Skip to content
/
Retrieve Customer

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

Customers

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

Operations

Retrieve Customer

Request

Retrieve customer details

Security
OAuth2Flow
Path
idstringrequired

Customer 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.

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

Responses

Success

Bodyapplication/json
One of:
dataobject(IndividualCustomer)required
data.​idstringrequired

Unique Identifier for the customer

data.​customer_typestringrequired

Type of customer

Enum"INDIVIDUAL""CORPORATION"
Discriminator
data.​statusstringread-onlyrequired

Customer Status - will determine servicing options on the customer and the customers accounts.

  • ACTIVE - Customer is open and available for use in line with its product configuration
  • CLOSED - Customer is permanently closed, no further actions can be performed on the customer. All accounts associated to the customer will also be CLOSED
  • PENDING - Customer is under additional review prior to moving to the OPEN or CLOSED state. No actions can be performed on the customer or their respective accounts.
  • FROZEN - Customer has been temporarily locked for all actions. All accounts associated to the customer will also be FROZEN
  • EDD - Customer requires enhanced due diligence to be performed. The customer will operate as if frozen until transitioning to ACTIVE or CLOSED.
  • DORMANT - No activity has been seen in the last 12 months. The customer and their accounts are available for use.
Enum"ACTIVE""CLOSED""FROZEN""PENDING""EDD""DORMANT"
data.​first_namestringrequired

First name

data.​middle_namestring

Middle Name(s) (if present)

data.​last_namestringrequired

Last name

data.​email_addressstring

Email Address

data.​mailing_addressobject(mailing_address)

Mailing Address

data.​telephone_numberstring

Telephone Number in E.164 format

data.​tax_reference_numberstring

Tax reference number of the individual (SSN, ITIN, SIN, National Insurance Number etc)

data.​passport_numberstring

Passport Number

data.​nationalitystring

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

data.​citizenshipArray of strings

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

data.​date_of_birthstring(date)

RFC3339 (YYYY-MM-DD) Date of Birth

data.​us_residency_statusstring

US Residency Status

Enum"US_CITIZEN""RESIDENT_ALIEN""NON_RESIDENT_ALIEN"
data.​employment_statusstring

Employment Status

Enum"EMPLOYEE""SELF_EMPLOYED""RETIRED""UNEMPLOYED""OTHER"
data.​employment_descriptionstring

Employment (job) description.

data.​employer_namestring

Employer name

data.​occupationstring

Occupation

data.​investment_profileobject(ProfileIndividualInvesting)

Investment Profile of the Individual

data.​kyc_profileobject(ProfileIndividualKYC)

KYC Profile of the Individual

Response
application/json
{
  "data": {
    "id": "string",
    "customer_type": "INDIVIDUAL",
    "status": "ACTIVE",
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "email_address": "string",
    "mailing_address": { … },
    "telephone_number": "string",
    "tax_reference_number": "string",
    "passport_number": "string",
    "nationality": "string",
    "citizenship": [ … ],
    "date_of_birth": "2019-08-24",
    "us_residency_status": "US_CITIZEN",
    "employment_status": "EMPLOYEE",
    "employment_description": "string",
    "employer_name": "string",
    "occupation": "string",
    "investment_profile": { … },
    "kyc_profile": { … }
  }
}

Update Customer

Request

Update customer details. For individuals (officers) linked to a corporate customer, modify the individual resource directly using Update Individual.

Security
OAuth2Flow
Path
idstringrequired

Customer 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(PatchCustomer)

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/customers/{customer_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(CustomerBase)required
data.​idstringrequired

Unique Identifier for the customer

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

Retrieve Individual

Request

Retrieve individual details. This operation is only for corporate customers that have individual officers with access to the account

Security
OAuth2Flow
Path
idstringrequired

Corporate Customer ID. This operation can only be performed on corporate customers.

individual_idstringrequired

Individual 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.

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

Responses

Success

Bodyapplication/json
dataobject(Individual)read-onlyrequired

Beneficial Owners and Control Persons Associated to the corporation

data.​idstringread-onlyrequired

Unique ID of the Individual

data.​individual_typeArray of stringsrequired

Type of individual in the corporation

Items Enum"OFFICER""BENEFICIAL_OWNER""CONTROL_PERSON""AUTHORIZED_PERSON"
data.​first_namestringrequired

First name

data.​middle_namestring

Middle Name(s) (if present)

data.​last_namestringrequired

Last name

data.​email_addressstring

Email Address

data.​mailing_addressobject(mailing_address)

Mailing Address

data.​telephone_numberstring

Telephone Number in E.164 format

data.​tax_reference_numberstring

Tax reference number of the country (SSN, ITIN, SIN, National Insurance Number etc)

data.​tax_reference_number_countrystring

Registered tax reference number country (2 Digit ISO31661-Alpha2 Format - https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

data.​passport_numberstring

Passport Number

data.​nationalitystring

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

data.​citizenshipArray of strings

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

data.​date_of_birthstring(date)

RFC3339 (YYYY-MM-DD) Date of Birth

data.​percentage_ownershipinteger(int32)

(Only where type is BENEFICIAL_OWNER) Percentage ownership of the corporation (0 to 100)

data.​titlestring

Example values CEO, COO, CFO, President, BenefitsAdministrationOfficer, CIO, VP, AVP, Treasurer, Secretary, Controller, Manager, Partner or Member.

data.​us_residency_statusstring

US Residency Status

Enum"US_CITIZEN""RESIDENT_ALIEN""NON_RESIDENT_ALIEN"
Response
application/json
{
  "data": {
    "id": "string",
    "individual_type": [ … ],
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "email_address": "string",
    "mailing_address": { … },
    "telephone_number": "string",
    "tax_reference_number": "string",
    "tax_reference_number_country": "string",
    "passport_number": "string",
    "nationality": "string",
    "citizenship": [ … ],
    "date_of_birth": "2019-08-24",
    "percentage_ownership": 0,
    "title": "string",
    "us_residency_status": "US_CITIZEN"
  }
}

Update Individual

Request

Update individual details. This operation is only for corporate customers that have individual officers with access to the account

Security
OAuth2Flow
Path
idstringrequired

Customer ID

individual_idstringrequired

Individual 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(PatchGeneric)

Follow standard patch guidance

curl -i -X PATCH \
  'https://docs.rail.io/_mock/api-docs/openapi/rail-spec/v1/customers/{customer_id}/individuals/{individual_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"
      }
    ]
  }'

