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 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:

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:

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.

Applying

Once an application is created, extract the application_id from the response, Then, call Apply to activate the KYC process.

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:

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.

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.