Individual
An individual entitity is essentially a person that owns an account or has access to a service.
Depending on the service that an individual entity is trying to gain access to, eligibility is determined based on the entity's access_level
Access Level spans from 1 to 5 (1 being the lowest and 5 being the highest). Services that require an entity_id will also make mention of the minimum access_level required.
Create an individual entity
Endpoint
{BASE_URL}/entities/individual
Method: POST.
| Parameter | Description | Required |
|---|---|---|
first_name | The individual's first name string | True |
middle_name | The individual's middle name string | False |
last_name | The individual's last name string | True |
date_of_birth | The individual's date of birth object object | False |
address | The individual's address object object | False |
id_number | The individual's id number string | False |
id_type | The individual's id type for which an id number was provided enum Available types are ssn, passport, drivers_license | False |
email_address | The individual's email address string | False |
phone | The individual's phone number object object | False |
date_of_birth object
| Parameter | Description | Required |
|---|---|---|
day | The individual's day of birth int | True |
month | The individual's month of birth int | True |
year | The individual's year of birth int | True |
address object
| Parameter | Description | Required |
|---|---|---|
street | The individual's address street string | True |
city | The individual's address city string | True |
state | The individual's address state abbreviation. E.G DE, CA, MD string | True |
postal_code | The individual's address postal code string | True |
country | The individual's address country in ISO 3166-2 format string | True |
phone object
| Parameter | Description | Required |
|---|---|---|
phone_number | A valid phone number string | True |
country_code | A valid country code for the phone number in ISO 3166-2 format string | True |
Sample Request
curl --location --request POST 'https://api.stack-ft.com/entities/individual' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"first_name": "John",
"middle_name": "A",
"last_name": "Dorian",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1990
},"address": {
"street": "123 stack ave",
"city": "Middletown",
"state": "DE",
"postal_code": "19705",
"country": "US"
},
"email": "[email protected]",
"id_type": "ssn",
"id_number": "234567676"
}'
Sample Response
{
"status": "success",
"request_id": "21f049e7-bc76-4a9b-8a7c-0afee5ab0280",
"entity": {
"first_name": "John",
"middle_name": "A",
"last_name": "Dorian",
"entity_id": "i_uuid_ba82e4fc-67f9-44ab-86f4-238d6d3d54d6"
}
}
INFO
Congratulations on creating your first individual entity. By default, the entity's access_level is set to 1 but this value increases based on how much information we have about the entity.
Get an individual entity
You can at any time make a request to get the details of an individual. This will also return, the access_level and missing_data.
Endpoint
{BASE_URL}/entities/individual?entity_id=:ENTITY_ID
Method: GET.
Sample Request
curl --location --request GET 'https://api.stack-ft.com/entities/individual?entity_id=i_uuid_ba82e4fc-67f9-44ab-86f4-238d6d3d54d6' \
--header 'Authorization: API_KEY' \
--data-raw ''
Sample Response
{
"status": "success",
"request_id": "8d4d31f2-3703-461a-bd69-4b77a3de8069",
"entity": {
"first_name": "John",
"middle_name": "A",
"last_name": "Dorian",
"entity_id": "i_uuid_ba82e4fc-67f9-44ab-86f4-238d6d3d54d6",
"access_level": 3,
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1990
},
"user_address": {
"street": "123 stack ave",
"city": "Middletown",
"state": "DE",
"postal_code": "19705",
"country": "USA"
},
"missing_data": [
"phone_number"
],
"verification_status": "pending"
}
}
Update an individual entity
If you ever need to update an entity, pass the same data in the same format as what is used to create an entity ( please refer to the parameters). All fields are OPTIONAL. You additionally have to pass a REQUIRED query parameter called entity_id and the individual's entity id.
WARNING
When a user has an access_level of 5, not all information can be updated. The only fields that can be updated at this point are email_address phone address
Endpoint
{BASE_URL}/entities/individual?entity_id=:ENTITY_ID
Method: PUT.
Sample Request
curl --location --request PUT 'https://api.stack-ft.com/entities/individual?entity_id=i_uuid_ba82e4fc-67f9-44ab-86f4-238d6d3d54d6' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"first_name": "John",
"middle_name": "A",
"last_name": "Dorian",
"date_of_birth": {
"day": 1,
"month": 1,
"year": 1990
},"address": {
"street": "123 stack ave",
"city": "Middletown",
"state": "DE",
"postal_code": "19705",
"country": "USA"
},
"email": "[email protected]",
"id_type": "ssn",
"id_number": "234567676"
}'
Sample Response
{
"status": "success",
"request_id": "21f049e7-bc76-4a9b-8a7c-0afee5ab0280",
"entity": {
"first_name": "John",
"middle_name": "A",
"last_name": "Dorian",
"entity_id": "i_uuid_ba82e4fc-67f9-44ab-86f4-238d6d3d54d6"
}
}
Verify an Entity
INFO
The only way you can raise an entity's access_level to 4 or 5 is by verifying the identity of the entity. If you have not provided ALL the information about the entity, you will not be able to raise their access_level to 5
When you send in a request to verify the identity of an entity, we first try to automatically confirm their identity using the information provided to us. This way, we can instantly verify about 85% of entities. In some cases, we will need to do a little more on our end before we can approve or reject an entity. If we are unable to instantly make a decision on a verification request, we will respond with a verification_status of in_progress while we manually look into the request. Once we make a final decision (usually with a few minutes - hours), we will update the verification_status with either verified or failed.
If a verification status comes back as failed, we will require a different way to verify the entity's identity. This will be communicated with you, the account owner.
Endpoint
{BASE_URL}/entities/individual/verify?entity_id=:ENTITY_ID
Method: POST.
Sample Request
curl --location --request POST 'https://api.stack-ft.com/entities/individual/verify?entity_id=i_uuid_ba82e4fc-67f9-44ab-86f4-238d6d3d54d6' \
--header 'Authorization: API_KEY' \
--header 'Content-Type: application/json' \
--data-raw ''
Sample Response
{
"status": "success",
"request_id": "0e8a7a53-92ab-43a8-816c-2ec2a9e1d6ae",
"entity": {
"entity_id": "i_uuid_ba82e4fc-67f9-44ab-86f4-238d6d3d54d6",
"access_level": 5,
"missing_data": [],
"verification_status": "verified"
}
}
INFO
If we are unable to verify the identity of an entity due to incomplete information, we will not return an error. We will simply return the current access_level of the entity and a missing_data array, letting you know what is missing. You can always use the update endpoint to update the entity and provide any missing information.