Skip to main content

Boarding API (v1.0.5)

Download OpenAPI specification:Download

Welcome to the Boarding API documentation!

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

Introduction

This is the reference documentation and schemas for the Boarding API 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 you 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 wih the JS SDK.

Payee

A Payee is a an entity in the platform's payment ecosystem. Using our Payee entity you can setup split payments for a given transaction. The lifecycle of a Payee is 1. A prospective payee receives an application to apply as a Payee, Note: Bank Account details is submitted with the Payee Application. Note: you can create a new payee application using link endpoint. 2. Once a payee application is filled out the application gets submitted to underwriting. 3. If our process approves the application a new payee entity comes into existence. The default state of the newly created Payee is active. You can deactivate or toggle activate for a Payee.

Deactivate an existing Payee

Deactivate an existing Payee

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Activate an existing Payee

Note: The payee has to have gone through the identity process before you can activate/deactivate a Payee

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Find All Payees by provided request

Returns all Payees that belong to your Partner account.

Authorizations:
x-api-key
query Parameters
required
object (PayeeExtFilterRequestDto)

Responses

Get an existing Payee By ID

Retrieve the details about a given Payee

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Find All Payee Applications by provided request

Returns all Payee Applications that belong to your Partner account.

Authorizations:
x-api-key
query Parameters
required
object (PayeeApplicationFilterRequestDto)

Responses

Locations

A Business on Forward can have one more Locations. Here you Create, Read, Update or Delete a Location for a Business.

Get a Location by unique id

You can review an existing Location that's assigned to a specific Business. Note: You can only review Business that you have access to.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Edit a Location

Business Locations are always editable, please keep this information updated as your information changes.

Authorizations:
x-api-key
path Parameters
id
required
string
Request Body schema: application/json
name
required
string [ 0 .. 100 ] characters

Location Name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Delete a Location

If a Location needs to be deleted, you can use this endpoint to delete a Location at Forward.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Find Locations

You can find all Locations that you have access to. Further filter on Business Location name and Business Id can be applied on the list of Locations.

Authorizations:
x-api-key
query Parameters
required
object (BusinessLocationFilterRequestExtDto)

Business Location Filter Information

Responses

Create a Location

This endpoint can be used to create a new Business Location only two fields are needed Business Id and Location Name.

Authorizations:
x-api-key
Request Body schema: application/json
business_id
required
string
name
required
string [ 0 .. 100 ] characters

Location Name

Responses

Request samples

Content type
application/json
{
  • "business_id": "string",
  • "name": "string"
}

Users

Manage user information for Businesses that you manage

View user details

Get user details

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Update a User

You can keep information regarding your user updated here.

Authorizations:
x-api-key
path Parameters
id
required
string
Request Body schema: application/json
first_name
required
string

User First Name

last_name
required
string

User Last Name

email
string

User Email Address

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "test@test.com"
}

Update User Status

You can activate or deactivate your user.

Authorizations:
x-api-key
path Parameters
id
required
string
Request Body schema: application/json
status
required
string
Enum: "ACTIVE" "INACTIVE"

User Status

Responses

Request samples

Content type
application/json
{
  • "status": "ACTIVE"
}

Get a list of users

Authorizations:
x-api-key
query Parameters
required
object (UserFilterRequestExtDto)

Pagination list request with filter

Responses

Create a Business User

Here you can create a user for a specific Business. Provide all the necessary details about the user. We will send an automated email out informing your user to setup a password and login. You can also generated a one time login link for this user.

Authorizations:
x-api-key
Request Body schema: application/json
business_id
required
string

Business Id

first_name
required
string

User First Name

last_name
required
string

User Last Name

email
required
string [ 0 .. 70 ] characters

User Email

Responses

Request samples

Content type
application/json
{
  • "business_id": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string"
}

Get a magic login link for specific user

You can retrieve a magic link for a specific Business user that you have access to.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

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

You can review a submitted boarding application by providing the unique Application id.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Update an existing draft boarding Application

Updates to boarding Application are allowed as needed. Note: An existing boarding draft Application can be updated as long as the boarding status is in a status that allows further updates. Once an boarding Application reaches a terminal state no further updates will be allowed on the boarding Application.

