# Introduction

*This guide walks through how to use the Partner API to onboard business customers (if you are trying to onboard non-business customers onto your application, please read ["Onboarding Individuals"](/products/partner-api/guides/building/onboarding-individuals) instead).*

As a regulated financial institution, Jiko is required to perform Customer Identification Program (CIP), Know Your Customer (KYC), and Know Your Business (KYB) checks on all applicants. Therefore, customers cannot be created directly using the Partner API — they are created automatically when an application is approved. The application process described below collects the information needed for these checks and is the only way to create customers in the system.

Each section below describes a specific step in the onboarding process, the API endpoints involved, and example request/response payloads.

Before you begin, review the [Partner Obligations](/products/partner-api/partner-obligation) for requirements around identity verification, email/phone verification, disclosures and agreements, statements, and trade confirmations.

# Onboard Businesses

Business onboarding requires making API calls for three object types:

- The **Business Application** contains general information about the business and the overall application status. Only one is needed per business.
- **Related Party Applications** contain personal information for authorized representatives, beneficial owners (if applicable), and a member of senior management. One is required for each individual.
- **Document Requests** are a checklist of document requirements, automatically generated based on information provided in the Business Application and Related Party Applications.


When all three object types have been completed, the overall Business Application can be submitted for review.

## Create a Business Application

### Business Goal

Initiate the onboarding process for a new business customer by creating a Business Application. The application captures general information about the business — such as its legal name, entity type, address, and identification number — and serves as the foundation for the full KYB (Know Your Business) workflow. All fields are optional at creation time, allowing partners to build up the application incrementally.

Note: for all addresses in the onboarding flow, the `state` field is only required when `country` is `"US"`. Also, if the applicant is a US citizen, the identification number must be a valid SSN. If the applicant is a non-US citizen, please provide only their passport number.

### Business Workflow Example

Partner systems:

1. Collect initial business information from the prospective business customer (e.g., legal name, entity type, EIN).
2. Call Jiko's create business application endpoint with the collected information.
3. Receive the created application with its Jiko `id` and `status: "CREATED"`.
4. Store the application `id` in internal systems for subsequent updates and tracking.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Create a new Business Application with initial business details. | POST [`/api/v1/business-applications/`](/products/partner-api/reference/businesses/create-business-application) |


## Update a Business Application

### Business Goal

Incrementally add or modify information on an existing Business Application. Since applications can be created with minimal information and built up over time, partners use this endpoint to supply additional details such as the business contact, risk profile, industry, and agreement consent before submission.

The following `risk_info` fields are always required: `business_activity_location`, `account_usage`, `monthly_transactions`, `first_month_deposit`, `source_of_funds`, `annual_revenue`, and `company_mission`. Additional fields become conditionally required depending on the risk categories:

| Trigger | Conditionally required fields | Type & Accepted Values |
|  --- | --- | --- |
| `risk_info.risk_categories` contains `"CRYPTOCURRENCY"` | `risk_info.has_current_enforcement_actions` | **Boolean**: Accepts `true` (Yes) or `false` (No). |
| `risk_info.risk_categories` contains `"FINANCIAL_OR_MONEY_MOVEMENT"` | `risk_info.has_current_enforcement_actions``risk_info.primary_regulator` | **Boolean**: Accepts `true` or `false`.**String**: Answers include: `'FRB'`, `'OCC'`, `'FDIC'`, `'FINRA'`, `'CFTC'`, `'FinCEN (MSB registration)'`, `'State regulatory agency'`, `'Other'`. |


If `risk_info.source_of_funds` is `"CLIENT_OR_EXTERNAL_FUNDS"`, the `risk_info.source_of_funds_explanation` field is also required. This expects a **String** input containing details about the source of the funds.

For `agreement_consent`, call [List Agreements](/products/partner-api/reference/individuals/list_agreements_api_v1_agreements__get) to retrieve the current agreements to display to your customers. After displaying them, provide the appropriate `agreement_consent.version` and the timestamp of consent in the Business Application. You must re-fetch agreements for every new application to ensure the latest version is presented — see [Partner Obligations](/products/partner-api/partner-obligation) for details.

