Skip to content
/
Retrieve Counterparty

rail API Specification (1.1.2)

Welcome to the rail Developer Guide!

Download OpenAPI description
rail-spec.json
rail-spec.yaml
Languages
Servers
Mock server

https://docs.rail.io/_mock/api-docs/openapi/rail-spec/

Sandbox - Stable API Instance

https://sandbox.layer2financial.com/api/

Production - Stable API Instance

https://platform.layer2financial.com/api/

Applications

Applications represent the onboarding journey for your customers. They are used to collect KYC information and documents required to open accounts on the platform. Visit our guides for a detailed understanding on how to use these APIs.

Operations

Accounts

Accounts are used to hold funds on the platform. Once a customer is onboarded via the application process, you can create accounts for them in various currencies.

Operations

Counterparties

Counterparties represent external entities that you may wish to send or receive funds from. All counterparties are verified to ensure compliance with regulatory requirements prior to being available for use for withdrawals.

Operations

Retrieve Counterparties

Request

Retrieves a list of counterparties given the filter parameters provided

Security
OAuth2Flow
Query
pageinteger(int32)

Page of records to get (default 0 = first page)

page_sizeinteger(int32)

Records to return per page (default = 20)

customer_idstring

Customer ID to whom the counterparty belongs

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

curl -i -X GET \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/counterparties?page=0&page_size=0&customer_id=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/json
dataobject(CounterpartyList)required
data.​counterpartiesArray of objects(CounterParty)required

Counterparty List

data.​counterparties[].​idstringread-only

Unique Identifier for the counter party

data.​counterparties[].​customer_idstringrequired

The customer to which this counter party will be registered for use.

data.​counterparties[].​descriptionstring

Description of the counterparty.

data.​counterparties[].​counterparty_typestringrequired

The type of counterparty will determine the available rails for sending or receiving funds. See the guides for more detailed explanation of counterparty types.

Enum"FIAT_US""FIAT_US_LINKED""FIAT_CA""FIAT_CA_LINKED""CRYPTO"
Discriminator
data.​counterparties[].​statusstringread-onlyrequired

Counterparty status determines options available for use on the counterparty.

  • ACTIVE - Counterparty is open and available for use for withdrawal or deposits
  • CLOSED - Counterparty is permanently closed, no further actions can be performed on the Counterparty.
  • PENDING - Counterparty is under additional review prior to moving to the OPEN or CLOSED state. No actions can be performed on the Counterparty in this state
  • FROZEN - Counterparty has been temporarily locked for all actions.
  • EDD - Counterparty requires enhanced due diligence to be performed. The counterparty will operate as if active but may transition to FROZEN or CLOSED post due-diligence.
  • DORMANT - No activity has been seen in the last 12 months. The counterparty is available for use.
Enum"ACTIVE""CLOSED""FROZEN""PENDING""EDD""DORMANT"
data.​counterparties[].​supported_railsArray of stringsrequired

The rails required for this counterparty. Rail selection will determine data requirements. See guides for full breakdowns.

Items Enum"ACH""FEDWIRE""SWIFT"
data.​counterparties[].​profileobject(CounterPartyProfileFIATUS)required

Details of the counter party account holder. Required fields are determined by the combination of required rails. See the API Guides for a full documented breakdown of required fields.

data.​counterparties[].​profile.​profile_typestringrequired

The profile type of the counterparty sending/receiving these funds.

Enum"INDIVIDUAL""CORPORATION"
data.​counterparties[].​profile.​namestringrequired

Name of the counterparty (individual or business name). Should match the name on the destination account if sending funds.

data.​counterparties[].​profile.​emailstring

The email address of the counterparty who is sending/receiving these funds.

data.​counterparties[].​profile.​telephone_numberstring

The Telephone Number in E.164 format of the counterparty who is sending/receiving these funds.

data.​counterparties[].​profile.​tax_reference_numberstring

The tax reference number of the counterparty who is sending/receiving these funds. (Corporations - EIN, FEIN, TIN, etc. / Individuals = SSN, ITIN, SIN, National Insurance Number etc). For large value payments, providing this info can significantly streamline processing times.

data.​counterparties[].​profile.​date_of_birthstring(date)

RFC3339 (YYYY-MM-DD) Date of Birth of the counterparty if they are an individual.

