Skip to main content

Profiles

A profile represents an end user customer or business registered by a Program. Each complete profile will have an associated account, which allows the profile to transact.

If your program would like to leverage our KYC/AML functionality, personal information about end user customers or businesses will need to be collected. Your program manager will walk you through KYC requirements specific to your program.

If your Program chooses to use internal KYC/AML, a profile will still need to be created for each user.

Register a Profile

Submit a profile with relevant personally identifiable information (PII). This will register the profile if no other profile matches its PII. Information stored on a profile will be used during KYC and card issuance.

Some information, like taxId.idNumber, will be encrypted at rest and will not be returned by our API, instead we will return has_business_ein or has_tax_id flags.

Profile type can be either a PERSONAL profile or a BUSINESS profile.

Phone numbers are limited to 10 digits when not providing the country code (e.g. 5555555555). If the country code is provided then it must start with a + symbol followed by up to 3 digits not beginning with 0 (e.g. +15555555555). The type of phone number can be either HOME, MOBILE, or WORK.

The state that corresponds to an address will be a valid two-character abbreviation of the US state. The country will be a valid ISO 3166-1 three-character abbreviation of the country code.

The tax ID type can be either SSN, ITIN, or EIN.

If the profile is a BUSINESS profile, the legal business name, the EIN tax ID of the business, the address of the business, and the business's structure must also be provided.

POST /profiles

{
"id": "423d2f77-697a-4f1e-8d7a-3b3362917d7c",
"type": "BUSINESS",
"email": "john.h.doe@example.com",
"name": {
"prefix": "Dr.",
"first_name": "John",
"middle_name": "Henry",
"last_name": "Doe",
"suffix": "Jr."
},
"dob": "1980-01-01",
"phone_number": {
"number": "5555555555",
"type": "HOME"
},
"address": {
"city": "Alexandria",
"state": "VA",
"street1": "42-2630 Hegal Place",
"street2": "Apt 2",
"zip": "22331",
"country": "USA"
},
"shipping_address": {
"city": "Alexandria",
"state": "VA",
"street1": "612 N St Asaph St",
"street2": "",
"zip": "22314",
"country": "USA"
},
"tax_id": {
"id_number": "555555555",
"id_type": "SSN"
},
"business_info": {
"business_name": "Acme Co",
"business_ein": "987654321",
"business_address": {
"city": "Alexandria",
"state": "VA",
"street1": "123 Rolling Lane",
"zip": "22331",
"country": "USA"
},
"business_structure": "CORPORATION"
}
}

Response:

{
"id": "423d2f77-697a-4f1e-8d7a-3b3362917d7c",
"created_dt": "2022-01-07T15:52:23.442264-05:00",
"updated_dt": "2022-01-07T15:52:23.442264-05:00",
"type": "BUSINESS",
"program_id": "f8621cf6-7019-44ea-9b79-a2f513caf71e",
"email": "john.h.doe@example.com",
"name": {
"prefix": "Dr.",
"first_name": "John",
"middle_name": "Henry",
"last_name": "Doe",
"suffix": "Jr."
},
"dob": "1980-01-01",
"username": null,
"phone_number": {
"number": "5555555555",
"type": "HOME"
},
"address": {
"city": "Alexandria",
"state": "VA",
"street1": "42-2630 Hegal Place",
"street2": "Apt 2",
"zip": "22331",
"country": "USA"
},
"shipping_address": {
"city": "Alexandria",
"state": "VA",
"street1": "612 N St Asaph St",
"street2": "",
"zip": "22314",
"country": "USA"
},
"tax_id": {
"has_tax_id": true,
"id_type": "SSN"
},
"status": "ONBOARDING",
"business_info": {
"business_name": "Acme Co",
"has_business_ein": true,
"business_address":
{
"city": "Alexandria",
"state": "VA",
"street1": "123 Rolling Lane",
"zip": "22331",
"country": "USA"
},
"business_structure": "CORPORATION"
}
}

User Consents

Figure provides a rich API for defining materials that must be acknowledged by end users in order to open and use a profile. The API is described in detail on the Onboarding Consents page.

Retrieve profiles

Fetch a limited set of metadata for all profiles that your program has registered and manages.

This response will be paginated.

GET /profiles

Retrieve an individual profile

Fetch the requested profile.

info

Not all information will be returned, such as taxId.id_number which is encrypted at rest and not returned by our API.

info

Usernames can only be set and returned for PERSONAL profiles.

GET /profiles/:profile_id

Response:

{
"id": "423d2f77-697a-4f1e-8d7a-3b3362917d7c",
"created_dt": "2022-01-07T15:52:23.442264-05:00",
"updated_dt": "2022-01-07T15:52:23.442264-05:00",
"type": "BUSINESS",
"program_id": "f8621cf6-7019-44ea-9b79-a2f513caf71e",
"email": "john.h.doe@example.com",
"name": {
"prefix": "Dr.",
"first_name": "John",
"middle_name": "Henry",
"last_name": "Doe",
"suffix": "Jr."
},
"dob": "1980-01-01",
"phone_number": {
"number": "5555555555",
"type": "HOME"
},
"address": {
"city": "Alexandria",
"state": "VA",
"street1": "42-2630 Hegal Place",
"street2": "Apt 2",
"zip": "22331",
"country": "USA"
},
"shipping_address": {
"city": "Alexandria",
"state": "VA",
"street1": "612 N St Asaph St",
"street2": "",
"zip": "22314",
"country": "USA"
},
"tax_id": {
"has_tax_id": true,
"id_type": "SSN"
},
"status": "APPROVED",
"business_info": {
"business_name": "Acme Co",
"has_business_ein": true,
"business_address": {
"city": "Alexandria",
"state": "VA",
"street1": "123 Rolling Lane",
"zip": "22331",
"country": "USA"
},
"business_structure": "CORPORATION"
}
}

