Link a bank account

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/bank-accounts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "accountHolderName": "Alice Doe",
  "beneficiaryType": "individual",
  "country": "US",
  "currency": "USD",
  "bankName": "Example Bank",
  "accountNumber": "000123456789",
  "accountType": "checking",
  "routing": {
    "type": "aba",
    "routingNumber": "021000021"
  },
  "rail": "ach",
  "beneficiaryAddress": {
    "street1": "1 Market Street",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "bankAddress": {
    "street1": "270 Park Avenue",
    "city": "New York",
    "region": "NY",
    "postalCode": "10017",
    "country": "US"
  }
}
'

{
  "bankAccount": {
    "id": "bank_account_123",
    "accountId": "acct_123",
    "accountHolderName": "Alice Doe",
    "country": "US",
    "currency": "USD",
    "bankName": "Example Bank",
    "accountNumberLast4": "1234",
    "rail": "ach",
    "status": "active",
    "verification": {
      "version": 1,
      "verifiedAt": "2026-09-01T10:00:00.000Z"
    },
    "disabledAt": null,
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "settlementDestination": {
    "id": "destination_123",
    "accountId": "acct_123",
    "type": "bank_account",
    "status": "restricted",
    "preferred": false,
    "capabilities": {
      "directions": [
        "receive"
      ],
      "settlementSupported": false,
      "unavailableReason": "linked_bank_receive_settlement_not_enabled",
      "country": "US",
      "currency": "USD",
      "rail": "ach"
    },
    "resource": {
      "type": "bank_account",
      "bankAccount": {
        "id": "bank_account_123",
        "accountId": "acct_123",
        "accountHolderName": "Alice Doe",
        "country": "US",
        "currency": "USD",
        "bankName": "Example Bank",
        "accountNumberLast4": "1234",
        "rail": "ach",
        "status": "active",
        "verification": {
          "version": 1,
          "verifiedAt": "2026-09-01T10:00:00.000Z"
        },
        "disabledAt": null,
        "createdAt": "2026-08-28T10:00:00.000Z",
        "updatedAt": "2026-08-28T10:00:00.000Z"
      }
    },
    "disabledAt": null,
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "provisioning": {
    "providerProvisioningCompleted": true,
    "settlementReady": false,
    "nextAction": {
      "type": "none"
    }
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

POST

accounts

{accountId}

bank-accounts

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/accounts/{accountId}/bank-accounts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "accountHolderName": "Alice Doe",
  "beneficiaryType": "individual",
  "country": "US",
  "currency": "USD",
  "bankName": "Example Bank",
  "accountNumber": "000123456789",
  "accountType": "checking",
  "routing": {
    "type": "aba",
    "routingNumber": "021000021"
  },
  "rail": "ach",
  "beneficiaryAddress": {
    "street1": "1 Market Street",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "bankAddress": {
    "street1": "270 Park Avenue",
    "city": "New York",
    "region": "NY",
    "postalCode": "10017",
    "country": "US"
  }
}
'

{
  "bankAccount": {
    "id": "bank_account_123",
    "accountId": "acct_123",
    "accountHolderName": "Alice Doe",
    "country": "US",
    "currency": "USD",
    "bankName": "Example Bank",
    "accountNumberLast4": "1234",
    "rail": "ach",
    "status": "active",
    "verification": {
      "version": 1,
      "verifiedAt": "2026-09-01T10:00:00.000Z"
    },
    "disabledAt": null,
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "settlementDestination": {
    "id": "destination_123",
    "accountId": "acct_123",
    "type": "bank_account",
    "status": "restricted",
    "preferred": false,
    "capabilities": {
      "directions": [
        "receive"
      ],
      "settlementSupported": false,
      "unavailableReason": "linked_bank_receive_settlement_not_enabled",
      "country": "US",
      "currency": "USD",
      "rail": "ach"
    },
    "resource": {
      "type": "bank_account",
      "bankAccount": {
        "id": "bank_account_123",
        "accountId": "acct_123",
        "accountHolderName": "Alice Doe",
        "country": "US",
        "currency": "USD",
        "bankName": "Example Bank",
        "accountNumberLast4": "1234",
        "rail": "ach",
        "status": "active",
        "verification": {
          "version": 1,
          "verifiedAt": "2026-09-01T10:00:00.000Z"
        },
        "disabledAt": null,
        "createdAt": "2026-08-28T10:00:00.000Z",
        "updatedAt": "2026-08-28T10:00:00.000Z"
      }
    },
    "disabledAt": null,
    "createdAt": "2026-08-28T10:00:00.000Z",
    "updatedAt": "2026-08-28T10:00:00.000Z"
  },
  "provisioning": {
    "providerProvisioningCompleted": true,
    "settlementReady": false,
    "nextAction": {
      "type": "none"
    }
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid",
    "details": "example"
  }
}

Read bank account requirements first for each country’s fields and current availability. Linking is implemented for the United States, the Philippines and Vietnam; the other country variants in the request schema describe planned inputs and stay unavailable. An individual UPA needs approved KYC. A business UPA can link a US/USD bank after hosted KYB and provider approval. Both require an enabled linked-bank route. A linked bank is a saved beneficiary and can belong to a supplier, contractor or the UPA subject. Linking does not prove ownership by the UPA subject.

Country	On link
US	Provisioned with the provider. Routing, account type and address fields are part of the encrypted payload.
PH	Stays pending verification. Bank directory membership never verifies account ownership.
VN	The beneficiary is verified with the provider.

All normalized bank details are stored with KMS-backed envelope encryption. Raw bank details and encrypted storage metadata are never returned. Linking does not enable payout or settlement execution. Idempotency-Key is required and must contain 1–256 characters after trimming surrounding whitespace. Preserve the original body and key after an uncertain response; changed input conflicts. See Off-ramps.

Authorizations

Authorization

string

header

required

HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin.

Headers

Idempotency-Key

string

required

Required retry key for linking a bank account or rail identifier: 1-256 characters after trimming surrounding whitespace. Retry the identical request with the same key; changed input returns a conflict.

Required string length: 1 - 256

Example:

"bank-beneficiary-supplier-123"

Stableyard-Version

enum<string>

Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated.

Available options:

2026-09-09

Path Parameters

accountId

string

required

Canonical account id returned by the Accounts API.

Example:

"acct_123"

Body

application/json

Country-specific bank inputs. Planned country profiles remain unavailable until their compatible provider adapter and route are enabled. Shortcut identifiers require separate rail integration.

country

string

required

Allowed value: "US"

currency

string

required

Allowed value: "USD"

accountHolderName

string

required

Required string length: 1 - 160

bankName

string

required

Required string length: 1 - 160

accountNumber

string

required

write-only

Required string length: 4 - 17

Pattern: ^[0-9]{4,17}$

accountType

enum<string>

required

Available options:

checking,

savings

routing

object

required

Show child attributes

beneficiaryAddress

Beneficiary address · object

required

Show child attributes

bankAddress

Bank address · object

required

Show child attributes

beneficiaryType

enum<string>

default:individual

Available options:

individual,

business

rail

enum<string>

default:ach

Available options:

ach,

fedwire,

fednow

Response

Linked bank account

bankAccount

object

required

Show child attributes

settlementDestination

object

required

Show child attributes

provisioning

object

required

Show child attributes

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Authorizations

Headers

Path Parameters

Body

Response