# Boarding API(v1.0.5)

Welcome to the Boarding API documentation!

Here you will find our collection of endpoints for boarding and managing accounts.

## Introduction
This is the reference documentation and schemas for the [Boarding API](https://docs.getfwd.com/docs/boarding-api).

### Authentication
The platform uses API Keys to manage access to the API. You can pass the API key in the `x-api-key` header to the request.
Talk to your sales rep about acquiring these API keys. Authorization is done via headers. You should pass the api key as the value to the `x-api-key` header. For example, `x-api-key: ${API_KEY}`.

Please note that you will be given 2 API keys, one public key and one private key. Use the private key for all server to server communication.
The public key is used for interfacing with the JS SDK.

## Accounts
A Forward Account is created when you have an **Application** that has gone through the boarding process to get to an **approved** state. You can fetch a particular Account, find all the Accounts that you are associated with, and update account name and user_fields. **Note:**

1. Each Account is required to have a **Company** as well as an **Address**.
2. You can only view and patch Accounts if you have the correct level of access.

### Fetch an Account By id
You will need the unique id for the Account.

##### Authorizations:

_x-api-key_

##### path Parameters  
|     |     |
| --- | --- |
| id<br>required | string |

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

**404**  
Requested resource not found

get/accounts/{id}

### Fetch Accounts
You can fetch all the Accounts that are associated with you. Additionally, there is further filtering available for Account Name or Business Id

##### Authorizations:

_x-api-key_

##### query Parameters  
|     |     |
| --- | --- |
| requestDto<br>required | object (AccountFilterRequestDto) |

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

get/accounts

## Applications
This is an object that represents a Forward Application. This is how you get started on Forward to initiate the process of having an Account. You can **Create** a Draft Application or Update the Draft Application. Additionally, you can also generate an Application Link to update or submit a new Boarding application. All the Applications that were created by you can also be retrieved.

### Fetch a boarding Application by id
Retrieve complete details about a specific boarding application by its unique identifier. This endpoint returns all application information including status, business details, company information, and configuration. Use this to review application details at any stage of the onboarding process, from draft to approved status. The response includes `requires_bank_account_file_ids_on_submit`: when `true`, your submit request must include `file_ids` with uploaded bank-validation documents.

##### Authorizations:

_x-api-key_

##### path Parameters  
|     |     |
| --- | --- |
| id<br>required | string |

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

**404**  
Requested resource not found

get/applications/{id}

### Update an existing draft boarding Application
Update an existing draft boarding application to modify or complete application details. **Important:** This endpoint can only be used to update applications that are in **DRAFT** status. Once an application has been submitted and moved to other statuses (such as UNDER_REVIEW, APPROVED, etc.), it cannot be updated through this route.

##### Authorizations:

_x-api-key_

##### path Parameters  
|     |     |
| --- | --- |
| id<br>required | string |

### Request Body schema: application/json
|     |     |
| --- | --- |
| business_id<br>required | string<br>The Business ID |
| name<br>required | string[ 0 .. 100 ] characters<br>Account Name |
| sales_code_id | string[ 0 .. 50 ] characters<br>Sales Code ID |
| company | object (AccountCompanyRequestDto) <br>Company Information - Supports both US (EIN) and Canadian (BN) applications |
| business_address | object (AddressRequestDto) <br>Address Info |
| industry_volume | object (ApplicationIndustryVolumeExtDto) <br>Partner-facing industry and volume. Use bank_volume for expected annual bank-rail processing volume; it is mapped to ACH annual fields on persist. |
| services_deliveries | object (ServicesDeliveriesRequestDto) <br>Service Delivery Information |
| transaction_modes | object (TransactionModesRequestDto) <br>Service Delivery Information |
| owners | Array of objects (OwnerUpdateRequestDto) <br>Owners Information |
| processing_plan_id | string<br>Processing Plan id |
| terms_accepted | boolean<br>Terms and Conditions are accepted or not |
| partner_data | object (PartnerDataDto) <br>Partner Data Information |
| country | string[ 0 .. 10 ] characters^(US|CA)$<br>Default:"US"<br>Country code - US or CA |
| external_account_id | string[ 0 .. 255 ] characters<br>Partner's external identifier for the account (e.g. partner system account ID) |
| user_fields | object<br>User-defined fields as free-form JSON object |

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

put/applications/{id}

### Deleting an existing Application in DRAFT or CANCELLED state
Permanently delete a boarding application that is in **DRAFT** or **CANCELLED** status. **Important:** This operation can only be performed on applications in DRAFT or CANCELLED states. Applications in other statuses (such as UNDER_REVIEW, APPROVED, DECLINED, etc.) cannot be deleted.

##### Authorizations:

_x-api-key_

##### path Parameters  
|     |     |
| --- | --- |
| id<br>required | string |

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

delete/applications/{id}

### Submit a boarding Application
Submit a draft boarding application to move it to underwriting. The application must be in DRAFT status.

**Access:** Submit via API is an entitlement and is not available to every integration. Contact support if you want to learn more about eligibility or enabling this capability.

### Request Body schema: application/json
|     |     |
| --- | --- |
| --- | --- |
| business_id<br>required | string<br>The Business ID under which the account will be created. Choose carefully: business users can manage accounts under the given Business, and this selection affects your workflows. Must match the application's business. |
| name<br>required | string[ 0 .. 100 ] characters<br>Account name. Display name for the merchant account. Max 100 characters. |
| sales_code_id | string[ 0 .. 50 ] characters<br>Optional. Sales code identifier. |
| company<br>required | object (AccountCompanyRequestDto) <br>Company Information - Supports both US (EIN) and Canadian (BN) applications |
| address<br>required | object (AddressRequestDto) <br>Address Info |
| industry_volume<br>required | object (ApplicationIndustryVolumeExtDto) <br>Partner-facing industry and volume. Use bank_volume for expected annual bank-rail processing volume; it is mapped to ACH annual fields on persist. |
| services_deliveries<br>required | object (ServicesDeliveriesRequestDto) <br>Service Delivery Information |
| transaction_modes<br>required | object (TransactionModesRequestDto) <br>Service Delivery Information |
| owners<br>required | Array of objects (OwnerUpdateRequestDto)

## Bank Account
Here you can fetch all the Bank Accounts that have been linked to Businesses that are linked to you.

### Fetch Bank Accounts
##### Authorizations:

_x-api-key_

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

get/bank_accounts

### Get Bank account information
##### Authorizations:

_x-api-key_

##### path Parameters  
|     |     |
| --- | --- |
| id<br>required | string |

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

**404**  
Requested resource not found

get/bank_accounts/{id}

## Business
This is an object that represents a Forward Business associated with an Account. Every Account that you have must be associated with You can create a Business, fetch a particular Business or find all the Businesses that are associated to your Account.

### Find all Businesses
You can find all Businesses or specifically filter by Name or Contact information.

##### Authorizations:

_x-api-key_

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

get/businesses

### Create a new Business
You can create a new Business that will be linked to your Account.

### Request Body schema: application/json
|     |     |
| --- | --- |
| name<br>required | string[ 0 .. 100 ] characters<br>Business Name |
| contact_email | string<br>Contact Email |
| contact_phone_number | string<br>Contact Phone Number |
| contact_phone_extension | string<br>Contact Phone Extension |
| contact_first_name | string[ 2 .. 50 ] characters<br>Contact First Name |
| contact_last_name | string[ 2 .. 50 ] characters<br>Contact Last Name |
  
# Locations
A Business on Forward can have one or more Locations.

### Get a Location by unique id
You can review an existing Location that's assigned to a specific Business.

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

**404**  
Requested resource not found

get/locations/{id}

# MC Codes
Here you can find all Merchant Category Codes that are assigned to your Accounts.

### List all MCCs
Use this endpoint to list all of the **MCCs** that have been assigned to you.

##### Authorizations:

_x-api-key_

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

get/mccs

# Payee
A Payee is an entity in the platform's payment ecosystem.

### Generate Payee On-boarding Application Link
Use this endpoint to create a new payee application link.

### Request Body schema: application/json
|     |     |
| --- | --- |
| application_data | object (PayeeRequestExtBaseDto) <br>Payee Application Data |
     
### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

post/payees/link

### Get an existing Payee By ID
Retrieve complete details about a specific payee by its unique identifier.

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

**404**  
Requested resource not found

get/payees/{id}

# Processing Plans
Processing Plans are key information that determines fees and payout processing at Forward.

### Find all Processing Plans
Here you can find all the Processing Plans.

##### Authorizations:

_x-api-key_

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

get/processing_plans

# Users
Manage user information for Businesses that you manage.

### View user details
Get user details.

### Responses

**200**  
Success

**400**  
Bad request parameters

**401**  
Authorization Required

**403**  
Access Denied to perform an action

**404**  
Requested resource not found

get/users/{id}