Personal Identities

Suggest Edits

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",//Must be in 5 digit format
    "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",//Must be in 5 digit format
    "city": "Rushville",
    "state": "IN",
    "country": "US"
  },
  "dateOfBirth": "1995-04-25"
}
  1. Monitor the upgradeRequirements (US end users only) 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",//Must be in 5 digit format
    "city": "Rushville",
    "state": "IN",
    "country": "US"
  },
  "dateOfBirth": "1987-03-25", 
  "ssn": "305464885"

List of possible upgradeRequirements:

-Phone is invalid
-Phone is not provided
-Name is invalid
-Name is not provided
-Address is invalid
-Address is not provided
-Ssn is invalid
-Ssn is not provided
-DateOfBirth is invalid
-DateOfBirth is not provided

📘

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(US end users only) 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) // 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.

Scanned documents are not supported and will automatically be rejected by the OCR. The end user should take a photo of their document, making sure there is no blur or glare, keeping all corners of the document within view of the image (DL/Gov ID needs a picture of both back and front, passport needs a picture of the entire front facing document).

Max file size: 10 MB
File resolution: 600 DPI or approx. 1200x1800 recommended.
Min recommended resolution: 400 DPI or 800x1200
Supported file types: jpg, jpeg, jpe, jif, jfif, png

👍

Supported File Types At This Time

".PNG",
".JPEG",
".JPG",
".JPE",
".JIF",
".JFIF"

Document Check Status

For document uploads, you can understand where the process is at based around the Document status check. There are 4 status's that you'll want to pay attention to. https://developers.fortress.io/reference/get_api-compliance-v1-personal-identities-identityid

  • approved
  • resubmit
  • rejected
  • manualReviewNeeded

resubmit means there was an issue reading the document, and the end user should take another image, make sure it's clear and captures all sides of the document, and is a supported file type.

manualReviewNeeded goes into a queue for compliance to review and either set to rejected, approved or resubmit

rejected is an issue with the document, expired, or fraudulent.

Note: After 3 rejected document checks, the end user is not allowed to move forward.
3 resubmit that do not approve will lead to 1 rejected.

Updated 5 months ago