# Onboarding Individuals

Onboarding an individual means completing KYC. An individual application is a single object: you create it with everything you know, you apply, and Jiko decides. Where it cannot decide automatically, it asks for documents or routes to human review.

When the application reaches `APPROVED`, Jiko creates a **customer**, and the application's `customer_id` is populated. That customer can then hold pockets.

Applicants must be **at least 18 years old**.

div
## Prerequisites

### Feature flags

No feature flag gates individual onboarding. `POST /api/v1/applications/` and `POST /api/v1/applications/{application_id}/apply/` are available to every partner.

One related flag exists, `non_us_id_citizenships`, but it is enforced on **related party** applications under [business onboarding](/products/partner-api/guides/building/onboarding-businesses). `INTERNATIONAL_ID` on an individual application is enabled for your partnership by Jiko; confirm the citizenships you may submit with your Jiko point of contact before you build the form, because the rejection arrives at validation with nothing on the application to explain it.

### Three things you must do before you create an application

These are [Partner Obligations](/products/partner-api/partner-obligation), not API validations. Nothing in the API checks them, and an application that skips them is still accepted.

1. **Verify ownership of the phone number** on the application — a confirmation code, or equivalent.
2. **Verify ownership of the email address** on the application, the same way.
3. **Display Jiko's agreements and capture time-stamped consent.** Fetch them from `GET /api/v1/agreements/`, show them, then put the `version` you showed and the timestamp of consent on the application as `agreement_consent`. **Re-fetch for every new application** — the current version can change, and consent recorded against a stale version is not consent to what Jiko is obliged to have shown.


Where you build your own onboarding UX rather than using Jiko's, you are also required to perform proof of ownership of the identity itself — government ID checked against a live photo match, through a trusted vendor.

### Everything else