Authorizations:
x-api-key
path Parameters
id
required
string
Request Body schema: application/json
business_id
required
string

The Business ID

name
required
string [ 0 .. 100 ] characters

Account Name

sales_code_id
string [ 0 .. 50 ] characters

Sales Code ID

object (AccountCompanyRequestDto)

Company Information

object (AddressRequestDto)

Address Info

object (IndustryVolumeRequestDto)

Industry & Volume Information

ach_volume
integer <int32>

Application Ach Volume Info

object (ServicesDeliveriesRequestDto)

Service Delivery Information

object (TransactionModesRequestDto)

Service Delivery Information

Array of objects (OwnerUpdateRequestDto)

Owners Information

processing_plan_id
string

Processing Plan id

terms_accepted
boolean

Terms and Conditions are accepted or not

object (PartnerDataDto)

Partner Data Information

Responses

Request samples

Content type
application/json
{
  • "business_id": "string",
  • "name": "string",
  • "sales_code_id": "string",
  • "company": {
    },
  • "business_address": {
    },
  • "industry_volume": {
    },
  • "ach_volume": 0,
  • "services_deliveries": {
    },
  • "transaction_modes": {
    },
  • "owners": [
    ],
  • "processing_plan_id": "string",
  • "terms_accepted": true,
  • "partner_data": {
    }
}

Deleting an existing Application in DRAFT or CANCELLED state

You can only delete an Application if its in DRAFT or CANCELLED state. Once an application has been deleted you will not see it in the list of Applications.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

List boarding Applications

You can list all the boarding applications submitted with the option of filtering on Statuses, BusinessId or Created timestamps

Authorizations:
x-api-key
query Parameters
required
object (ApplicationFilterRequestDto)

Application Filter Request

Responses

Create a boarding Application

Create a new boarding Application to get started on Forward. Once the boarding Application has been submitted it will processed and go through our process for approval. You can monitor the submitted applications here.This is the mapping of the Company ownership types and the corresponding owners title. Note: These are optional and you don't need in the 'Create Application Step'.

LIMITED LIABILITY COMPANY

  • PRESIDENT
  • VICE_PRESIDENT
  • TREASURER
  • CEO
  • CFO
  • COO
  • SECRETARY
  • MEMBER

PRIVATE

  • PRESIDENT
  • VICE_PRESIDENT
  • SECRETARY
  • TREASURER
  • CEO
  • CFO
  • COO

TAX EXEMPT ORGANIZATION

  • ADMINISTRATOR

SOLO TRADER

  • OWNER

PARTNERSHIP

  • PARTNER

GOVERNMENT

  • ADMINISTRATOR

PUBLIC

  • ADMINISTRATOR

Authorizations:
x-api-key
Request Body schema: application/json
business_id
required
string

The Business ID that the account needs to belong to. This allows you to arrange the Accounts when they get created.

name
required
string [ 0 .. 100 ] characters

Account Name

sales_code_id
string [ 0 .. 50 ] characters

Sales Code ID

sales_agent_id
string [ 0 .. 50 ] characters

Sales Agent ID

sales_group_id
string [ 0 .. 50 ] characters

Sales Group ID

object (AccountCompanyRequestDto)

Company Information

object (AddressRequestDto)

Address Info

object (IndustryVolumeRequestDto)

Industry & Volume Information

ach_volume
integer <int32>

Ach Volume Info

object (ServicesDeliveriesRequestDto)

Service Delivery Information

object (TransactionModesRequestDto)

Service Delivery Information

Array of objects (MerchantOwnerCreationRequestDto)

Owners Information

processing_plan_id
required
string

Processing Plan id

terms_accepted
boolean

Terms and Conditions are accepted or not

object (PartnerDataDto)

Partner Data Information

Responses

Request samples

Content type
application/json
{
  • "business_id": "string",
  • "name": "string",
  • "sales_code_id": "string",
  • "sales_agent_id": "string",
  • "sales_group_id": "string",
  • "company": {
    },
  • "address": {
    },
  • "industry_volume": {
    },
  • "ach_volume": 0,
  • "services_deliveries": {
    },
  • "transaction_modes": {
    },
  • "owners": [
    ],
  • "processing_plan_id": "string",
  • "terms_accepted": true,
  • "partner_data": {
    }
}

