Guides

Banking

Suggest Edits

Worklio Bank Onboarding API Guide

Introduction

The Worklio Bank Onboarding API enables you to manage your company's bank onboarding process within the Worklio platform. This guide provides a step-by-step walkthrough of the onboarding process, detailing how to use each endpoint effectively.

By following this guide, you will learn how to:

  • Check the onboarding status
  • Retrieve and submit company and bank account details
  • Upload and submit the required documents
  • Verify bank accounts
  • Complete the onboarding process

Prerequisites

Before you begin, ensure you have the following:

  • API Credentials: Your Worklio API key or OAuth token with the necessary permissions.
  • Company ID: The unique identifier of the company you want to onboard its bank.

Overview of the Onboarding Process

Onboarding your company's bank information involves several steps. These steps include:

  1. Company Details: Retrieve and submit company information.
  2. Check Onboarding Status: Before you decide to onboard banking information, you must determine your company's current status. Doing this will provide you with information regarding the next steps.
  3. Bank Account Information: Retrieve and submit bank account details.
  4. Custody Account Information: If applicable, retrieve and submit custody account details.
  5. Documents Handling: Recover required documents, upload, and submit them.
  6. Account Verification: Verify the bank account via micro-deposits.
  7. Completion: Finalize the onboarding process.

Understanding this flow ensures that you interact with the API endpoints in the correct order.

Step-by-Step Guide

1. Submit Company Details

Endpoint: POST /wep/companies/{companyId}/bankOnboarding/details

Description: Submits or updates the company's details required for onboarding.

Example Request:

POST https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/details
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "companyName": "Acme Corporation",
  "address": "123 Business Rd.",
  "city": "Metropolis",
  "state": "NY",
  "zipCode": "10001",
  "taxId": "12-3456789",
  "contactPerson": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "555-1234"
  }
}

Example Response:

{
  "message": "Company details updated successfully."
}

Usage:

  • Ensure you fill in all required fields.
  • Validate the data before submission to prevent errors.

2. Retrieve Company Details

Endpoint: GET /wep/companies/{companyId}/bankOnboarding/company

Description: Calling this endpoint retrieves your company's existing details on file. If your authorization allows you to make the endpoint call, it returns your company's information in the system, like

  • Company's name
  • Email
  • Phone number
  • Entity Type
  • Entity Scope
  • Full Address
  • Business State Date, and
  • FEIN

Example Request:

GET https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/company
Authorization: Bearer YOUR_API_TOKEN

curl --request GET \
     --url https://api.worklio.com/wep/companies//bankonboarding/company \
     --header 'accept: application/json' \
     --header 'api-version: 1.0' \
     --header 'x-api-version: 1.0'

Example Response:

{
  "companyName": "Acme Corporation",
  "emailAddress": "[email protected]",
  "address": "123 Business Rd.",
  "city": "Metropolis",
  "state": "NY",
  "zipCode": "10001",
  "taxId": "12-3456789"
}

Usage:

  • Review the existing company details for accuracy.
  • Proceed to update or confirm these details as needed.

3. Check Onboarding Status

Endpoint: GET /wep/companies/{companyId}/bankOnboarding

Description: When you call this endpoint, you retrieve the current status of your company's bank onboarding process. You can call this endpoint at any stage of the onboarding process.

Example Request:

GET https://apidocs.worklio.com/wep/companies/123456/bankOnboarding
Authorization: Bearer YOUR_API_TOKEN

Example Response:

{
  "status": "pending",
  "nextStep": "companyDetails"
}

Usage:

  • Use this endpoint to determine the following required action.
  • The status field indicates the overall onboarding status (pending, in_progress, completed).

4. Retrieve Bank Account Information

Endpoint: GET /wep/companies/{companyId}/bankOnboarding/bankAccount

Description: If your company has already onboarded its bank information, this endpoint call retrieves the existing information and returns sensitive information about your company's bank.

Example Request:

GET https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/bankAccount
Authorization: Bearer YOUR_API_TOKEN

Example Response:

{
  "bankName": "First National Bank",
  "accountNumber": "****5678",
  "routingNumber": "123456789",
  "accountType": "checking"
}

Usage:

  • Review the bank account details currently on file.
  • Proceed to submit new details if updates are necessary.

