Boarding API

Introduction

At Forward, we simplify the process of onboarding a new Account or Contractor through our API. Here’s a step-by-step guide to using the API to create applications, establish links, and listen to events for status updates such as approval or other changes in an application’s status:

Creating Applications, Links, and Listening to Events via API

This guide will walk you through the process of using our API to create applications, generate links, and set up event listeners to monitor status updates such as approval and boarding.

Pre-requisites

Before you begin, ensure you have the following:

1. Understanding of Our Object Hierarchy:

   • Familiarity with concepts such as Business and the ability to associate an Account with a Business. This understanding is crucial for organizing accounts and managing each client's data efficiently.

2. Access Credentials:

   • You will need access credentials (x-api-key) to be included in the header of your API requests. These credentials should have been provided to you during the onboarding process.

Step 1: Creating an Application via API

To create an application link programmatically, follow these steps:

1.1. Send a POST request to the applications endpoint:

• Sending this request will create an application with the values you want to pre-populate. Note that all of these fields are optional. If specified, the values will be pre-populated for your clients when they complete the application through the UI.

  One of the important fields is ownership type and the owner's title, which can be optionally set when pre-filling the application. You will enter the ownership_type in the company section and corresponding title in each of the owners array. To assist you in this process, here are the valid company types and their corresponding ownership types:

Ownership types and Titles:

{
  "LIMITED_LIABILITY_COMPANY": ["PRESIDENT", "VICE_PRESIDENT", "TREASURER", "CEO", "CFO", "COO", "SECRETARY", "MEMBER LLC"],
  "PRIVATE": ["PRESIDENT", "VICE_PRESIDENT", "SECRETARY", "TREASURER", "CEO", "CFO", "COO"],
  "TAX_EXEMPT_ORGANIZATION": ["ADMINISTRATOR"],
  "SOLO_TRADER": ["OWNER"],
  "PARTNERSHIP": ["PARTNER"],
  "GOVERNMENT":["ADMINISTRATOR"],
  "PUBLIC": ["ADMINISTRATOR"]
}

Headers

• x-api-key: Your API key; replace key_123456789 with your actual API key.

Sample request body

{
       "business_id": "business_id", // Enter your Business ID
       "name": "My best account", //The account
       "sales_code_id": "sc_310146",
       "company": {
           "ownership_type": "SOLO_TRADER",
           "category": "RETAIL",
           "ein": "Please have a valid EIN",
           "legal_name": "Glenn Graham", 
           "dba_name": "Glenn Graham Cookies",
           "description": "Sell amazing cookies",
           "business_start_date": "2023-08-10",
           "website": "https://merchantaccount.com",
           "timezone": "EST",
           "phone_number": "5107052819",
           "mcc": "1731" // Enter your partner registered MCC code 
       },
       "address": {
           "country": "US",
           "state": "TX",
           "city": "Austin",
           "zip_code": "35242",
           "address_line1": "858 Michele Trail",
           "address_line2": "BLD 16"
       },
       "industry_volume": {
           "avg_annual_volume": 100000,
           "avg_ticket_amount": 10000,
           "high_ticket_amount": 10000
       },
       "services_deliveries": {
           "same_day_delivery": 100,
           "one_week_delivery": 0,
           "two_week_delivery": 0,
           "one_month_delivery": 0,
           "more_than_one_month_delivery": 0
       },
       "transaction_modes": {
           "in_person": 0,
           "online": 100
       },
       "owners": [
           {
               "first_name": "Jewell",
               "last_name": "Quigley",
               "phone_number": "5121231234",
               "title": "OWNER", // Update Title based on your Ownership types 
               "email":"Dawson.Stoltenberg@example.net",
               "ownership_percent": 100,
               "birth_date": "2001-08-11",
               "residence_address": {
                   "country": "US",
                   "state": "TX",
                   "city": "Austin",
                   "zip_code": "35242",
                   "address_line1": "7760 Kilback Lights",
                   "address_line2": "BLD 17"
               },
               "signer": true
           }
       ],
   "processing_plan_id": "partppl_2hpScdzijRDZqqu68xZ21ues42s", // Enter your partner processing_plan_id
   "term_accepted": true
}

1.2.Generate Application link:

Once your application has been submitted with the data you want to pre-fill, you need to generate a link to send to your clients. Depending on how you have configured it, the link could be on your domain or be hosted by Forward. Here is an example of how that will look:

Headers

• x-api-key: Your API key. Replace key_123456789 with your actual API key.

Example Request

curl --location --request POST 'https://api.getfwd.com/applications/{{application_id}}/link' \
--header 'x-api-key: key_123456789'

With the link generated, please have your client continue to fill out all the fields on the UI. Note we recommend your clients add their bank accounts at this step to the application so that it can be securely linked to their account. This will expedite the process of paying out to your clients.

Step 2: Application approval

After your client has completed the application on the UI, the application will go through the underwriting process. In this step, we review the business and owners' information. The majority of the time, our advanced underwriting will be able to finish reviewing an application quickly. Occasionally, if there are any clarifications, our underwriting team will request changes, and you will see a NEEDS INFORMATION event from us. The initial application status will be DRAFT; once it has been fully verified by us, it will be changed to APPROVED.

2.1. Get current status:

A quick way for you get the current application status is to run the following:

Headers

• x-api-key: Your API key. Replace key_123456789 with your actual API key.

Example Request

curl --location  'https://api.getfwd.com/applications/{{applicationId}}' --header 'x-api-key: key_123456789'

In your response, look out for these fields:

{
    "status": "NEED_INFORMATION",
    "documents_requested": {
        "document_types": [
            "Passport"
        ],
        "required": true,
        "received": true,
        "received_date": "2024-07-18T20:04:50.9",
        "comments": "I need the passport copy since driver's license is not available"
    }
}

In the above example, the application is in the Needs Information status. These are the valid statuses the application can be in:

• NEED_INFORMATION -- The underwriting team requires further information to complete the review. Be sure to look at the documents_requested field for more information
• DRAFT -- The application is still in Draft and not been submitted to us.
• UNDER_REVIEW -- Your application has been submitted for underwriting but not been picked up as yet. Note it's at this time that a new user may also be created for your client based on whom the owner was specified in the application.
• UNDERWRITING -- Our underwriting is working on the application.
• APPROVED -- Application has been approved by underwriting. This will automatically create the Account in your system.
• DECLINED -- Underwriting has declined your application. The reason for denial will be communicated to you.
• CANCELLED -- The application has been cancelled, usually this happens when there are duplicate applications.
• UNDERWRITING_ERROR -- Sometimes there is an error in the application that we did not catch earlier. This can result in an underwriting error. We will try our best to recover from this expediently.
• CREDIT_PENDED -- This means that we need credit to be approved for your account.
• REJECT_BY_SALES -- This means our sales team has denied this account.
• CONDITIONALLY_APPROVED -- The account is approved, but not ready to start doing transactions.
• DECLINE_REEVALUATION_INITIATED -- We are reevaluating the application after declining the application.
• REEVALUATION_PENDING -- The reevaluation is pending.
• REEVALUATION_DECLINED -- The reevaluation has been declined.
• REEVALUATION_APPROVED -- The reevaluation has been approved, and you are good to proceed.

Step 3: Listening to Events

We highly recommend you consume our webhook events, so that you can monitor events such as application approval or request of more information. Set up event listeners:

3.1. Subscribe to events using a webhook.

Make sure you have configured to consume the webhooks. You should see this on the partner portal page under development tab that you log on to.

If you navigate to within the development tag, you can see the different types of messages and their schema.

3.2. How to know that an application is approved?

We recommend subscribing to the following events:

• v2.account.created
• v2.account.gateway_updated

Both events include the application object, which can be used to trace back to the original application. You can easily check an application's current status using the fetch endpoint.

To view the account's status, use our get account endpoint. You should see a boarded status if the account has been successfully onboarded.

3.3. When are you ready to start receiving payouts?

Your account is ready to receive payouts when you receive the v2.account.payouts_enabled webhook event. You can also check this status by fetching the account endpoint.

Conclusion

By following these steps, you can programmatically create applications, generate links, and set up event listeners to monitor status updates via our API. This enables seamless integration and automation of application management processes.

For more details on API endpoints and payloads, refer to our API documentation or contact our support team.