Responses

Success

Bodyapplication/json
dataobject(IndividualBase)required
data.​idstringread-onlyrequired

Unique ID of the Individual

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

Retrieve Customers

Request

Retrieve customers matching the provided query parameters

Security
OAuth2Flow
Query
pageinteger(int32)

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

page_sizeinteger(int32)

Records to return per page (default = 20)

typestring

Type of Customer

Enum"INDIVIDUAL""CORPORATION"
statusstring
  • ACTIVE - Customer is active and available for use in line with client configuration.
  • CLOSED - Customer is permanently closed, no further actions can be performed on it or associated accounts.
  • PENDING - Customer is under additional review. No actions can be performed on the account.
  • FROZEN - Customer and associated accounts have been temporarily locked for all actions.
  • EDD - Customer requires enhanced due diligence to be performed. The customer and accounts will operate as if frozen.
  • DORMANT - No activity has been seen in the last 12 months. Customer and accounts are available for use.
Enum"ACTIVE""CLOSED""FROZEN""PENDING""EDD""DORMANT"
Headers
Authorizationstring

OAuth bearer token (see authentication flows)

x-l2f-request-idstring

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

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

Responses

Success

Bodyapplication/json
dataobject(CustomerList)required
data.​customersArray of objects(Customer)required

Customer List

data.​customers[].​idstringrequired

Unique Identifier for the customer

data.​customers[].​customer_typestringrequired

Type of customer

Enum"INDIVIDUAL""CORPORATION"
Discriminator
data.​customers[].​statusstringread-onlyrequired

Customer Status - will determine servicing options on the customer and the customers accounts.

  • ACTIVE - Customer is open and available for use in line with its product configuration
  • CLOSED - Customer is permanently closed, no further actions can be performed on the customer. All accounts associated to the customer will also be CLOSED
  • PENDING - Customer is under additional review prior to moving to the OPEN or CLOSED state. No actions can be performed on the customer or their respective accounts.
  • FROZEN - Customer has been temporarily locked for all actions. All accounts associated to the customer will also be FROZEN
  • EDD - Customer requires enhanced due diligence to be performed. The customer will operate as if frozen until transitioning to ACTIVE or CLOSED.
  • DORMANT - No activity has been seen in the last 12 months. The customer and their accounts are available for use.
Enum"ACTIVE""CLOSED""FROZEN""PENDING""EDD""DORMANT"
data.​customers[].​first_namestringrequired

First name

data.​customers[].​middle_namestring

Middle Name(s) (if present)

data.​customers[].​last_namestringrequired

Last name

data.​customers[].​email_addressstring

Email Address

data.​customers[].​mailing_addressobject(mailing_address)

Mailing Address

data.​customers[].​telephone_numberstring

Telephone Number in E.164 format

data.​customers[].​tax_reference_numberstring

Tax reference number of the individual (SSN, ITIN, SIN, National Insurance Number etc)

data.​customers[].​passport_numberstring

Passport Number

data.​customers[].​nationalitystring

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

data.​customers[].​citizenshipArray of strings

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

data.​customers[].​date_of_birthstring(date)

RFC3339 (YYYY-MM-DD) Date of Birth

data.​customers[].​us_residency_statusstring

US Residency Status

Enum"US_CITIZEN""RESIDENT_ALIEN""NON_RESIDENT_ALIEN"
data.​customers[].​employment_statusstring

Employment Status

Enum"EMPLOYEE""SELF_EMPLOYED""RETIRED""UNEMPLOYED""OTHER"
data.​customers[].​employment_descriptionstring

Employment (job) description.

data.​customers[].​employer_namestring

Employer name

data.​customers[].​occupationstring

Occupation

data.​customers[].​investment_profileobject(ProfileIndividualInvesting)

Investment Profile of the Individual

data.​customers[].​kyc_profileobject(ProfileIndividualKYC)

KYC Profile of the Individual

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": {
    "customers": [ … ]
  },
  "links": {
    "self": "string",
    "first": "string",
    "prev": "string",
    "next": "string",
    "last": "string"
  }
}

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.