MC Codes

Here you can find all Merchant Category Codes that are assigned to your Accounts. Please contact Forward support if you have any questions.

List all MCCs

Use this endpoint to list all of the MCCs that have been assigned to you. Please verify this information as it plays a key role in our payment processing flows, as well as the Application creation process.

Authorizations:
x-api-key
query Parameters
required
object (MccCodeFilterRequestDto)

MC Codes Filter Request

Responses

Contractor

A Contractor is a an entity in the platform's payment ecosystem. Using our Contractor entity you can setup split payments for a given transaction. The lifecycle of a Contractor is 1. A prospective contractor receives an application to apply as a Contractor, Note: Bank Account details is submitted with the Contractor Application. Note: you can create a new contractor application using link endpoint. 2. Once a contractor application is filled out the application gets submitted to underwriting. Note a Contractor can be Individual or Business. 3. If underwriting approves the application a new contractor entity comes into existence. The default state of the newly created Contractor is active. You can deactivate or toggle activate for a Contractor.

⚠️ DEPRECATED: This API is deprecated and will be removed in a future version. Please use the Payee API instead (payees).

Deactivate an existing Contractor Deprecated

Deactivate an existing Contractor. ⚠️ DEPRECATED: Use payees/{id}/deactivate instead.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Activate an existing Contractor Deprecated

Note: The contractor has to have gone through the identity process before you can activate/deactivate a Contractor. ⚠️ DEPRECATED: Use payees/{id}/activate instead.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Find All Contractors by provided request Deprecated

Please provide the x-business-id so that all the Contractors can be retrieved for a given Business. If you don't provide this header you will get back all the Contractors that belong to you and none of our business specific Contractors. ⚠️ DEPRECATED: Use payees instead.

Authorizations:
x-api-key
query Parameters
required
object (ContractorExtFilterRequestDto)
header Parameters
x-business-id
string

Responses

Get an existing Contractor By ID Deprecated

Retrieve the details about a given Contractor. ⚠️ DEPRECATED: Use payees/{id} instead.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

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 update your Account, fetch a particular Account as well as find all the Accounts that you are associated with. If there was something incorrect for your Account you can also update details for an Account. Note:

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

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
required
object (AccountFilterRequestDto)

Responses

Fetch an Account By id

You will need the unique id for the Account.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

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
query Parameters
required
object (BusinessFilterRequestExtDto)

Business Information

Responses

Create a new Business

You can create a new Business that will be linked to your Account. We encourage you to complete all the fields while creating a new Business. Once you have created a Business you can start creating Applications and get associated Accounts.

Authorizations:
x-api-key
Request Body schema: application/json
name
required
string [ 0 .. 100 ] characters

Business Name

contact_email
string

Contact Email

contact_phone_number
string

Contact Phone Number

contact_phone_extension
string

Contact Phone Extension

contact_first_name
string [ 2 .. 50 ] characters

Contact First Name

contact_last_name
string [ 2 .. 50 ] characters

Contact Last Name

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "contact_email": "string",
  • "contact_phone_number": "string",
  • "contact_phone_extension": "string",
  • "contact_first_name": "string",
  • "contact_last_name": "string"
}

Fetch a Business by a unique id

Each Business has a unique id and must be associated with your Account. You can only search a Business you have access to.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Processing Plans

Processing Plans are key information that determines fees and payout processing at Forward. You can view, create, update a Processing Plan associated with your Accounts.

Find all Processing Plans

Here you can find all the Processing Plans, if you specify Name you can filter on specific Name as well.The Processing Plan data will be returned to you in a list.

Authorizations:
x-api-key
query Parameters
required
object (ProcessingPlanFilterDto)

Processing Plan Filter

Responses

Get a Processing Plan by id

Here you can review Processing Plan that has been created and verify the information is accurate. If there are any discrepancies in the Fees data please reach out as these play a key role processing payouts.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Bank Account

Bank Account Information

Fetch Bank Accounts

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

Authorizations:
x-api-key
query Parameters
required
object (BankAccountExtFilterRequestExtDto)

Bank Account pagination and filter request

Responses

Get Bank account information

Here you can fetch a Bank Account and retrieve the status of a given bank account.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses