v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB

External Accounts

Create external account

Create an external account, which relates to an existing active account holder.

post/external_accounts

Request body

type'individual' | 'legal_entity'

The type of the external account.

namestring

The name of the external account.

holder_namestring required

The name of the legal entity or individual holding the account.

account_numberstring required

The account number.

account_number_format'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other'

The format of the account number. When set, it must match account_number unless the format is other or tokenized.

bank_codestring required

The bank code, for instance BIC / Swift code, UK sort code, or US routing number.

bank_code_format'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other'

The format of the bank code. When set, it must match bank_code unless the format is other or tokenized.

account_holder_idstring

The ID of the related account holder. It must not be disabled.

company_registration_numberstring

The company registration number of the external account, when type = legal_entity.

The type of the external account's company registration number, when type = legal_entity.

bank_namestring

The name of the bank holding the account.

accept_duplicate_account_numberboolean

Controls whether duplicate account detection includes the account holder's name as part of the uniqueness check.

If false (default), the API will return an error if an active external_account already exists with the same account_number and bank_code.
If true, the error is only triggered when an active external_account matches on account_number, bank_code, and holder_name, allowing duplicate account numbers across different holders.

metadataobject

Additional client data in JSON format. See Metadata.

custom_fieldsCommonCustomFields

Custom fields in JSON key:value format. See Custom fields.

Example request

{
  "holder_name": "PartnerCo SAS",
  "account_number": "FR7601234567891127967100082",
  "bank_code": "BNPAFRPPXXX",
  "account_holder_id": "0b441172-4945-11ed-b878-0242ac120002",
  "organization_identification": {
    "legal_entity_identifier": "529900T8BM49AURSDO55",
    "business_identification_code": "SOMEBIC0XXX",
    "default_other_identifier_type": "siren",
    "others": [
      {
        "type": "siren",
        "value": "901250746"
      }
    ]
  },
  "holder_address": {
    "line_1": "1, rue de la Bourse",
    "building_number": "1",
    "street_name": "rue de la Bourse",
    "postal_code": "59000",
    "city": "Lille",
    "country": "FR"
  },
  "bank_name": "BankCo",
  "bank_address": {
    "line_1": "1, place de la Concorde",
    "building_number": "1",
    "street_name": "place de la Concorde",
    "postal_code": "75008",
    "city": "Paris",
    "country": "FR",
    "department": "Marketing",
    "sub_department": "Content team",
    "building_name": "Bat. 4",
    "floor": "3",
    "postal_box": "67b",
    "room": "47",
    "city_location_name": "Confluences",
    "district_name": "District 9"
  },
  "metadata": {
    "property_a": true,
    "property_b": "some text"
  }
}

Response

200

idstring uuid required

The UUID of the external account.

objectstring required

Type of the object, external_account.

type'individual' | 'legal_entity'

The type of the external account.

namestring

The name of the external account.

holder_namestring required

The name of the legal entity or individual holding the account.

account_numberstring required

The account number.

account_number_format'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other'

The format of the account number.

account_holder_idstring required

The ID of the related account holder.

company_registration_numberstring

The company registration number of the external account, when type = legal_entity.

The type of the external account's company registration number, when type = legal_entity.

bank_codestring required

The bank code. For example, a BIC or SWIFT code.

bank_code_format'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other'

The format of the bank code.

bank_namestring

The name of the bank holding the account.

status'pending_approval' | 'approved' | 'denied' | 'disabled' required

The status of this external account.

status_detailsstring required

The details of the status of this external account.

created_atstring date-time required

The UTC timestamp of the creation of this external account.

disabled_atstring date-time

The UTC timestamp of the disabling of this external account.

metadataobject

Additional client data in JSON format. See Metadata.

custom_fieldsCommonCustomFields required

Custom fields in JSON key:value format. See Custom fields.

Example response

{
  "object": "external_account",
  "holder_name": "Joe Black",
  "account_number": "FR1420041010050500013M02606",
  "organization_identification": {
    "legal_entity_identifier": "529900T8BM49AURSDO55",
    "business_identification_code": "SOMEBIC0XXX",
    "default_other_identifier_type": "siren",
    "others": [
      {
        "type": "siren",
        "value": "901250746"
      }
    ]
  },
  "bank_code": "BNPAFRPPXXX",
  "holder_address": {
    "line_1": "1, rue de la Bourse",
    "building_number": "1",
    "street_name": "rue de la Bourse",
    "postal_code": "59000",
    "city": "Lille",
    "country": "FR"
  },
  "bank_name": "BankCo",
  "bank_address": {
    "line_1": "1, place de la Concorde",
    "building_number": "1",
    "street_name": "place de la Concorde",
    "postal_code": "75008",
    "city": "Paris",
    "country": "FR",
    "department": "Marketing",
    "sub_department": "Content team",
    "building_name": "Bat. 4",
    "floor": "3",
    "postal_box": "67b",
    "room": "47",
    "city_location_name": "Confluences",
    "district_name": "District 9"
  },
  "account_verification": {
    "result": "valid",
    "valid_account_number": {
      "result": "valid",
      "details": {
        "reason": "unauthorized_characters",
        "expected_value": "SOMEBIC0XXX",
        "message": "IBAN contains unauthorized characters"
      }
    },
    "matching_account_number_and_bank_code": {
      "result": "valid",
      "details": {
        "reason": "unauthorized_characters",
        "expected_value": "SOMEBIC0XXX",
        "message": "IBAN contains unauthorized characters"
      }
    },
    "matching_account_holder": {
      "result": "valid",
      "details": {
        "reason": "unauthorized_characters",
        "expected_value": "SOMEBIC0XXX",
        "message": "IBAN contains unauthorized characters"
      }
    },
    "active_account": {
      "result": "valid",
      "details": {
        "reason": "unauthorized_characters",
        "expected_value": "SOMEBIC0XXX",
        "message": "IBAN contains unauthorized characters"
      }
    }
  },
  "metadata": {
    "property_a": true,
    "property_b": "some text"
  }
}