This is the reference documentation and schemas for the Forward Boarding API API. For tutorials and other documentation please refer to the documentation.
Forward 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}
. For more information on authentication, please refer to the authentication token docs.
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 Forward JS SDK.
A Business on Forward can have one more Locations. Here you Create, Read, Update or Delete a Location for a Business.
Edit a Location
Business Locations are always editable, please keep this information updated as your information changes.
Authorizations:
path Parameters
id required | string |
Request Body schema: application/json
name required | string [ 0 .. 100 ] characters Location Name |
Responses
Request samples
- Payload
{- "name": "string"
}
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:
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:
Request Body schema: application/json
business_id required | string |
name required | string [ 0 .. 100 ] characters Location Name |
Responses
Request samples
- Payload
{- "business_id": "string",
- "name": "string"
}
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.
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:
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 |
Responses
Request samples
- Payload
{- "business_id": "string",
- "name": "string",
- "sales_code_id": "string",
- "company": {
- "ownership_type": "GOVERNMENT",
- "category": "RETAIL",
- "ein": "string",
- "legal_name": "string",
- "dba_name": "string",
- "description": "string",
- "business_start_date": "2019-08-24",
- "website": "string",
- "timezone": "EST",
- "phone_number": "8005550100",
- "mcc": "7021",
- "stock_symbol": "string"
}, - "business_address": {
- "country": "US",
- "state": "AL",
- "city": "string",
- "zip_code": "35242",
- "address_line1": "string",
- "address_line2": "string"
}, - "industry_volume": {
- "avg_annual_volume": 999999999,
- "avg_ticket_amount": 99999,
- "high_ticket_amount": 0
}, - "ach_volume": 0,
- "services_deliveries": {
- "same_day_delivery": 0,
- "one_week_delivery": 0,
- "two_week_delivery": 0,
- "one_month_delivery": 0,
- "more_than_one_month_delivery": 0
}, - "transaction_modes": {
- "in_person": 0,
- "online": 0
}, - "owners": [
- {
- "id": "string",
- "first_name": "string",
- "last_name": "string",
- "email": "string",
- "phone_number": "string",
- "title": "OWNER",
- "ownership_percent": 0,
- "ssn": "string",
- "birth_date": "2019-08-24",
- "residence_address": {
- "country": "US",
- "state": "AL",
- "city": "string",
- "zip_code": "35242",
- "address_line1": "string",
- "address_line2": "string"
}, - "signer": true
}
], - "processing_plan_id": "string",
- "terms_accepted": true
}
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.
Authorizations:
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 |
Responses
Request samples
- Payload
{- "business_id": "string",
- "name": "string",
- "sales_code_id": "string",
- "sales_agent_id": "string",
- "sales_group_id": "string",
- "company": {
- "ownership_type": "GOVERNMENT",
- "category": "RETAIL",
- "ein": "string",
- "legal_name": "string",
- "dba_name": "string",
- "description": "string",
- "business_start_date": "2019-08-24",
- "website": "string",
- "timezone": "EST",
- "phone_number": "8005550100",
- "mcc": "7021",
- "stock_symbol": "string"
}, - "address": {
- "country": "US",
- "state": "AL",
- "city": "string",
- "zip_code": "35242",
- "address_line1": "string",
- "address_line2": "string"
}, - "industry_volume": {
- "avg_annual_volume": 999999999,
- "avg_ticket_amount": 99999,
- "high_ticket_amount": 0
}, - "ach_volume": 0,
- "services_deliveries": {
- "same_day_delivery": 0,
- "one_week_delivery": 0,
- "two_week_delivery": 0,
- "one_month_delivery": 0,
- "more_than_one_month_delivery": 0
}, - "transaction_modes": {
- "in_person": 0,
- "online": 0
}, - "owners": [
- {
- "first_name": "string",
- "last_name": "string",
- "email": "test@example.com",
- "phone_number": "1234567890",
- "title": "OWNER",
- "ownership_percent": 50,
- "ssn": "123456789",
- "birth_date": "2019-08-24",
- "residence_address": {
- "country": "US",
- "state": "AL",
- "city": "string",
- "zip_code": "35242",
- "address_line1": "string",
- "address_line2": "string"
}, - "signer": true
}
], - "processing_plan_id": "string",
- "terms_accepted": true
}
Generate a boarding Application Link
Here you are able to generate a link for the Boarding Application. If you have your own Hosted Application domain the link will be generated based of your domain. Otherwise the link is hosted on Forward. Note its required that a Processing Plan be selected to able to generate the application link. Also each Application link can expire, once a link is expired a new Application Link will need to regenerated.
Authorizations:
path Parameters
id required | string |
Responses
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:
query Parameters
required | object (MccCodeFilterRequestDto) MC Codes Filter Request |
Responses
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:
- Each Account is required to have a Company as well as an Address.
- You can only view and modify Accounts if you have the correct level of access.
Update Account data
Here you can update an Account. Most of an Account's fields can be updated.
Authorizations:
path Parameters
id required | string |
Request Body schema: application/json
name required | string [ 0 .. 100 ] characters Account name |
recruited_by | string Account Recruited By User Name/Email |
required | object (AccountCompanyUpdateDto) Company Information |
location_id | string [ 0 .. 100 ] characters Account Location Id |
required | object (AddressDto) Address Info |
Responses
Request samples
- Payload
{- "name": "string",
- "recruited_by": "string",
- "company": {
- "ownership_type": "GOVERNMENT",
- "category": "RETAIL",
- "ein": "string",
- "legal_name": "string",
- "dba_name": "string",
- "description": "string",
- "business_start_date": "2019-08-24",
- "website": "string",
- "timezone": "EST",
- "phone_number": "8005550100",
- "mcc": "string"
}, - "location_id": "string",
- "address": {
- "country": "US",
- "state": "AL",
- "city": "string",
- "zip_code": "35242",
- "address_line1": "string",
- "address_line2": "string"
}
}
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.
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:
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
- Payload
{- "name": "string",
- "contact_email": "string",
- "contact_phone_number": "string",
- "contact_phone_extension": "string",
- "contact_first_name": "string",
- "contact_last_name": "string"
}
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:
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:
path Parameters
id required | string |
Responses
A Contractor is a an entity in Forward'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.
Generate Contractor On-boarding Application Link
Use this endpoint to create a new contractor application link. A contractor can select to be an individual or company. A company contractor will require some information link Owners information.
Authorizations:
Request Body schema: application/json
parent_id required | string Contractor Parent ID |
parent_type required | string Default: "PARTNER" Enum: "PARTNER" "BUSINESS" Contractor Parent Type |
object (ContractorRequestExtBaseDto) Wrapper Company Contractor Creation Information |
Responses
Request samples
- Payload
{- "parent_id": "string",
- "parent_type": "BUSINESS",
- "application_data": {
- "individual": {
- "first_name": "string",
- "last_name": "string",
- "address": {
- "country": "US",
- "state": "AL",
- "city": "string",
- "zip_code": "35242",
- "address_line1": "string",
- "address_line2": "string"
}, - "email": "string",
- "phone_number": "string"
}, - "company": {
- "name": "string",
- "legal_name": "string",
- "email": "string",
- "ownership_type": "PARTNERSHIP",
- "company_owners": [
- {
- "first_name": "string",
- "last_name": "string",
- "email": "string",
- "phone_number": "string",
- "residence_address": {
- "country": "US",
- "state": "AL",
- "city": "string",
- "zip_code": "35242",
- "address_line1": "string",
- "address_line2": "string"
}, - "ownership_percent": 0,
- "title": "OWNER"
}
], - "business_address": {
- "country": "US",
- "state": "AL",
- "city": "string",
- "zip_code": "35242",
- "address_line1": "string",
- "address_line2": "string"
}
}
}
}
Find All Contractors by provided request
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.
Authorizations:
query Parameters
required | object (ContractorExtFilterRequestDto) |
header Parameters
x-business-id required | string |