Create a persistent link request

POST

/link-requests

curl --request POST \
  --url https://api.banklink.co.za/v1/link-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "reference": "customer-4821", "name": "Customer 4821 onboarding", "bank_id": "fnb", "return_options": { "dateFrom": "2026-08-01", "dateTo": "2026-08-31" }, "destinations": [ { "type": "webhook", "url": "https://example.co.za/banklink/callback" } ], "save_data": true, "expires_at": "2026-09-18T12:00:00.000Z", "redirect_url": "https://example.co.za/onboarding/bank-done" }'

• Production (use an sk_live_ key)
• Sandbox (same URL — use an sk_test_ key)

Creates a single-use hosted URL to send to your customer. Completing the link creates a reusable bank profile and stores encrypted credentials for later syncs. Set save_data: true to retain the fetched transactions in Banklink in addition to any webhook or email delivery.

Requires the link scope and a verified link profile. Test keys create a synthetic hosted link and do not contact a bank or external destination.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

reference

required

Your identifier, echoed in webhook payloads and request records

string

<= 200 characters

name

Optional internal label. Defaults to reference.

string

<= 200 characters

bank_id

Restrict the link to one bank, or omit to let the customer choose

string | null

Allowed values: fnb absa nedbank standard_bank discovery

return_options

object

dateFrom

string format: date

dateTo

string format: date

destinations

required

Webhook/email delivery targets. Link requests may use an empty array when save_data is true. Live webhook URLs must be https on your verified domain (or a subdomain); deliveries are signed.

Array

One of:

object

object

type

required

Allowed value: webhook

url

required

string format: uri

object

object

type

required

Allowed value: email

address

required

string format: email

save_data

Link requests only. Persist fetched transactions in Banklink.

boolean

expires_at

string | null format: date-time

redirect_url

Where to send the customer when they finish or cancel. https on your verified domain (test keys may also use http://localhost). Defaults to your link profile’s redirect URL. Banklink appends banklink_status (success, cancelled, expired, revoked, already_completed) and banklink_reference. Treat it as a UI hint; the signed webhook is the source of truth.

string | null format: uri

Example

{
  "reference": "customer-4821",
  "name": "Customer 4821 onboarding",
  "bank_id": "fnb",
  "return_options": {
    "dateFrom": "2026-08-01",
    "dateTo": "2026-08-31"
  },
  "destinations": [
    {
      "type": "webhook",
      "url": "https://example.co.za/banklink/callback"
    }
  ],
  "save_data": true,
  "expires_at": "2026-09-18T12:00:00.000Z",
  "redirect_url": "https://example.co.za/onboarding/bank-done"
}

Responses

201

Link request created

Media typeapplication/json

object

data

required

object

id

required

string format: uuid

reference

required

string

token

required

Opaque single-use token embedded in the hosted URL

string

url

required

string format: uri

status

required

string

Allowed values: pending completed expired revoked

bank_id

string | null

return_options

object

destinations

required

Array<object>

object

kind

string

Allowed values: link access

name

string

save_data

Present on link requests

boolean

redirect_url

string | null format: uri

expires_at

string | null format: date-time

completed_at

string | null format: date-time

last_error

Why the customer’s last attempt failed, while the request is pending

string | null

delivery_error

Set when the bank fetch succeeded but a webhook/email delivery failed

string | null

created_at

required

string format: date-time

Example

{
  "data": {
    "status": "pending",
    "kind": "link"
  }
}

400

Invalid request configuration

Media typeapplication/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

Human-readable error description

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Account not found"
  }
}

401

Missing or invalid API key

Media typeapplication/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

Human-readable error description

string

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

403

The organisation’s link profile isn’t verified yet

Media typeapplication/json

object

error

required

object

code

required

Machine-readable error code

string

message

required

Human-readable error description

string

Example

{
  "error": {
    "code": "org_not_verified",
    "message": "Verify your organisation's link profile before creating link or access requests: https://app.banklink.co.za/?page=link-requests"
  }
}