5. Submit Bank Account Information

Endpoint: POST /wep/companies/{companyId}/bankOnboarding/bankAccount

Description: This endpoint call submits new or updated bank account details.

Example Request:

POST https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/bankAccount
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "bankName": "First National Bank",
  "accountNumber": "987654321",
  "routingNumber": "123456789",
  "accountType": "checking"
}

Example Response:

{
  "message": "Bank account information submitted successfully."
}

Usage:

  • Securely handle sensitive information.
  • Verify the accuracy of account and routing numbers.

6. Verify Bank Account

Endpoint: POST /wep/companies/{companyId}/bankOnboarding/verifyAccount

Description: Verifies the bank account, typically through micro-deposits.

Example Request:

POST https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/verifyAccount
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "depositAmounts": [0.12, 0.18]
}

Example Response:

{
  "message": "Bank account verified successfully."
}

Usage:

  • After receiving micro-deposits, input the exact amounts.
  • Ensure the amounts are accurate to avoid verification failure.

7. Retrieve Custody Account Information

Endpoint: GET /wep/companies/{companyId}/bankOnboarding/custodyAccount

Description: If your company has a custody account information, calling this endpoint retrieves this information.

Example Request:

GET https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/custodyAccount
Authorization: Bearer YOUR_API_TOKEN

Example Response:

{
  "custodyAccountNumber": "CUST-001",
  "status": "active"
}

Usage:

  • Determine whether your company requires a custody account.
  • Review existing custody account details.

8. Submit Custody Account Information

Endpoint: POST /wep/companies/{companyId}/bankOnboarding/custodyAccount

Description: If you want to submit your company's custody account details for onboarding into our system, you can call this endpoint.

Example Request:

POST https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/custodyAccount
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "custodyAccountNumber": "CUST-002",
  "beneficiaryName": "Acme Corporation"
}

Example Response:

{
  "message": "Custody account information submitted successfully."
}

Usage:

  • Provide all required custody account details.
  • Ensure compliance with any legal requirements.

9. Upload and Submit Documents

Upload Document

Endpoint: POST /wep/companies/{companyId}/bankOnboarding/documents/{docId}/upload

Description: Uploads a document file.

Example Request:

 -X POST "https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/documents/doc1/upload" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -F "file=@/path/to/document.pdf"

Example Response:

{
  "message": "Document uploaded successfully."
}

Submit Document for Review

Endpoint: POST /wep/companies/{companyId}/bankOnboarding/documents/{docId}/submit

Description: Submits the uploaded document for review.

Example Request:

POST https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/documents/doc1/submit
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "comment": "Please review the attached document."
}

Example Response:

{
  "message": "Document submitted for review."
}

Usage:

  • Repeat the upload and submit steps for each required document.
  • Ensure documents are in accepted formats (e.g., PDF, JPEG).

10. Retrieve Required Documents

Endpoint: GET /wep/companies/{companyId}/bankOnboarding/documents

Description: Retrieves a list of documents required for onboarding.

Example Request:

GET https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/documents
Authorization: Bearer YOUR_API_TOKEN

Example Response:

[
  {
    "docId": "doc1",
    "type": "Articles of Incorporation",
    "status": "pending"
  },
  {
    "docId": "doc2",
    "type": "Tax Identification Document",
    "status": "pending"
  }
]

Usage:

  • Identify all required documents.
  • Note the docId for each document for your use in subsequent requests.

11. Complete Onboarding

Endpoint: POST /wep/companies/{companyId}/bankOnboarding/complete

Description: Finalizes the onboarding process.

Example Request:

POST https://apidocs.worklio.com/wep/companies/123456/bankOnboarding/complete
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "confirmation": true
}

Example Response:

{
  "message": "Onboarding process completed."
}

Usage:

  • Ensure all prior steps are successfully completed before calling this endpoint.
  • Confirm that all data is accurate and up to date.

Best Practices

  • Secure Handling: Always use HTTPS to protect data in transit.
  • Data Validation: Validate all inputs before sending API requests.

Conclusion

Integrating the Worklio Bank Onboarding API into your application streamlines your company's onboarding process. This guide will help you efficiently manage each step, from initial status checks to final completion.

Updated 3 months ago