data.​counterparties[].​profile.​addressobject(AddressProfileStateRequired)required

Address of the counterparty (individual or business name)

data.​counterparties[].​profile.​address.​unit_numberstring

Unit Number

data.​counterparties[].​profile.​address.​address_line1string

Address Line 1

data.​counterparties[].​profile.​address.​address_line2string

Address Line 2

data.​counterparties[].​profile.​address.​address_line3string

Address Line 3

data.​counterparties[].​profile.​address.​citystring

City

data.​counterparties[].​profile.​address.​statestringrequired

State / Province (2 Digit subdivision component of the ISO 3166-2 code, which consists of the last two characters. https://en.wikipedia.org/wiki/ISO_3166-2

data.​counterparties[].​profile.​address.​postal_codestring

Postal / Zip Code

data.​counterparties[].​profile.​address.​country_codestringrequired

Country Code (2 Digit ISO31661-Alpha2 Format - https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

data.​counterparties[].​profile.​line_of_businessstring

Line of Business of the counterparty (if they are a business)

Enum"ARTS_AND_ANTIQUES""AGRICULTURE""AUDIT_VIDEO""AUTOMOTIVE""BANK_CREDIT_UNION""BIOTECH_PHARMACEUTICAL""BOOKSELLER""CONSTRUCTION""CASINOS_GAMBLING""CLOTHING"
data.​counterparties[].​profile.​relationship_to_customerstring

Relationship of the customer to the counterparty

Enum"SPOUSE""EX_SPOUSE""CHILDREN""PARENT""SIBLING""RELATIVE""SELF""FRIEND""BUSINESS_PARTNER""CUSTOMER"
data.​counterparties[].​account_informationobject(CounterPartyAccountFIATUS)required

Details of the counter party account and institution. Required fields are determined by the combination of required needed rails. See the API Guides for a full documented breakdown of required fields.

data.​counterparties[].​account_information.​asset_type_idstring

Destination asset type. Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
data.​counterparties[].​account_information.​account_numberstringrequired

Counterparty account number

data.​counterparties[].​account_information.​typestring

Counterparty account type.

Enum"CHECKING""SAVING"
data.​counterparties[].​account_information.​routing_numberstringrequired

Counterparty routing number

data.​counterparties[].​account_information.​swift_bicstring

Counterparty SWIFT/BIC Number

data.​counterparties[].​account_information.​institution_namestring

Institution Name (e.g. Bank of America)

data.​counterparties[].​account_information.​institution_addressobject(institution_address)

Address of institution

data.​counterparties[].​intermediary_informationobject(CounterPartyIntermediary)

Optional details of the intermediary (correspondent bank) institution when sending SWIFT payments. SWIFT must be added to the support_rail list in order to provide an intermediary

linksobject(Page)required

See the pagination section for additional details on the generic pagination approach.

links.​selfstringrequired

endpoint to the current page of results

links.​firststringrequired

endpoint to the first page of results

links.​prevstringrequired

endpoint to the previous page of results

links.​nextstringrequired

endpoint to the next page of results

links.​laststringrequired

endpoint to the last page of results

Response
application/json
{
  "data": {
    "counterparties": [ … ]
  },
  "links": {
    "self": "string",
    "first": "string",
    "prev": "string",
    "next": "string",
    "last": "string"
  }
}

Create Counterparty

Request

Create a new counterparty for the purpose of pulling funds into the platform or pushing out

Security
OAuth2Flow
Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

Bodyapplication/jsonrequired
customer_idstringrequired

The customer to which this counter party will be registered for use.

descriptionstring

Description of the counterparty.

counterparty_typestringrequired

The type of counterparty will determine the available rails for sending or receiving funds. See the guides for more detailed explanation of counterparty types.

Enum"FIAT_US""FIAT_US_LINKED""FIAT_CA""FIAT_CA_LINKED""CRYPTO"
Discriminator
supported_railsArray of stringsrequired

The rails required for this counterparty. Rail selection will determine data requirements. See guides for full breakdowns.

Items Enum"ACH""FEDWIRE""SWIFT"
profileobject(CounterPartyProfileFIATUS)required

Details of the counter party account holder. Required fields are determined by the combination of required rails. See the API Guides for a full documented breakdown of required fields.

profile.​profile_typestringrequired

The profile type of the counterparty sending/receiving these funds.

Enum"INDIVIDUAL""CORPORATION"
profile.​namestringrequired

Name of the counterparty (individual or business name). Should match the name on the destination account if sending funds.

profile.​emailstring

The email address of the counterparty who is sending/receiving these funds.

profile.​telephone_numberstring

The Telephone Number in E.164 format of the counterparty who is sending/receiving these funds.

profile.​tax_reference_numberstring

The tax reference number of the counterparty who is sending/receiving these funds. (Corporations - EIN, FEIN, TIN, etc. / Individuals = SSN, ITIN, SIN, National Insurance Number etc). For large value payments, providing this info can significantly streamline processing times.

profile.​date_of_birthstring(date)

RFC3339 (YYYY-MM-DD) Date of Birth of the counterparty if they are an individual.

profile.​addressobject(AddressProfileStateRequired)required

Address of the counterparty (individual or business name)

profile.​address.​unit_numberstring

Unit Number

profile.​address.​address_line1string

Address Line 1

profile.​address.​address_line2string

Address Line 2

profile.​address.​address_line3string

Address Line 3

profile.​address.​citystring

City

profile.​address.​statestringrequired

State / Province (2 Digit subdivision component of the ISO 3166-2 code, which consists of the last two characters. https://en.wikipedia.org/wiki/ISO_3166-2

profile.​address.​postal_codestring

Postal / Zip Code

profile.​address.​country_codestringrequired

Country Code (2 Digit ISO31661-Alpha2 Format - https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

profile.​line_of_businessstring

Line of Business of the counterparty (if they are a business)

Enum"ARTS_AND_ANTIQUES""AGRICULTURE""AUDIT_VIDEO""AUTOMOTIVE""BANK_CREDIT_UNION""BIOTECH_PHARMACEUTICAL""BOOKSELLER""CONSTRUCTION""CASINOS_GAMBLING""CLOTHING"
profile.​relationship_to_customerstring

Relationship of the customer to the counterparty

Enum"SPOUSE""EX_SPOUSE""CHILDREN""PARENT""SIBLING""RELATIVE""SELF""FRIEND""BUSINESS_PARTNER""CUSTOMER"
account_informationobject(CounterPartyAccountFIATUS)required

Details of the counter party account and institution. Required fields are determined by the combination of required needed rails. See the API Guides for a full documented breakdown of required fields.

account_information.​asset_type_idstring

Destination asset type. Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
account_information.​account_numberstringrequired

Counterparty account number

account_information.​typestring

Counterparty account type.

Enum"CHECKING""SAVING"
account_information.​routing_numberstringrequired

Counterparty routing number

account_information.​swift_bicstring

Counterparty SWIFT/BIC Number

account_information.​institution_namestring

Institution Name (e.g. Bank of America)

account_information.​institution_addressobject(institution_address)

Address of institution

intermediary_informationobject(CounterPartyIntermediary)

Optional details of the intermediary (correspondent bank) institution when sending SWIFT payments. SWIFT must be added to the support_rail list in order to provide an intermediary

curl -i -X POST \
  https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/counterparties \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -d '{
    "customer_id": "string",
    "description": "string",
    "counterparty_type": "FIAT_US",
    "supported_rails": [
      "ACH"
    ],
    "profile": {
      "profile_type": "INDIVIDUAL",
      "name": "string",
      "email": "string",
      "telephone_number": "string",
      "tax_reference_number": "string",
      "date_of_birth": "2019-08-24",
      "address": {
        "unit_number": "string",
        "address_line1": "string",
        "address_line2": "string",
        "address_line3": "string",
        "city": "string",
        "state": "string",
        "postal_code": "string",
        "country_code": "string"
      },
      "line_of_business": "ARTS_AND_ANTIQUES",
      "relationship_to_customer": "SPOUSE"
    },
    "account_information": {
      "asset_type_id": "string",
      "account_number": "string",
      "type": "CHECKING",
      "routing_number": "string",
      "swift_bic": "string",
      "institution_name": "string",
      "institution_address": {
        "unit_number": "string",
        "address_line1": "string",
        "address_line2": "string",
        "address_line3": "string",
        "city": "string",
        "state": "string",
        "postal_code": "string",
        "country_code": "string"
      }
    },
    "intermediary_information": {
      "intermediary_type": "FIAT_US",
      "institution_name": "string",
      "institution_address": {
        "unit_number": "string",
        "address_line1": "string",
        "address_line2": "string",
        "address_line3": "string",
        "city": "string",
        "state": "string",
        "postal_code": "string",
        "country_code": "string"
      }
    }
  }'

Responses

Success

Bodyapplication/json
dataobject(CounterPartyBase)required
data.​idstringread-only

Unique Identifier for the counter party

Response
application/json
{
  "data": {
    "id": "string"
  }
}

Retrieve Linking Details

Request

Retrieve the linking instructions for embedding in a UI to launch account linking from providers such as MX or Plaid.

Security
OAuth2Flow
Path
idstringrequired

Counterparty ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

Bodyapplication/jsonrequired
linking_providerstringrequired

The provider for which linking instructions are required.

Enum"MX""PLAID"
Discriminator
is_mobile_webviewbooleanrequired

Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages.

ui_message_webview_url_schemestringrequired

Used as a redirect destination at the end of OAuth,

curl -i -X POST \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/counterparties/{counterparty_id}/link/details' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -d '{
    "linking_provider": "MX",
    "is_mobile_webview": true,
    "ui_message_webview_url_scheme": "string"
  }'

Responses

Success

Bodyapplication/json
linking_providerstringrequired

The provider for which linking instructions are required.

Enum"MX""PLAID"
Discriminator
is_mobile_webviewbooleanrequired

Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages.

ui_message_webview_url_schemestringrequired

Used as a redirect destination at the end of OAuth,

mx_widget_urlstringread-onlyrequired

Single use MX widget URLs for use in the front end. You must fetch a new widget URL each time you load the widget.

Response
application/json
{
  "linking_provider": "MX",
  "is_mobile_webview": true,
  "ui_message_webview_url_scheme": "string",
  "mx_widget_url": "string"
}

Connect Linked Account

Request

Established the connection between a counterparty and external linked account.

Security
OAuth2Flow
Path
idstringrequired

Counterparty ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

Bodyapplication/jsonrequired
linking_providerstringrequired

The provider for which linking instructions are required.

Enum"MX""PLAID"
Discriminator
account_link_idstringrequired

Establish a connections to an account taken from the /link/accounts call

curl -i -X POST \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/counterparties/{counterparty_id}/link/connect' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -d '{
    "linking_provider": "MX",
    "account_link_id": "string"
  }'

Responses

Success

Bodyapplication/json
dataobject(CounterPartyBase)required
data.​idstringread-only

Unique Identifier for the counter party

Response
application/json
{
  "data": {
    "id": "string"
  }
}

Retrieve Linkable Accounts

Request

Retrieve the accounts that are available for linking for a LINKED counterparty via a provider such as MX or Plaid.

Security
OAuth2Flow
Path
idstringrequired

Counterparty ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

Bodyapplication/jsonrequired
linking_providerstringrequired

Which provider was used when generating linking instructions

Enum"MX""PLAID"
Discriminator
member_guidstringrequired

The member_guid from the mx/connect/memberConnected event generated in the UI by the mx widget

curl -i -X POST \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/counterparties/{counterparty_id}/link/accounts' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -d '{
    "linking_provider": "MX",
    "member_guid": "string"
  }'

Responses

Success

Bodyapplication/json
linking_providerstringrequired

Which provider was used when generating linking instructions

Enum"MX""PLAID"
Discriminator
member_guidstringrequired

The member_guid from the mx/connect/memberConnected event generated in the UI by the mx widget

available_accountsArray of objects(CounterPartyLinkingAccountsMXAbbrev)read-onlyrequired

The list of accounts that are available for linking. Use the connect operation to connect the desired account from this list with the counterparty

available_accounts[].​account_link_idstringrequired

Unique ID for this account required when finalising the connection

available_accounts[].​account_namestringrequired

Account name

available_accounts[].​account_numberstringrequired

Abbreviated account number (e.g. last 4 characters)

Response
application/json
{
  "linking_provider": "MX",
  "member_guid": "string",
  "available_accounts": [
    { … }
  ]
}

Retrieve Counterparty

Request

Retrieves a list of counterparties given the filter parameters provided

Security
OAuth2Flow
Path
idstringrequired

Counterparty ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

curl -i -X GET \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/counterparties/{counterparty_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string'

Responses

Success

Bodyapplication/json
dataobject(CounterParty)required
data.​idstringread-only

Unique Identifier for the counter party

data.​customer_idstringrequired

The customer to which this counter party will be registered for use.

data.​descriptionstring

Description of the counterparty.

data.​counterparty_typestringrequired

The type of counterparty will determine the available rails for sending or receiving funds. See the guides for more detailed explanation of counterparty types.

Enum"FIAT_US""FIAT_US_LINKED""FIAT_CA""FIAT_CA_LINKED""CRYPTO"
Discriminator
data.​statusstringread-onlyrequired

Counterparty status determines options available for use on the counterparty.

  • ACTIVE - Counterparty is open and available for use for withdrawal or deposits
  • CLOSED - Counterparty is permanently closed, no further actions can be performed on the Counterparty.
  • PENDING - Counterparty is under additional review prior to moving to the OPEN or CLOSED state. No actions can be performed on the Counterparty in this state
  • FROZEN - Counterparty has been temporarily locked for all actions.
  • EDD - Counterparty requires enhanced due diligence to be performed. The counterparty will operate as if active but may transition to FROZEN or CLOSED post due-diligence.
  • DORMANT - No activity has been seen in the last 12 months. The counterparty is available for use.
Enum"ACTIVE""CLOSED""FROZEN""PENDING""EDD""DORMANT"
data.​supported_railsArray of stringsrequired

The rails required for this counterparty. Rail selection will determine data requirements. See guides for full breakdowns.

Items Enum"ACH""FEDWIRE""SWIFT"
data.​profileobject(CounterPartyProfileFIATUS)required

Details of the counter party account holder. Required fields are determined by the combination of required rails. See the API Guides for a full documented breakdown of required fields.

data.​profile.​profile_typestringrequired

The profile type of the counterparty sending/receiving these funds.

Enum"INDIVIDUAL""CORPORATION"
data.​profile.​namestringrequired

Name of the counterparty (individual or business name). Should match the name on the destination account if sending funds.

data.​profile.​emailstring

The email address of the counterparty who is sending/receiving these funds.

data.​profile.​telephone_numberstring

The Telephone Number in E.164 format of the counterparty who is sending/receiving these funds.

data.​profile.​tax_reference_numberstring

The tax reference number of the counterparty who is sending/receiving these funds. (Corporations - EIN, FEIN, TIN, etc. / Individuals = SSN, ITIN, SIN, National Insurance Number etc). For large value payments, providing this info can significantly streamline processing times.

data.​profile.​date_of_birthstring(date)

RFC3339 (YYYY-MM-DD) Date of Birth of the counterparty if they are an individual.

data.​profile.​addressobject(AddressProfileStateRequired)required

Address of the counterparty (individual or business name)

data.​profile.​address.​unit_numberstring

Unit Number

data.​profile.​address.​address_line1string

Address Line 1

data.​profile.​address.​address_line2string

Address Line 2

data.​profile.​address.​address_line3string

Address Line 3

data.​profile.​address.​citystring

City

data.​profile.​address.​statestringrequired

State / Province (2 Digit subdivision component of the ISO 3166-2 code, which consists of the last two characters. https://en.wikipedia.org/wiki/ISO_3166-2

data.​profile.​address.​postal_codestring

Postal / Zip Code

data.​profile.​address.​country_codestringrequired

Country Code (2 Digit ISO31661-Alpha2 Format - https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

data.​profile.​line_of_businessstring

Line of Business of the counterparty (if they are a business)

Enum"ARTS_AND_ANTIQUES""AGRICULTURE""AUDIT_VIDEO""AUTOMOTIVE""BANK_CREDIT_UNION""BIOTECH_PHARMACEUTICAL""BOOKSELLER""CONSTRUCTION""CASINOS_GAMBLING""CLOTHING"
data.​profile.​relationship_to_customerstring

Relationship of the customer to the counterparty

Enum"SPOUSE""EX_SPOUSE""CHILDREN""PARENT""SIBLING""RELATIVE""SELF""FRIEND""BUSINESS_PARTNER""CUSTOMER"
data.​account_informationobject(CounterPartyAccountFIATUS)required

Details of the counter party account and institution. Required fields are determined by the combination of required needed rails. See the API Guides for a full documented breakdown of required fields.

data.​account_information.​asset_type_idstring

Destination asset type. Asset type IDs follow a simple structure as follows: {$BLOCKCHAIN}_{$NETWORK}_{$CURRENCY_CODE} Simple asset type to test with include

  • ETHEREUM_SEPOLIA_ETH
  • ETHEREUM_SEPOLIA_USDC
  • SOLANA_DEVNET_SOL
  • BITCOIN_TESTNET_BTC
  • FIAT_TESTNET_USD
  • FIAT_TESTNET_USD
  • FIAT_MAINNET_USD
  • FIAT_TESTNET_EUR
data.​account_information.​account_numberstringrequired

Counterparty account number

data.​account_information.​typestring

Counterparty account type.

Enum"CHECKING""SAVING"
data.​account_information.​routing_numberstringrequired

Counterparty routing number

data.​account_information.​swift_bicstring

Counterparty SWIFT/BIC Number

data.​account_information.​institution_namestring

Institution Name (e.g. Bank of America)

data.​account_information.​institution_addressobject(institution_address)

Address of institution

data.​intermediary_informationobject(CounterPartyIntermediary)

Optional details of the intermediary (correspondent bank) institution when sending SWIFT payments. SWIFT must be added to the support_rail list in order to provide an intermediary

Response
application/json
{
  "data": {
    "id": "string",
    "customer_id": "string",
    "description": "string",
    "counterparty_type": "FIAT_US",
    "status": "ACTIVE"
  }
}

Update Counterparty

Request

Update Counterparty details. There are limits to what can be updated once the counterparty has been approved for use.

Security
OAuth2Flow
Path
idstringrequired

Counterparty ID

Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

Optional Unique ID per request, useful for fault resolution/diagnosis and audit.

x-l2f-idempotency-idstring

Unique ID used to safely retry an operation. See idempotency section for more details.

Bodyapplication/jsonrequired
updatesArray of objects(PatchCounterparty)

Follow standard patch guidance

updated_bystring

Description or reference of the system/person who requested the change

reasonstring

String representing the reason for the change.

curl -i -X PATCH \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/counterparties/{counterparty_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-l2f-idempotency-id: string' \
  -H 'x-l2f-request-id: string' \
  -d '{
    "updates": [
      {
        "field": "string",
        "value": "string"
      }
    ],
    "updated_by": "string",
    "reason": "string"
  }'

Responses

Success

Bodyapplication/json
dataobject(CounterPartyBase)required
data.​idstringread-only

Unique Identifier for the counter party

Response
application/json
{
  "data": {
    "id": "string"
  }
}

Customers

Customers can only be created via the application process. Once created, customers can have multiple accounts associated with them.

Operations

Deposits

Deposits are used to request instructions for funding platform managed accounts from external sources. A given account may have many deposits associated with it depending on the supported rails and configurations.

Operations

Documents

Document uploading and management functions.

Operations

Exchanges

Exchanges are used to convert funds from one currency to another. This is achieved by moving money between 2 platform accounts that are denominated in different currencies. We have eliminated the complexity of traditional currency trading.

Operations

Payments

Payments are used to orchestrate end to end payment flows from external parties or from within the platform.

Operations

Transactions

Transactions are created to record the movement of funds between accounts. The transactions endpoint allows the bulk retrieval of transaction data for reconciliation and reporting purposes.

Operations

Transfers

Transfer are used to move funds between two platform managed accounts that are denominated in the same currency.

Operations

Withdrawals

Move funds from a platform managed account to an external counterparty via supported rails.

Operations

Settlements

Settlement services for funds confirmation and reconciliation. Settlements are a deprecated concept and will be removed in future versions of the API. Please use Payments for all new integrations.

Operations

Subscriptions (Webhooks)

Manage your callback (webhook) subscriptions. Subscriptions allow you to receive real-time notifications of events that occur within your platform instance. Visit the guides for a full breakdown of all available events.

Operations
© 2026 Rail. All Rights Reserved.