For the full list of possible `industry.industry` values, see the [API Reference](/products/partner-api/reference/businesses/create-business-application) and expand the `IndustryInfo` object under the request schema.

### Business Workflow Example

Partner systems:

1. Collect additional business information (e.g., contact details, risk profile, industry, agreement consent).
2. Call Jiko's update business application endpoint with the fields to add or modify.
3. Receive the updated application reflecting the changes.
4. Repeat as needed until all required information has been provided.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Update an existing Business Application with additional or corrected information. | PATCH [`/api/v1/business-applications/{application_id}/`](/products/partner-api/reference/businesses/update-business-application) |
| 2 | Optionally retrieve the current state of the application to verify updates. | GET [`/api/v1/business-applications/{application_id}/`](/products/partner-api/reference/businesses/get-business-application) |


## Add Related Parties to a Business Application

### Business Goal

Register individuals who are associated with the business — such as control persons and authorized representatives — as part of the KYB process. Each business application must include exactly one related party with the `CONTROL_PERSON` role before submission. Related parties can be added, updated, or removed as needed before the application is submitted. Furthermore, when displaying the agreements to the end user, only an authorized representative or control person may sign the agreements and submit an application on behalf of a business. Lastly, ensure that the sum of the ownership percentages for each related party does not exceed 100% for a business.

Note: the `address.state` field is only required for US addresses. The `identification_number` is masked in responses (e.g. `*****6789`) and cannot be read back — do not include it when updating a related party, as this would overwrite the real value with the masked one.

### Business Workflow Example

Partner systems:

1. Collect personal information for each related party (e.g., name, date of birth, identification number such as SSN, role, ownership percentage).
2. Call Jiko's create related party endpoint for each individual associated with the business.
3. Receive the created related party with its Jiko `id`.
4. If corrections are needed, update or delete the related party before submission.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Add a related party (e.g., control person, authorized representative) to the business application. | POST [`/api/v1/business-applications/{application_id}/related-party-applications/`](/products/partner-api/reference/businesses/create-related-party-application) |
| 2 | List all related parties associated with the business application. | GET [`/api/v1/business-applications/{application_id}/related-party-applications/`](/products/partner-api/reference/businesses/list-related-party-application) |
| 3 | Update an existing related party if corrections are needed. | PATCH [`/api/v1/business-applications/{application_id}/related-party-applications/{related_party_application_id}/`](/products/partner-api/reference/businesses/update-related-party-application) |
| 4 | Remove a related party. | DELETE [`/api/v1/business-applications/{application_id}/related-party-applications/{related_party_application_id}/`](/products/partner-api/reference/businesses/delete-related-party-application) |


## Document Requests

Document Requests are automatically generated based on information provided in the Business Application and Related Party Applications. They vary depending on the business entity type, risk profile, and related party details.

### Business Goal

List outstanding document requirements for the business application, upload requested documents, and ensure all documents are provided before submission.

Note: If `INTERNAL_KYC_AUDIT`, `EXTERNAL_KYC_AUDIT`, **AND** `KYC_POLICIES_AND_PROCEDURES` are requested, the business is only required to submit either `EXTERNAL_KYC_AUDIT` **OR** `INTERNAL_KYC_AUDIT` **AND** `KYC_POLICIES_AND_PROCEDURES`.

### Business Workflow Example

Partner systems:

1. Call the List Document Requests endpoint to retrieve the checklist of required documents.
2. For each document with `status: "PENDING_UPLOAD"`, upload a `.png` file of the requested document.
3. Uploading a document updates its status from `PENDING_UPLOAD` to `PENDING_REVIEW`. The document will then be reviewed and the status will move to either `APPROVED` or `INVALID`.
4. If a document status is `INVALID`, an `exception_reason` will be provided as guidance. Upload a corrected document.
5. When all Document Requests have status `APPROVED` or `PENDING_REVIEW`, along with the completed Business Application and Related Party Applications, submit the overall application using Apply.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | List document requests for a business application. | GET [`/api/v1/business-applications/{application_id}/documents/`](/products/partner-api/reference/businesses/list-document-requests-businesses) |
| 2 | Upload a document for a document request. | POST [`/api/v1/documents/{document_id}/`](/products/partner-api/reference/businesses/upload-application-document) |


