Bank linking — start (Plaid)

post

https://sandbox-api-gtw.softpoint.io/api/{version}/customers/{customer_id}/bank-linking-sessions

This API is used to start saving a bank account: the customer logs in to their bank on a hosted page (Plaid) and picks an account.

It returns a session_id and a hosted_link_url. Send the customer to hosted_link_url; when they finish they return to redirect_uri. Then call Bank linking — status with the session_id to get the saved account.

Note: The location must have bank linking (Plaid) enabled. Customer data comes from the profile; fields in the body override it. Which fields are required depends on the location setup; missing ones return 422 with the field names.

URL

{{interface_url}}/{{version}}/customers/{{customer_id}}/bank-linking-sessions

Method

POST

Headers

Authorization: Bearer {access_token} (or Api-Key)

Request Parameters

Field	Type	Required	Description
redirect_uri	String	No	HTTPS URL where the customer returns after linking.
first_name / last_name	String	No	Max 64. Default: profile.
email	String	No	Default: profile.
phone	String	No	7-15 digits. Default: profile.
date_of_birth	String	No	`YYYY-MM-DD`.
address.line1	String	No	Max 100. Default: profile.
address.city	String	No	Max 64.
address.state	String	No	State code (e.g. `TX`). Default: profile state.
address.zipcode	String	No	Max 20.
location_id	Integer	Conditional	Location to use. Required when the token covers more than one location (corporate / sub corporate); with a location token it is taken from the token.

URL Parameters

Parameter	Required/Optional	Type	Description
customer_id	Required	Integer	Our customer ID (`id` returned by Create customer).

Example Request (cURL)

curl --location --request POST '{{interface_url}}/{{version}}/customers/{{customer_id}}/bank-linking-sessions' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "location_id": 279685,
  "redirect_uri": "https://example.com/bank-linked",
  "date_of_birth": "1990-01-31",
  "address": {
    "line1": "100 Main St",
    "city": "Austin",
    "state": "TX",
    "zipcode": "78701"
  }
}'

Example Response (JSON) — 201

{
  "session_id": 123,
  "location_id": 279685,
  "hosted_link_url": "https://hosted.plaid.com/link/...",
  "expires_at": "2026-11-05T18:46:18Z",
  "status": "pending"
}

Error Responses

Format: { "error": { "code", "name", "message", "details" } }

Status	Error	When
400	bank_linking_not_enabled	The location has no bank linking.
422	invalid_parameter_value	A field the location requires is missing (see `error.details`).
404	customer_not_found	The customer is not linked to that location.
502	gateway_unavailable	The gateway did not answer. Retry.

Response

200OK