- **API credentials for the environment you are calling.** Build against sandbox first — the flow spans days once documents or manual review are involved, and sandbox is where you can exercise it. The [sandbox status simulator](#sandbox-testing) makes every terminal state reachable in seconds.
- **Everything the application needs, at creation time.** An individual application has no `PATCH`. `POST /api/v1/applications/` is the only place to supply the applicant's details, so collect the whole set before you call it. (A business application is the opposite — see [Onboarding businesses](/products/partner-api/guides/building/onboarding-businesses).)
- **An applicant who is at least 18.** A `date_of_birth` that puts them under 18 is rejected at validation.
- **An `investment_profile` matching the `employment_status`.** The profile is discriminated on that field, so sending employer details with `UNEMPLOYED`, or omitting them with `EMPLOYED`, is rejected at validation. A Jiko pocket holds a brokerage account as well as a bank account, which is why a suitability profile is part of KYC at all.
- **A way to collect and upload documents, as PNGs.** `DOCUMENTS_NEEDED` is a normal outcome, not an edge case, and it can occur more than once on a single application; an integration with no document path stalls there permanently. Uploads require a `Content-Type` of `image/png` — the header is pattern-matched, so convert before you upload.
- **A webhook subscription** for `application.approved`, `application.manual_review`, `application.documents_needed` and `application.rejected`. The payload is `application_id` only, so every event means "fetch the application" — including the approval, which is the only place `customer_id` appears. Subscriptions are recorded against the API user that creates them.
- **The v1 endpoints.** `/api/v2/applications/` is not exposed in production, so build against v1.


## The shape of the flow

1. **Create the application.** `POST /api/v1/applications/`
2. **Apply.** `POST /api/v1/applications/{application_id}/apply/`
3. **If Jiko asks for documents, upload them — and then apply again.**
4. **Wait for a terminal status**, delivered by webhook.


Creating an application does not start KYC. Applying does. An application sitting in `CREATED` will sit there indefinitely.

**Step 3 is a loop, and the second half of it is the part integrations miss.** Uploading the last outstanding document does not resume the review. It moves the application from `DOCUMENTS_NEEDED` to `PENDING`, which means "nothing is outstanding, and Jiko is waiting for you to resubmit". You must call `apply` again. An application parked in `PENDING` is waiting on you, not on Jiko, and no webhook will arrive to tell you so.

### Relevant API endpoints

| Step | Purpose | Endpoint |
|  --- | --- | --- |
| 1 | Fetch the agreements to display, before you build the application | GET `/api/v1/agreements/` |
| 2 | Create the application with the applicant's full details | POST `/api/v1/applications/` |
| 3 | Submit it for KYC | POST `/api/v1/applications/{application_id}/apply/` |
| 4 | Read the current status, the document flags and, on approval, `customer_id` | GET `/api/v1/applications/{application_id}/` |
| 5 | List outstanding document requests | GET `/api/v1/applications/{application_id}/documents/` |
| 6 | Upload a document (`Content-Type: image/png`) | POST `/api/v1/applications/{application_id}/documents/{document_type}/file/` |
| 7 | Resubmit once the status has moved to `PENDING` | POST `/api/v1/applications/{application_id}/apply/` |


## Create the application

```
POST /api/v1/applications/
```

| Field | Notes |
|  --- | --- |
| `name` | First and last name |
| `email` |  |
| `date_of_birth` | Must put the applicant at 18 or older |
| `phone_number` | E.164. Parsed as US by default |
| `address` |  |
| `identification_number` | SSN or the equivalent for the chosen type |
| `identification_type` | `SSN` (default), `PASSPORT`, `TIN`, `DRIVERS_LICENSE`, `INTERNATIONAL_ID` |
| `identification_number_issuing_country` | ISO 3166. Defaults to `US` |
| `citizenship_country` | ISO 3166. Defaults to `US` |
| `investment_profile` | See below |
| `agreement_consent` | Consent to Jiko's agreements |
| `originally_onboarded_at` | Optional. When you onboarded this person on your own side. Cannot be in the future |


### `investment_profile` is discriminated on employment status

A Jiko pocket holds a brokerage account as well as a bank account, so KYC includes a suitability profile. The shape of that profile depends on `employment_status`:

| `employment_status` | Extra fields |
|  --- | --- |
| `EMPLOYED` | Employer details |
| `INDEPENDENT` | — |
| `RETIRED` | — |
| `STUDENT` | — |
| `UNEMPLOYED` | — |


All variants carry banded `annual_personal_income` and `average_personal_net_worth`.

Send the variant that matches the employment status. Sending employer fields with `UNEMPLOYED`, or omitting them with `EMPLOYED`, is rejected at validation.

### Non-US applicants

`citizenship_country` and `identification_number_issuing_country` both default to `US`, and `identification_type` defaults to `SSN`, so an existing US-only integration keeps working unchanged.

`INTERNATIONAL_ID` is accepted only where the applicant's citizenship is on your partnership's allowlist. Outside that allowlist it is rejected at validation, regardless of what else is on the application. If you onboard non-US individuals, confirm the allowlist with your Jiko point of contact before building the form.

### `originally_onboarded_at`

If you are migrating customers you already onboarded elsewhere, set this to the date you originally onboarded them. It does not skip KYC — it records the history.

## Apply

```
POST /api/v1/applications/{application_id}/apply/
```

This submits the application for KYC. From here the status moves on its own, and you learn about it through webhooks.

## Lifecycle

| Status | Meaning | Who it is waiting on |
|  --- | --- | --- |
| `CREATED` | Created, not yet applied. Call `apply` | You |
| `SUBMITTED` | Submitted, under evaluation | Jiko |
| `DOCUMENTS_NEEDED` | Jiko needs documents before it can decide. Read the flags and the document list | You |
| `PENDING` | Every outstanding document has been supplied. **Call `apply` again** | You |
| `MANUAL_REVIEW` | Under human review at Jiko | Jiko |
| `APPROVED` | KYC passed. A customer now exists; read `customer_id`. Terminal | — |
| `REJECTED` | KYC failed. Terminal, and the application cannot be revived | — |


`PENDING` is the one to read carefully. It does not mean "in processing" — it is the state an application lands in once you have cleared the document requests, and it moves no further until you resubmit.

## Documents

An application in `DOCUMENTS_NEEDED` tells you what it needs through three booleans on the application object, and through its `documents` list:

| Flag | Means |
|  --- | --- |
| `id_verification_documents_needed` | Photo ID required |
| `identification_number_verification_document_needed` | Proof of SSN/TIN required |
| `address_verification_document_needed` | Proof of address required |


Read the outstanding requests:

```
GET /api/v1/applications/{application_id}/documents/
```

Each flag maps to a specific set:

| Flag | Upload |
|  --- | --- |
| `id_verification_documents_needed` | A `SELFIE`, **and** either both `ID_FRONT` and `ID_BACK`, or a `PASSPORT` |
| `identification_number_verification_document_needed` | `IDENTIFICATION_NUMBER_VERIFICATION` — an SSN card, a W-2, a tax return |
| `address_verification_document_needed` | `ADDRESS_VERIFICATION` — a recent utility bill, bank statement or lease |


Document types on the individual path: `ID_FRONT`, `ID_BACK`, `ID_BARCODE`, `SELFIE`, `PASSPORT`, `IDENTIFICATION_NUMBER_VERIFICATION`, `ADDRESS_VERIFICATION`.

Uploads must carry `Content-Type: image/png`. The header is pattern-matched, so a JPEG or a PDF is rejected before the file is read.

Upload against the application and document type:

```
POST /api/v1/applications/{application_id}/documents/{document_type}/file/
```

or, for a customer who already exists:

```
POST /api/v1/customers/{customer_id}/documents/{document_type}/file/
```

Each document carries a status: `PENDING_UPLOAD` → `PENDING_REVIEW` → `APPROVED` or `INVALID`. An `INVALID` document must be re-uploaded — it does not reject the application on its own, but the application will not move until it is replaced.

A driver's license usually needs `ID_FRONT` **and** `ID_BACK`, sometimes `ID_BARCODE`. A passport is a single `PASSPORT` document. Read the requested list rather than guessing from the ID type.

**Then apply again.** Once no document request is outstanding, the application moves itself to `PENDING` and stops. `POST /api/v1/applications/{application_id}/apply/` is what resumes the review.

## Sandbox testing

In sandbox, the `identification_number` you submit decides the outcome, so every status is reachable without real KYC. The first digit controls what happens on the first `apply`:

| Prefix | Status after `apply` |
|  --- | --- |
| `2` | `DOCUMENTS_NEEDED` |
| `4` | `APPROVED` |
| `5` | `REJECTED` |
| Anything else | `MANUAL_REVIEW` |


For a `2`, the **second** digit selects which flags are raised:

| Prefix | Documents requested |
|  --- | --- |
| `21` | `id_verification_documents_needed` |
| `22` | `identification_number_verification_document_needed` |
| `23` | `address_verification_document_needed` |
| `24` | both `id_verification_documents_needed` and `identification_number_verification_document_needed` |


And the **third** digit decides where the application lands after you upload the documents and apply again: `1` sends it to `MANUAL_REVIEW`, anything else to `APPROVED`. So `241` exercises a two-document round followed by manual review, and `240` the same round followed by approval.

Sandbox appends a unique suffix to the identification number you submit, so the same value can be reused across applications without colliding. That also means the number you read back is not the one you sent.

## Webhooks

| Event | Meaning |
|  --- | --- |
| `application.approved` | KYC passed; a customer exists |
| `application.manual_review` | Routed to human review |
| `application.documents_needed` | Documents required |
| `application.rejected` | KYC failed |


Payload: `application_id`. Fetch the application to learn what changed and, on approval, to read `customer_id`.

`application.documents_needed` can fire more than once on a single application — a second round of documents after a first was reviewed is normal. Treat it as "read the outstanding requests again", not as a one-time step.

## After approval

The application's `customer_id` is the handle for everything downstream:

```
GET   /api/v1/customers/{customer_id}/
PATCH /api/v1/customers/{customer_id}/
POST  /api/v2/customers/{customer_id}/pockets/
GET   /api/v2/customers/{customer_id}/pockets/
```

### An approved customer does not necessarily have a pocket

For most partnerships, approval creates the **customer** and nothing else. Opening a pocket is a call you make.

Automatic pocket-and-portal creation at approval does exist, but it is a legacy behavior limited to an explicit allowlist of partner IDs held in Jiko's configuration — the code path is named for it. If your partnership is on that list, an approved customer already has a pocket and a virtual bank account portal with a routing and account number, ready to receive ACH. If it is not, `GET /api/v2/customers/{customer_id}/pockets/` comes back empty and stays empty until you create one.

Do not infer which case you are in from a single approval in sandbox. Ask your Jiko point of contact, and write the integration so that it reads the pocket list rather than assuming either answer.

Creating a pocket takes a `pocket_name` of up to 100 characters, a `deposit_strategy_id`, an optional `reinvestment_strategy_id`, and — where your partnership permits the choice — a `type`.

Available strategies are listed at `GET /api/v2/trading-strategies/`. The deposit strategy governs how incoming funds are invested; the reinvestment strategy governs what happens when holdings mature. Both can be changed later on an existing pocket.

The choice has a direct payments consequence: it sets the maturity profile of the pocket's holdings, and therefore how much of the balance is available at T+0 rather than T+1. Read `liquidation_value_t0` and `liquidation_value_t1` on the pocket's portfolio before instructing an outbound payment — `total_value` is what the customer owns, the liquidation values are what can actually be moved, and when.

A customer may hold up to **20 pockets per partner** by default. The limit counts every pocket ever created for that customer, **including closed ones** — closing a pocket does not free a slot.

## Endpoints

| Operation | Endpoint |
|  --- | --- |
| List agreements to display | `GET /api/v1/agreements/` |
| Create an application | `POST /api/v1/applications/` |
| Get an application | `GET /api/v1/applications/{application_id}/` |
| Apply, and re-apply | `POST /api/v1/applications/{application_id}/apply/` |
| List document requests | `GET /api/v1/applications/{application_id}/documents/` |
| Upload an application document | `POST /api/v1/applications/{application_id}/documents/{document_type}/file/` |
| Upload a customer document | `POST /api/v1/customers/{customer_id}/documents/{document_type}/file/` |


There is no `PATCH` on an individual application. Everything the applicant supplies goes in at creation.

## See also

- [Onboarding businesses](/products/partner-api/guides/building/onboarding-businesses)
- [Partner Obligations](/products/partner-api/partner-obligation) — phone, email, disclosures, identity proofing
- [Individuals reference](/products/partner-api/reference/individuals)
- [Pockets](/products/partner-api/reference/pockets/list-pockets-v2)
- [Webhooks](/products/partner-api/guides/building/webhooks)