## Submit a Business Application for Review

### Business Goal

Submit a completed Business Application for KYB review. The Business Application, Related Party Applications, and Document Requests must all be complete before submission. If required information is missing, the endpoint returns `exception_reasons` indicating what needs to be addressed. Upon approval, a Customer is created for the business and the application's `customer_id` field is populated.

### Application Statuses

| Status | Description |
|  --- | --- |
| `CREATED` | The application has been created but not submitted. Complete the Business Application, Related Party Applications, and Document Requests, then call Apply. |
| `SUBMITTED` | The application has been submitted and is being reviewed. |
| `DOCUMENTS_NEEDED` | The application requires additional documentation. Call List Document Requests to view outstanding documents, then upload them. When all requested documents have been provided, the status automatically moves to `PENDING`. |
| `PENDING` | Required actions are complete. Call Apply again to re-submit for evaluation. |
| `MANUAL_REVIEW` | The application is being manually reviewed. |
| `APPROVED` | The application has been approved and a `customer_id` now exists for the business. This is a terminal status. |
| `REJECTED` | The application has been rejected. This is a terminal status. |
| `CLOSED` | The application has been closed due to inactivity. This is a terminal status. |


### Business Workflow Example

Partner systems:

1. Verify that all required business information, related parties, and documents have been provided.
2. Call Jiko's apply endpoint to submit the business application for review.
3. If the response contains `exception_reasons`, address the missing information by updating the application, adding related parties, or uploading documents, then resubmit.
4. Once successfully submitted, the application `status` transitions to `"SUBMITTED"`.
5. Poll the application periodically or subscribe to [webhooks](/products/partner-api/guides/building/webhooks) (e.g. `application.approved`, `application.documents_needed`) to track review progress.
6. If `status` is `"DOCUMENTS_NEEDED"`, list and upload the required documents. When complete, the status moves to `"PENDING"` — call Apply again.
7. When `status` is `"APPROVED"`, use the `customer_id` from the application to proceed with account setup.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Submit the completed business application for KYB review. | POST [`/api/v1/business-applications/{application_id}/apply/`](/products/partner-api/reference/businesses/business-application-apply) |
| 2 | Poll the application to track review progress and retrieve the `customer_id` upon approval. | GET [`/api/v1/business-applications/{application_id}/`](/products/partner-api/reference/businesses/get-business-application) |
| 3 | List outstanding document requests. | GET [`/api/v1/business-applications/{application_id}/documents/`](/products/partner-api/reference/businesses/list-document-requests-businesses) |
| 4 | Upload a requested document. | POST [`/api/v1/documents/{document_id}/`](/products/partner-api/reference/businesses/upload-application-document) |


## Sandbox Testing

The sandbox environment lets you test all application statuses without going through real KYB review. The first digit of the Business ID (`identification_number`) controls which status the application transitions to after calling Apply:

| ID prefix | Result after Apply |
|  --- | --- |
| `2` | `DOCUMENTS_NEEDED` |
| `3` | `MANUAL_REVIEW` |
| `4` | `APPROVED` |
| `5` | `REJECTED` |
| Other | `MANUAL_REVIEW` |


## Retrieve a Business Application

### Business Goal

Retrieve the current state of a Business Application at any point during the onboarding process. This supports tracking application progress, verifying submitted information, and determining when an application has been approved and a Customer has been created.

### Business Workflow Example

Partner systems:

1. Call Jiko's get business application endpoint with the application `id`.
2. Review the `status` field to determine the current stage of the application.
3. If `status` is `"APPROVED"`, extract the `customer_id` to proceed with account operations.
4. If `status` is `"DOCUMENTS_NEEDED"`, upload the required documents.
5. Propagate the application state to internal systems for tracking and reporting.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Retrieve the current state of a Business Application. | GET [`/api/v1/business-applications/{application_id}/`](/products/partner-api/reference/businesses/get-business-application) |