# Onboarding Individuals

Now that you've sent your first signed request to the API, you're ready to start
onboarding new customers.

Our onboarding system is based on *Applications*, which spawn a *Customer* once
approved.

An *Application* is the precursor to creating a *Customer*, and must contain
important, but sensitive, user data. This user data must undergo strict scrutiny
and verification of ownership. This process is known as KYC (Know Your
Customer).

Current application features include:

1. Creating an Application using a Customer's information
2. Submitting an Application to trigger the KYC process and account creation
3. Retrieving an Application to review the information entered and survey the
application status (`CREATED`, `SUBMITTED`, `DOCUMENTS_NEEDED`, `APPROVED`,
`REJECTED`)


Depending on your program details, Jiko will complete most of the required KYC
processes. Three requirements must be fulfilled **before** an application can be
created:

1. Verify ownership of the phone number used in the application
2. Verify ownership of the email address used in the application.
3. Display
[agreements provided by Jiko](/products/partner-api/reference/individuals/list_agreements_api_v1_agreements__get)
to the user, note the version number, and get time-stamped consent. The
version number and timestamp must be attached to the application.


If you're interested in pass-through onboarding, where Jiko vets and relies on
your KYC process, please get in touch with your Jiko point of contact.

## Creating an Application

Once you’ve fulfilled all these requirements, you can call
[Create Application](/products/partner-api/reference/individuals/create_application_api_v1_applications__post):


```bash
body='{
    "identification_number": "999999999",
    "name": {
        "first_name": "Jiko",
        "last_name": "Customer"
    },
    "email": "jiko@example.com",
    "phone_number": "15551234567",
    "date_of_birth": "1970-01-01",
    "investment_profile": {
        "income": "BETWEEN_100K_AND_250K",
        "net_worth": "BETWEEN_1M_AND_5M",
        "occupation": "Investor",
        "employment_status": "EMPLOYED"
    },
    "agreement_consent": {
        "version": "1",
        "timestamp": "2023-01-01T12:00:00+00:00"
    },
    "address": {
        "street_address": "2000 Allston Way",
        "city": "Berkeley",
        "postal_code": "94701",
        "state": "CA",
        "country": "USA"
    }
}'
send_jiko_request "POST" "/api/v1/applications/" $body
```

Or use Python:


```python
endpoint = "/api/v1/applications/"
url = root + endpoint
body = {
    "identification_number": "999999999",
    "name": {
        "first_name": "Jiko",
        "last_name": "Customer"
    },
    "email": "jiko@example.com",
    "phone_number": "15551234567",
    "date_of_birth": "1970-01-01",
    "investment_profile": {
        "income": "BETWEEN_100K_AND_250K",
        "net_worth": "BETWEEN_1M_AND_5M",
        "occupation": "Investor",
        "employment_status": "EMPLOYED"
    },
    "agreement_consent": {
        "version": "1",
        "timestamp": "2023-01-01T12:00:00+00:00"
    },
    "address": {
        "street_address": "2000 Allston Way",
        "city": "Berkeley",
        "postal_code": "94701",
        "state": "CA",
        "country": "USA"
    }
}

headers = {}
headers["Authorization"] = "Bearer " + token
headers["x-jiko-idempotency"] = get_idempotency()
headers["x-jiko-signature"] = get_signature(
   headers["x-jiko-idempotency"], endpoint, json.dumps(body)
)

resp = requests.post(url, json=body, headers=headers)
print(resp.text)
```

The first key in the JSON response is the ID for this application, used in the
next section. For a more detailed look at the properties and available values,
see
[Get Application](/products/partner-api/reference/individuals/get_application_api_v1_applications__application_id___get).

## Applying

Once an application is created, extract the `application_id` from the response,
Then, call
[Apply](/products/partner-api/reference/individuals/apply_api_v1_applications__application_id__apply__post)
to activate the KYC process.


```bash
application_id="id-from-response";
send_jiko_request "POST" "/api/v1/applications/$application_id/apply/"
```

Once this endpoint has been called, the status of the application will change
for the first time.

These are the available application statuses:

