Personal Identities

Personal identities are related to individual customers who are using your platform. They are an object in our API that relates specific information about the individual (PII/Proof of Id), their KYC status, and any requirements needed for upgrading to the next KYC tier. Those 3 aspects will be what you need to onboard new end users and manage their compliance utilizing our APIs.

Depending on how you're structuring your platform, you can either obtain and pass through all KYC requirements initially on new onboardings, or stagger out the onboarding process for tiered functionality pertaining to your platform and our APIs.

Steps

  1. Create the initial identity-container to get started by entering in the information of the end user.
POST /api/trust/v1/identity-containers

//Sample Request

{
  "firstName": "John",
  "middleName": "Second", //optional
  "lastName": "Doe",
  "phone": "+12025550165",
  "email": "[email protected]",
  "address": { //optional
    "street1": "4220 Davisson Street",
    "postalCode": "46173",
    "city": "Rushville",
    "state": "IN",
    "country": "US"
  },
  "dateOfBirth": "1995-04-25", //optional
  "ssn": "305464885" //optional
}

📘

Optional Information

Remember, only the first/last name, phone number, and email are required to create a new identity. You can however obtain all PII information from your end user up front and pass through all information on a new identity creation to get them a higher KYC tier quicker.

 1a. If you only obtained the required info to create an L0 identity and want to upgrade, you'll need to 
       followup with a PATCH call to add the extra information. Our KYC process will initiate on new information 
       provided after a PATCH call automatically (this will change at a later date so that you can initiate the KYC 
       process when you see fit).
PATCH /api/trust/v1/personal-identities/{personalIdentityId}

//Sample Request

{
  "address": { 
    "street1": "4220 Davisson Street",
    "postalCode": "46173",
    "city": "Rushville",
    "state": "IN",
    "country": "US"
  },
  "dateOfBirth": "1995-04-25"
}
  1. Monitor the upgradeRequirements field in the identity object to know what information needs to be provided for the end user to get a higher KYC tier. This will be accomplished by asking the end user to provide a value for the fields that populate this array.
GET /api/trust/v1/personal-identities/{personalIdentityId}

//Sample Response

...
"upgradeRequirements" : [
  "Address is invalid",
  "DateOfBirth is invalid",
  "Ssn is not provided"
],
"kycLevel" : "L0",
...
  1. PATCH in the updated/correct information to initiate another KYC process and see if the end user kycLevel is upgraded.
PATCH /api/trust/v1/personal-identities/{personalIdentityId}

//Sample Request Schema

  "address": { 
    "street1": "4220 Davidson Street",
    "postalCode": "45221",
    "city": "Rushville",
    "state": "IN",
    "country": "US"
  },
  "dateOfBirth": "1987-03-25", 
  "ssn": "305464885"

📘

KYC Process

If the information the end user provided the first time around didn't pass our KYC checks, you'll know this by looking at the upgradeRequirements field. This will be your cue to try and get the end user to provide you with updated/correct information. You'll then PATCH in this updated/correct information and the KYC process will initiate again.

If the end user is unable to pass the correct information after a second time, we advocate that you let the information be manually reviewed on our side by compliance personnel. They will either approve of the information provided and update the kycLevel, or communicate what would be needed for the end user to pass KYC to you, the integrator.

Proof of Id/Document Upload

If you're looking to let end users deposit/withdrawal crypto with our APIs, or are onboarding an international end user, the end user will need to provide a proof of ID to upgrade their kycLevel to L2. A proof of ID can be a driver's license, government ID, or passport. Use the following call to upload a document to a personal-identity

POST /api/trust/v1/personal-identities/{personalIdentityId}/documents

//Sample Request Schema
//multipart/form-data

DocumentType : "license" //[ license, identificationCard, passport ]
DocumentFront : "string"($binary)
DocumentBack : "string"($binary) //optional, used for Driver's License or Government Issued ID

🚧

Image Quality

OCRs can be finicky when it comes to image quality and reading a proof of ID. It's best to ensure that your end user is uploading a quality picture, with all corners of the ID showing, no glare, no blurriness and all information in view. This will ensure the best possible chance of automatic approval by our KYC process and an expedited upgrade to the L2 KYC level.


Did this page help you?