Identities

Your End-User

Identities are an object that represents your end-user and their PII/documentation. On initial creation, identities only require a first name, last name, email and phone number which will return you an initial risk assessment of the particular individual. These initial identities are considered L0 (unverified user), and allow limited functionality. The bulleted list below shows functionality for the different tier groups.

👍

Want to make the onboarding process a lot faster?

Visit our Elements (KYC Widget) section for our own customizable front end widget that collects and submits all of your end user's information over our API for you!

L0 (First/Last name, email, phone number):

• Create and save payment methods
• Perform "one time" purchases of NFTs (reoccurring purchases coming at a later date*)

L1 (verified PII, DoB, address, tax-id):

• Create accounts
• Deposit/Withdrawal fiat to/from a Fortress account
• Crypto buy/sell through Fortress's API

L2 (verified PII and documentation):

• Crypto deposit/withdrawals in a Fortress account

📘

Creating a new identity

The API Reference section lists all relevant fields for creating a new identity including PII. If you're just looking to create an initial identity and get a risk score, you can just collect first name, last name, phone # and email and submit. If you want extended functionality for the particular end-user later on, you can PATCH their identity and add the PII information.

What might a flow look like for onboarding a new end-user:

Identity Container vs Personal/Business-Identities

There are three different objects in our API that are related to your end user, the identity-container, personal-identity, and business-identity. The identity-container is an object that groups any personal/business-identities together, and is automatically established whenever you create a new identity in the API. The identity-container is used to establish relationships between personal and business identities, although you won't be interacting with the container object nearly as much as the personal/business objects.

personal-identities and business-identities will be your main focus as an integrator, as these objects contain information about the end user, their KYC/KYB level, next steps for KYC upgrade, and are also the objects you reference for other functionality in the API. When manipulating these objects (updating/adding information to pass KYC/KYB, creating accounts, establishing externalAccounts), remember to target the correct Id(personalIdentityId or businessIdentityId) in your API calls otherwise you'll receive a 404 error.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", //identity-container ID
  "firstName": "John",
  "middleName": "Second",
  "lastName": "Doe",
  "phone": "+12025550165",
  "email": "[email protected]",
  "personalIdentity": "3fa85f64-5717-4562-b3fc-2c963f66afa6", //personal-identity ID *Used for all other API functionality
  "businessIdentities": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6" //business-identity ID *Used for all other API functionality
  ],
  "address": {
    "street1": "4220 Davisson Street",
    "postalCode": "46173", //Must be in 5 digit format
    "city": "Rushville",
    "state": "IN",
    "country": "US"
  },
  "dateOfBirth": "2022-08-16",
  "ssn": "305464885"
}

Domestic vs International End Users

Fortress allows KYC/KYB, custody, and payments for both end users residing in the US as well as international. The KYC process in particular differs between domestic and international end users, mostly for individuals. Here is the quick step by step overview for reaching L1 for both a domestic and international personal-identity. Note that there are two approaches you can take for domestic end users.

Domestic

Progressive:

• Provide first name, last name, email, and phone number and initiate global watchlist/sanctions check. Check returned object's field upgradeRequirements to see what PII needs to be obtained and provided.
• PATCH the created personal-identity with the additional KYC information (DoB, Address, SSN) returned in the previous step and run another KYC check.
• On successful KYC check, kycLevel is moved from L0 -> L1

Upfront:

• Provide all relevant information on identity creation (name, phone number, email, DoB, Address, SSN).
• Initiate KYC check and look for kycLevel to move from L0 -> L1. If not, upgradeRequirements will populate with fields that were found invalid.
• PATCH updated fields found invalid with correct information from the end user and initiate another KYC check.

International:

• Provide first name, last name, email, phone number, date of birth, and address (no SSN needed). When onboarding a non-US personal identity, add the optional parameter to your POST /identity-container call, "upgradeKYC" : false\.
• Upload personal document (passport works best) to the personal-identity and the KYC check will initiate automatically.

The following sections will cover personal/business identities as well as the KYC flow.