Add a username to a profile

Associate the given username with the given profile. Usernames can only be set for PERSONAL profiles.

Includes an option to append a random suffix to the username if the provided username is already taken.

PATCH /profiles/:profile_id/username
{
"username": "janesmith",
"append_suffix": true
}

Response:

  "id": "423d2f77-697a-4f1e-8d7a-3b3362917d7c",
"created_dt": "2022-01-07T15:52:23.442264-05:00",
"updated_dt": "2022-01-07T15:52:23.442264-05:00",
"type": "PERSONAL",
"program_id": "f8621cf6-7019-44ea-9b79-a2f513caf71e",
"email": "john.h.doe@example.com",
"name": {
"prefix": "Dr.",
"first_name": "John",
"middle_name": "Henry",
"last_name": "Doe",
"suffix": "Jr."
},
"dob": "1980-01-01",
"username": "janesmith-DBmE3eqm",
"phone_number": {
"number": "5555555555",
"type": "HOME"
},
"address": {
"city": "Alexandria",
"state": "VA",
"street1": "42-2630 Hegal Place",
"street2": "Apt 2",
"zip": "22331",
"country": "USA"
},
"shipping_address": {
"city": "Alexandria",
"state": "VA",
"street1": "612 N St Asaph St",
"street2": "",
"zip": "22314",
"country": "USA"
},
"tax_id": {
"has_tax_id": true,
"id_type": "SSN"
},
"status": "APPROVED",
}

Update an existing profile

Update an existing profile. A successful request contains at least one update.

PATCH /profiles/:profile_id
{
"email": "jsmith@gmail.com",
"name":
{
"prefix": "Mr.",
"first_name": "Bob",
"middle_name": "Peter",
"last_name": "Marley",
"suffix": "Sr."
},
"phone_number": {
"number": "7777777777",
"type": "HOME"
},
"address": {
"city": "Alexandria",
"state": "VA",
"street1": "222 Main St",
"street2": "Apt 8",
"zip": "22331",
"country": "USA"
},
"shipping_address": {
"city": "Alexandria",
"state": "VA",
"street1": "612 N St Asaph St",
"street2": "",
"zip": "22314",
"country": "USA"
},
"tax_id": {
"id_number": "155555555",
"id_type": "ITIN"
},
"business_info": {
"business_name": "Acme Co",
"business_ein": "987654321",
"business_address": {
"city": "Alexandria",
"state": "VA",
"street1": "123 Central Court",
"zip": "22331",
"country": "USA"
},
"business_structure": "NON_PROFIT_ORGANIZATION"
}
}

Response:

  "id": "423d2f77-697a-4f1e-8d7a-3b3362917d7c",
"created_dt": "2022-01-07T15:52:23.442264-05:00",
"updated_dt": "2022-01-07T15:52:23.442264-05:00",
"type": "BUSINESS",
"program_id": "f8621cf6-7019-44ea-9b79-a2f513caf71e",
"email": "jsmith@gmail.com",
"name":
{
"prefix": "Mr.",
"first_name": "Bob",
"middle_name": "Peter",
"last_name": "Marley",
"suffix": "Sr."
},
"dob": "1980-01-01",
"phone_number": {
"number": "7777777777",
"type": "HOME"
},
"address": {
"city": "Alexandria",
"state": "VA",
"street1": "222 Main St",
"street2": "Apt 8",
"zip": "22331",
"country": "USA"
},
"shipping_address": {
"city": "Alexandria",
"state": "VA",
"street1": "612 N St Asaph St",
"street2": "",
"zip": "22314",
"country": "USA"
},
"tax_id": {
"has_tax_id": true,
"id_type": "ITIN"
},
"status": "APPROVED",
"business_info": {
"business_name": "Acme Co",
"has_business_ein": true,
"business_address": {
"city": "Alexandria",
"state": "VA",
"street1": "123 Central Court",
"zip": "22331",
"country": "USA"
},
"business_structure": "NON_PROFIT_ORGANIZATION"
}
}

Using Time-based One-time Password (TOTP)

Certain endpoints require the use of a time-based one-time password (TOTP) as an additional authentication method. Unique numeric passwords are generated following an open standard algorithm.

The algorithm uses a shared secret key to generate and validate the token. The secret key should only be accessible by your profile users and only transmitted over HTTPS.

info

This feature is still a work-in-progress. Please discuss timelines and deliverables with your program manager.

Generate TOTP secret

Generates a new TOTP secret and outputs a URL that can be used to generate a QR code suitable for 2FA apps like Twilio Authy and Google Authenticator. A profile can have only one generated TOTP secret.

POST /profiles/:profile_id/totp

Response:

{
"url": "otpauth://totp/Figure:{{id}}?secret={{secret_key}}&issuer=Figure&period=30&digits=6&algorithm=SHA1"
}
info

This URL cannot be retrieved later on.

Remove TOTP secret

Removes the TOTP secret from the provided profile. After deletion, there will no longer be a TOTP associated with that profile. A successful deletion will result in no response.

DELETE /profiles/:profile_id/totp
info

A profile can re-generate a new TOTP if needed.