| Application Status | Description |
|  --- | --- |
| `CREATED` | This is the initial state of all applications. When you're ready, call [Apply](/products/partner-api/reference/individuals/apply_api_v1_applications__application_id__apply__post) to change the status to `SUBMITTED` |
| `SUBMITTED` | Once an application is submitted via the Apply endpoint, it maintains this status while the system processes the application. Automatic KYC then returns Application status `DOCUMENTS_NEEDED`, `MANUAL_REVIEW` or `APPROVED`. Poll [Get Application](/products/partner-api/reference/individuals/get_application_api_v1_applications__application_id___get) or subscribe to the [`application` Event Types](/products/partner-api/reference/events/list_event_types_api_v1_events_types__get) to monitor Application status changes. |
| `DOCUMENTS_NEEDED` | This is the only state that requires further action. You must collect ID documents from the end-user and upload them to verify their identity. See more at [Upload Document to Application](/products/partner-api/reference/individuals/upload_document_to_application_api_v1_applications__application_id__documents__document_type__file__post). Which documents are needed is based on the flags that are part of the Application response. Once all flags have been cleared, the application status is automatically set to `PENDING`, which means that the application is ready to be submitted again. The flags are as follows: 1. `id_verification_documents_needed`2. `identification_number_document_needed`3. `address_verification_document_needed` |
| `PENDING` | If an application needed further action (for example `DOCUMENTS_NEEDED`), this state signifies that the required actions are completed and the application is ready to apply again. |
| `MANUAL_REVIEW` | This state means that the application is being reviewed manually based on the documents that were provided. |
| `REJECTED` | This state is final and means the application has been rejected. An application can not be revived after it reaches this state. |
| `APPROVED` | When an application reaches this state, a customer is created with an account and a portal with routing and account numbers, ready to receive external ACH fund transfers. |


## Controlling Application Status

In the sandbox API, the first number in the SSN (identification_number) allows
you to control which status the application receives after applying:

- SSN starts with 2: `DOCUMENTS_NEEDED`
  - Control document needed flags
    - SSN starts with 21: `id_verification_documents_needed` is set to `true`
    - SSN starts with 22: `identification_number_document_needed` is set to
`true`
    - SSN starts with 23: `address_verification_document_needed` is set to
`true`
    - SSN starts with 24: `id_verification_documents_needed` and
`identification_number_document_needed` is set to `true`
  - Control transition after uploading documents and applying again
    - SSN starts with 2*1: Transitions to `MANUAL_REVIEW`
    - SSN starts with 2**: Transitions to `APPROVED`
- SSN starts with 3: `MANUAL_REVIEW`
- SSN starts with 4: `APPROVED`
- SSN starts with 5. `REJECTED`
- SSN starts with anything else: Application ends in `MANUAL_REVIEW`


## Uploading Documents

If and when an application receives the status `DOCUMENTS_NEEDED`, you will have
to upload images of documents to better confirm the identity of the customer
before they can be approved. The types of documents that can be uploaded through
the API are `ID_FRONT`, `ID_BACK`, `SELFIE`, `PASSPORT`,
`IDENTIFICATION_NUMBER_VERIFICATION`, `ADDRESS_VERIFICATION`, and `OTHER`. These
documents can be uploaded at any time but if the application status is
`DOCUMENTS_NEEDED`, it's based on which flag is set to true:

- `id_verification_documents_needed`:
  - `ID_FRONT`
  - `ID_BACK`
  - `SELFIE` or `PASSPORT`
- `identification_number_document_needed`:
  - `IDENTIFICATION_NUMBER_VERIFICATION` (SSN card, W-2, Tax return)
- `address_verification_document_needed`:
  - `ADDRESS_VERIFICATION` (Recent Utility Bill, Recent Bank Statement, Recent
CC Statement, Lease Agreement, Gov Issued Photo ID, Property Tax Bill)


These documents should be images under 5 MB and should have the
`application/png` content type.


```bash
endpoint="/api/v1/applications/$application_id/documents/SELFIE/file/";
idempotency=$(get_idempotency);
curl --request POST \
 --url https://$PREFIX.sandbox-api.jikoservices.com$endpoint \
 --header "Authorization: Bearer $TOKEN" \
 --header 'Content-Type: image/png' \
 --header "x-jiko-idempotency: $idempotency" \
 --data-binary '@/your/dir/here/image.png';
```

If all goes well, you should receive a success message.

These documents are sensitive personal information and can not be retrieved
after upload. Once all flags have been cleared, the application will be
automatically updated to the `PENDING` status. Apply again and the application
will be re-evaluated if you are not in the sandbox. The sandbox currently has no
path out of the `DOCUMENTS_NEEDED` status.