# rail API Specification Welcome to the rail Developer Guide! Version: 1.1.2 ## Servers Sandbox - Stable API Instance ``` https://sandbox.layer2financial.com/api ``` Production - Stable API Instance ``` https://platform.layer2financial.com/api ``` ## Security ### OAuth2Flow Type: oauth2 ## Download OpenAPI description [rail API Specification](https://docs.rail.io/_bundle/api-docs/openapi/rail-spec.yaml) ## 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. ### Retrieve Applications - [GET /v1/applications](https://docs.rail.io/api-docs/openapi/rail-spec/applications/getapplications.md): Retrieves a list of applications given the filter parameters provided ### Create Application - [POST /v1/applications](https://docs.rail.io/api-docs/openapi/rail-spec/applications/createapplication.md): Start a new application to onboard a person or corporation. Once the application is created, proceed to add individuals and update as needed, and then submit once the status allows for it. ### Submit Application - [POST /v1/applications/{application_id}/submit](https://docs.rail.io/api-docs/openapi/rail-spec/applications/submitapplication.md): Submit the application for processing, can only be performed once the application status is "READY_FOR_SUBMISSION". ### Add Individual - [POST /v1/applications/{application_id}/individual](https://docs.rail.io/api-docs/openapi/rail-spec/applications/addindividualtoapplication.md): Adds an individual to the corporate application. Not applicable for individual applications ### Request Access Code - [POST /v1/applications/{application_id}/accesscode](https://docs.rail.io/api-docs/openapi/rail-spec/applications/createapplicationonetimecode.md): Generate an access code for use with the rail Customer Onboarding SDK. ### Retrieve Application - [GET /v1/applications/{application_id}](https://docs.rail.io/api-docs/openapi/rail-spec/applications/getapplication.md): Retrieve full details of the application ### Update Application - [PATCH /v1/applications/{application_id}](https://docs.rail.io/api-docs/openapi/rail-spec/applications/updateapplication.md): Update applicant properties. For Individuals attached to a corporation, you much patch the individuals directly using Update Individual. ### Delete Individual - [DELETE /v1/applications/{application_id}/individual/{individual_id}](https://docs.rail.io/api-docs/openapi/rail-spec/applications/deleteindividual.md): Deletes an individual from a corporate application. This action is permanent and cannot be reversed. All related details of the individual (including uploaded documents) will also be deleted. ### Update Individual - [PATCH /v1/applications/{application_id}/individual/{individual_id}](https://docs.rail.io/api-docs/openapi/rail-spec/applications/updateindividual_1.md): Update individual properties. This applies only for corporate applications where individuals associated to the company need to be updated. ### Retrieve Application Status - [GET /v1/applications/{application_id}/status](https://docs.rail.io/api-docs/openapi/rail-spec/applications/getapplicationstatus.md): Retrieve the detailed status of an application ## 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. ### Retrieve Accounts - [GET /v1/accounts/deposits](https://docs.rail.io/api-docs/openapi/rail-spec/accounts/getaccounts.md): Retrieves a list of accounts given the filter parameters provided ### Open Account - [POST /v1/accounts/deposits](https://docs.rail.io/api-docs/openapi/rail-spec/accounts/openaccount.md): Opens a new account for a customer of a given product type ### Retrieve Account - [GET /v1/accounts/deposits/{id}](https://docs.rail.io/api-docs/openapi/rail-spec/accounts/getaccount.md): Retrieves the base set of account details for a given account ID ### Update Account - [PATCH /v1/accounts/deposits/{id}](https://docs.rail.io/api-docs/openapi/rail-spec/accounts/updatedepositaccount.md): Update an account details. Currently only the account status can be updated. ### Retrieve Transactions - [GET /v1/accounts/deposits/{id}/transactions](https://docs.rail.io/api-docs/openapi/rail-spec/accounts/gettransactions_1.md): Retrieves all transactions under the given account ### Retrieve Transaction - [GET /v1/accounts/deposits/{id}/transactions/{id}](https://docs.rail.io/api-docs/openapi/rail-spec/accounts/gettransaction_1.md): Retrieves details of a single transaction under the given account ### Retrieve Statements - [GET /v1/accounts/deposits/{id}/statements](https://docs.rail.io/api-docs/openapi/rail-spec/accounts/getstatements.md): Retrieves a paginated list of statements for a given account id. ### Retrieve Statement - [GET /v1/accounts/deposits/{account_id}/statements/{statement_id}](https://docs.rail.io/api-docs/openapi/rail-spec/accounts/getstatement.md): Retrieves the statement for a specific month and year for a given account id. ## 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. ### Retrieve Counterparties - [GET /v1/counterparties](https://docs.rail.io/api-docs/openapi/rail-spec/counterparties/getcounterparties.md): Retrieves a list of counterparties given the filter parameters provided ### Create Counterparty - [POST /v1/counterparties](https://docs.rail.io/api-docs/openapi/rail-spec/counterparties/createcounterparty.md): Create a new counterparty for the purpose of pulling funds into the platform or pushing out ### Retrieve Linking Details - [POST /v1/counterparties/{counterparty_id}/link/details](https://docs.rail.io/api-docs/openapi/rail-spec/counterparties/getlinkingdetails.md): Retrieve the linking instructions for embedding in a UI to launch account linking from providers such as MX or Plaid. ### Connect Linked Account - [POST /v1/counterparties/{counterparty_id}/link/connect](https://docs.rail.io/api-docs/openapi/rail-spec/counterparties/connectlinkaccount.md): Established the connection between a counterparty and external linked account. ### Retrieve Linkable Accounts - [POST /v1/counterparties/{counterparty_id}/link/accounts](https://docs.rail.io/api-docs/openapi/rail-spec/counterparties/getlinkaccounts.md): Retrieve the accounts that are available for linking for a LINKED counterparty via a provider such as MX or Plaid. ### Retrieve Counterparty - [GET /v1/counterparties/{counterparty_id}](https://docs.rail.io/api-docs/openapi/rail-spec/counterparties/getcounterparty.md): Retrieves a list of counterparties given the filter parameters provided ### Update Counterparty - [PATCH /v1/counterparties/{counterparty_id}](https://docs.rail.io/api-docs/openapi/rail-spec/counterparties/updatecounterparty.md): Update Counterparty details. There are limits to what can be updated once the counterparty has been approved for use. ## Customers Customers can only be created via the application process. Once created, customers can have multiple accounts associated with them. ### Retrieve Customer - [GET /v1/customers/{customer_id}](https://docs.rail.io/api-docs/openapi/rail-spec/customers/getcustomerdetails.md): Retrieve customer details ### Update Customer - [PATCH /v1/customers/{customer_id}](https://docs.rail.io/api-docs/openapi/rail-spec/customers/updatecustomer.md): Update customer details. For individuals (officers) linked to a corporate customer, modify the individual resource directly using Update Individual. ### Retrieve Individual - [GET /v1/customers/{customer_id}/individuals/{individual_id}](https://docs.rail.io/api-docs/openapi/rail-spec/customers/getindividual.md): Retrieve individual details. This operation is only for corporate customers that have individual officers with access to the account ### Update Individual - [PATCH /v1/customers/{customer_id}/individuals/{individual_id}](https://docs.rail.io/api-docs/openapi/rail-spec/customers/updateindividual.md): Update individual details. This operation is only for corporate customers that have individual officers with access to the account ### Retrieve Customers - [GET /v1/customers](https://docs.rail.io/api-docs/openapi/rail-spec/customers/getcustomers.md): Retrieve customers matching the provided query parameters ## 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. ### Create Deposit - [POST /v1/deposits](https://docs.rail.io/api-docs/openapi/rail-spec/deposits/createdeposits.md): Create a deposit request for a platform account in order to send funds into the account. ### Accept Deposit - [POST /v1/deposits/{deposit_id}/accept](https://docs.rail.io/api-docs/openapi/rail-spec/deposits/acceptdeposit.md): Accept a Deposit. This is only needed for PULL deposits, PUSH deposits do not need to be accepted. On acceptance, this will initiate the funds pull from the source counterparty. It is not reversible ### Retrieve Deposit - [GET /v1/deposits/{deposit_id}](https://docs.rail.io/api-docs/openapi/rail-spec/deposits/getdeposit.md): Retrieves details of a previously requested deposit ## Documents Document uploading and management functions. ### Upload Document - [POST /v1/documents/{document_id}](https://docs.rail.io/api-docs/openapi/rail-spec/documents/uploaddocument.md): Uploads a document to the system. Subsequent uploads to the same id will overwrite previous documents.ß ### Download Document - [GET /v1/documents/{document_id}/download](https://docs.rail.io/api-docs/openapi/rail-spec/documents/downloaddocument.md): Downloads a previously upload document ## 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. ### Accept Exchange - [POST /v1/exchanges/{exchange_id}/accept](https://docs.rail.io/api-docs/openapi/rail-spec/exchanges/acceptexchange.md): Accept an exchange quote. This will execute the exchange and is not reversible ### Create Exchange (Market) - [POST /v1/exchanges/market](https://docs.rail.io/api-docs/openapi/rail-spec/exchanges/createexchangemarket.md): When requesting a market exchange, the quote received is indicative ONLY. This represents an approximate rate from our liquidity providers. On accepting a market exchange the trade is performed at the current market rate which will be different to the quote presented to you. Note: Not all custodians support all order types. Where the order type is not possible (Quote/Market/Fix Destination/ Fix Source) an error will be returned. ### Retrieve Exchange - [GET /v1/exchanges/{exchange_id}](https://docs.rail.io/api-docs/openapi/rail-spec/exchanges/getexchange.md): Retrieves details of a previously requested exchange ## Payments Payments are used to orchestrate end to end payment flows from external parties or from within the platform. ### Create Payment - [POST /v1/payments](https://docs.rail.io/api-docs/openapi/rail-spec/payments/createpayments.md): Create a payment request for a platform account in order to receive funds from an external third party. ### Accept Payment - [POST /v1/payments/{payment_id}/accept](https://docs.rail.io/api-docs/openapi/rail-spec/payments/acceptpayment.md): Accept a Payment. On acceptance, payment instructions will be returned (if source = counterparty) or funds will begin processing (if source = account). ### Retrieve Payment - [GET /v1/payments/{payment_id}](https://docs.rail.io/api-docs/openapi/rail-spec/payments/getpayment.md): Retrieves details of a previously requested payment ### Retrieve Payment Status - [GET /v1/payments/{payment_id}/status](https://docs.rail.io/api-docs/openapi/rail-spec/payments/getpaymentstatus.md): Retrieves status of a previously created payment. Provides insight into any actions or RFIs that require attention. ## 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. ### Retrieve Transactions - [GET /v1/transactions](https://docs.rail.io/api-docs/openapi/rail-spec/transactions/gettransactions.md): Retrieves a list of transactions across all accounts given the query parameters provided ### Retrieve Transaction - [GET /v1/transactions/{id}](https://docs.rail.io/api-docs/openapi/rail-spec/transactions/gettransaction.md): Retrieves details of a single transaction ## Transfers Transfer are used to move funds between two platform managed accounts that are denominated in the same currency. ### Create Transfer - [POST /v1/transfers](https://docs.rail.io/api-docs/openapi/rail-spec/transfers/createtransfer.md): Request a new transfer. The transfer must be accepted prior to executing ### Accept Transfer - [POST /v1/transfers/{transfer_id}/accept](https://docs.rail.io/api-docs/openapi/rail-spec/transfers/confirmtransfer.md): Accept a requested transfer. This will execute the transfer and may not be reversible depending on the owner of the destination account ### Retrieve Transfer - [GET /v1/transfers/{transfer_id}](https://docs.rail.io/api-docs/openapi/rail-spec/transfers/gettransfer.md): Retrieves details of a previously requested transfer ## Withdrawals Move funds from a platform managed account to an external counterparty via supported rails. ### Create Withdrawal - [POST /v1/withdrawals](https://docs.rail.io/api-docs/openapi/rail-spec/withdrawals/createwithdrawal.md): Request a new withdrawal. On successful request, the withdrawal must be accepted before it is queued for execution. Withdrawals accepted before ### Cancel Withdrawal - [POST /v1/withdrawals/{withdrawal_id}/cancel](https://docs.rail.io/api-docs/openapi/rail-spec/withdrawals/cancelwithdrawal.md): Cancel a withdrawal. This will submit a withdrawal cancellation request. Some withdrawals may not be cancellable, if the funds have already been processed and sent externally. ### Accept Withdrawal - [POST /v1/withdrawals/{withdrawal_id}/accept](https://docs.rail.io/api-docs/openapi/rail-spec/withdrawals/acceptwithdrawal.md): Accept a withdrawal. This will execute the withdrawal and may not be reversible ### Retrieve Withdrawal - [GET /v1/withdrawals/{withdrawal_id}](https://docs.rail.io/api-docs/openapi/rail-spec/withdrawals/getwithdrawal.md): Retrieves details of a previously requested withdrawal ### Retrieve Withdrawal Status - [GET /v1/withdrawals/{withdrawal_id}/status](https://docs.rail.io/api-docs/openapi/rail-spec/withdrawals/getwithdrawalstatus.md): Retrieves status of a previously requested withdrawal ### Retrieve Withdrawal Receipt - [GET /v1/withdrawals/{withdrawal_id}/receipt](https://docs.rail.io/api-docs/openapi/rail-spec/withdrawals/getwithdrawalreceipt.md): Retrieves a receipt for a previously completed withdrawal. ## 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. ### Retrieve Settlement (deprecated) - [GET /v1/settlements/{settlement_id}](https://docs.rail.io/api-docs/openapi/rail-spec/settlements/getsettlement.md): Returns a detailed breakdown of an outbound settlement by account and customer. Filterable by source and destination accounts. ## 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. ### Get Subscriptions - [GET /v1/subscriptions](https://docs.rail.io/api-docs/openapi/rail-spec/subscriptions-(webhooks)/getsubscriptions.md): Return all subscriptions ### Create Subscription - [POST /v1/subscriptions](https://docs.rail.io/api-docs/openapi/rail-spec/subscriptions-(webhooks)/createsubscription.md): Creates a new event call back subscription ### Delete Subscription - [DELETE /v1/subscriptions/{subscription_id}](https://docs.rail.io/api-docs/openapi/rail-spec/subscriptions-(webhooks)/deletesubscription.md): Delete an existing subscription