Onboarding Consents

To facilitate the onboarding of profiles and accounts, programs can configure consent requirements for user-facing signup workflows. Consent requirements can be things like a terms of service page, a privacy policy document, or a user agreement requiring an e-signature.

A program's consent requirements are called consent definitions in the Banking API.

Creating Definitions

Creating and managing consent definitions is done through the CSP Portal and is not exposed as a public API. Programs should work closely with their program managers to ensure the definitions are created correctly and work as expected.

Generally, to define a consent definition a program will need to provide:

Field	Description
Code	A string identifier that groups different versions of the same consent definition.
Entity Type	What entity this consent definition applies to (Profile or Account) and whether it is for business or personal entities.
Displayable Name	The human readable name of the definition displayed to the user.

Additional fields will be required depending on the type of consent definition being created.

Definition Types

Type	Description	Additional Fields
URL	A link to a web page containing the consent materials.	The URL
DOCUMENT	A static consent document file like a PDF or Word Document.	The document file
TEMPLATE	A DOCX file that supports dynamic information and e-signature functionality. This file needs to be formatted in a specific way so programs should consult their program manager on any `TEMPLATE` consents.	The document file, the list of the template fields

Template Fields

The list of supported injectable fields for a TEMPLATE definition.

Field	Description
PROFILE_FIRST_NAME	The first name on the profile.
PROFILE_LAST_NAME	The last name on the profile.
PROFILE_EMAIL	The email address on the profile.
PROFILE_ADDRESS_STREET_1	Line 1 of the profile street address.
PROFILE_ADDRESS_STREET_2	Line 2 of the profile street address.
PROFILE_ADDRESS_STREET_FULL	The full street address of the profile.
PROFILE_ADDRESS_CITY	The city of the profile address.
PROFILE_ADDRESS_STATE	The state of the profile address.
PROFILE_ADDRESS_ZIP	The zip code of the profile address.
PROFILE_ADDRESS_COUNTRY	The country of the profile address.
PROFILE_BUSINESS_NAME	The business name on the profile for business types.
PROFILE_BUSINESS_TAX_ID	The tax identifier listed on the profile for business types.
PROFILE_BUSINESS_ADDRESS_STREET_1	Line 1 of the business specific profile street address.
PROFILE_BUSINESS_ADDRESS_STREET_2	Line 2 of the business specific profile street address.
PROFILE_BUSINESS_ADDRESS_STREET_FULL	The full street address of the business specific profile.
PROFILE_BUSINESS_ADDRESS_CITY	The city of the business specific profile address.
PROFILE_BUSINESS_ADDRESS_STATE	The state of the business specific profile address.
PROFILE_BUSINESS_ADDRESS_ZIP	The zip code of the business specific profile address.
PROGRAM_NAME	The name of the Program.
PROGRAM_CONTACT_EMAIL	The contact email address associated with the Program.
PROGRAM_CONTACT_PHONE	The contact phone number associated with the Program.
PROGRAM_CONTACT_WEBSITE	The website associated with the Program.
PROGRAM_CONTACT_ADDRESS_STREET_1	Line 1 of the Program contact address.
PROGRAM_CONTACT_ADDRESS_STREET_2	Line 2 of the Program contact address.
PROGRAM_CONTACT_ADDRESS_STREET_FULL	The full street address of the Program contact address.
PROGRAM_CONTACT_ADDRESS_CITY	The city of the Program contact address.
PROGRAM_CONTACT_ADDRESS_STATE	The state of the Program contact address.
PROGRAM_CONTACT_ADDRESS_COUNTRY	The country of the Program contact address.
PROGRAM_CONTACT_ADDRESS_ZIP	The zip code of the Program contact address.
CURRENT_DATE_TIME	The current date and time in PST timezone (ex. Sep 01, 2022 12:17 PM PT).
SIGNATURE_DATE_TIME	The current date time to be used as an e-signature timestamp. This will be omitted if the document is previewed by the user prior to consenting.
SIGNATURE_FULL_NAME	The profile full name formatted as a signature for e-signing. This will be omitted if the document is previewed by the user prior to consenting.

Consent Definitions are uniquely identified by a UUID id, but they are grouped by their code for versioning purposes. Querying definitions will return a map of existing definitions grouped by this code. Within a code group only one definition can be active at any given time.

GET /consent-definitions

{
    "data": {
        "FPBIIB": [
            {
                "id": "02d62046-733f-415e-81f0-f43ff52d7609",
                "code": "FPBIIB",
                "version": 1,
                "program_id": "51353e69-4f7f-44c8-bc1f-3237f2cfd8ba",
                "name": "Figure Pay Bio-metric Information and Identifiers",
                "entity_type": "BUSINESS_PROFILE",
                "type": "URL",
                "document_id": null,
                "document_template_id": null,
                "url": "https://www.figure.com/figurepay/biometric-policy/",
                "active": true,
                "created_dt": "2022-08-29T21:25:26.083279Z",
                "updated_dt": "2022-08-29T21:25:26.083279Z"
            }
        ],
        "DAGPP": [
            {
                "id": "c347570a-01ae-4d2a-926a-02a606c232c8",
                "code": "DAGPP",
                "version": 3,
                "program_id": "51353e69-4f7f-44c8-bc1f-3237f2cfd8ba",
                "name": "Deposit Agreement Template",
                "entity_type": "PERSONAL_PROFILE",
                "type": "TEMPLATE",
                "document_id": null,
                "document_template_id": "0d0c6d37-a5e8-4df6-b600-6772fc204717",
                "url": null,
                "active": true,
                "created_dt": "2022-08-31T16:30:21.757376Z",
                "updated_dt": "2022-08-31T16:30:21.757376Z"
            },
            {
                "id": "bf59fdc0-a9c1-429c-9c14-51f402ae4a8d",
                "code": "DAGPP",
                "version": 2,
                "program_id": "51353e69-4f7f-44c8-bc1f-3237f2cfd8ba",
                "name": "Deposit Account Agreement Template",
                "entity_type": "PERSONAL_PROFILE",
                "type": "TEMPLATE",
                "document_id": null,
                "document_template_id": "ed22de38-a744-4c5a-b88e-98a24d413066",
                "url": null,
                "active": false,
                "created_dt": "2022-08-31T15:11:36.925124Z",
                "updated_dt": "2022-08-31T15:11:36.925124Z"
            },
            {
                "id": "18f7ebb0-8359-4a96-898c-5e78eab2da20",
                "code": "DAGPP",
                "version": 1,
                "program_id": "51353e69-4f7f-44c8-bc1f-3237f2cfd8ba",
                "name": "Deposit Account Agreement Template",
                "entity_type": "PERSONAL_PROFILE",
                "type": "TEMPLATE",
                "document_id": null,
                "document_template_id": "50798d19-3ec2-41a9-b88c-3b3f5704dac4",
                "url": null,
                "active": false,
                "created_dt": "2022-08-30T17:41:04.820615Z",
                "updated_dt": "2022-08-30T17:41:04.820615Z"
            }
        ],
        "GLBAP": [
            {
                "id": "8254eaf3-50d4-424c-a44d-0d0eb5e35be0",
                "code": "GLBAP",
                "version": 2,
                "program_id": "51353e69-4f7f-44c8-bc1f-3237f2cfd8ba",
                "name": "GLBA Notice",
                "entity_type": "PERSONAL_PROFILE",
                "type": "DOCUMENT",
                "document_id": "0c9a92fd-bad1-4d17-b048-2839d3c093b4",
                "document_template_id": null,
                "url": null,
                "active": false,
                "created_dt": "2022-08-31T01:10:29.977906Z",
                "updated_dt": "2022-08-31T01:10:29.977906Z"
            },
            {
                "id": "26ccbce0-8931-4c42-af43-a95709cdf9ba",
                "code": "GLBAP",
                "version": 1,
                "program_id": "51353e69-4f7f-44c8-bc1f-3237f2cfd8ba",
                "name": "GLBA Notice",
                "entity_type": "PERSONAL_PROFILE",
                "type": "DOCUMENT",
                "document_id": "85844b8a-9aad-49dc-af5a-f56d03e8ba5f",
                "document_template_id": null,
                "url": null,
                "active": true,
                "created_dt": "2022-08-30T13:54:18.470889Z",
                "updated_dt": "2022-08-30T13:54:18.470889Z"
            }
        ]
    }
}

Query parameters allow definitions to be filtered by entity_type or code filters, or an active_only flag.

GET /consent-definitions?code=DAGPP&entity_type=PERSONAL_PROFILE&active_only=true

{
    "data": {
        "DAGPP": [
            {
                "id": "c347570a-01ae-4d2a-926a-02a606c232c8",
                "code": "DAGPP",
                "version": 3,
                "program_id": "51353e69-4f7f-44c8-bc1f-3237f2cfd8ba",
                "name": "Deposit Agreement Template",
                "entity_type": "PERSONAL_PROFILE",
                "type": "TEMPLATE",
                "document_id": null,
                "document_template_id": "0d0c6d37-a5e8-4df6-b600-6772fc204717",
                "url": null,
                "active": true,
                "created_dt": "2022-08-31T16:30:21.757376Z",
                "updated_dt": "2022-08-31T16:30:21.757376Z"
            }
        ]
    }
}

Consents API

When an entity (profile or account) is created, ONBOARDING consent records will be created for that entity based on the active Consent Definitions that exist for its entity type. These ONBOARDING consents can be queried and acknowledged via the Consents API.

Fetching Consents

Fetching the ONBOARDING consents for a profile can be done like so:

GET /profiles/:profile_id/consents?consent_type=ONBOARDING

{
    "consents": [
        {
            "id": "a86fb1f8-858e-4958-ae6c-0f25d0a7cebe",
            "consent_type": "ONBOARDING",
            "has_consented": false,
            "program_consent_definition_id": "02d62046-733f-415e-81f0-f43ff52d7609",
            "document_id": null,
            "created_dt": "2022-09-14T22:06:27.643241Z",
            "updated_dt": "2022-09-14T22:06:27.643246Z"
        },
        {
            "id": "aa88bcae-cf73-4a59-8d1f-cd8369238889",
            "consent_type": "ONBOARDING",
            "has_consented": false,
            "program_consent_definition_id": "c347570a-01ae-4d2a-926a-02a606c232c8,
            "document_id": null,
            "created_dt": "2022-09-14T22:06:27.607826Z",
            "updated_dt": "2022-09-14T22:06:27.60783Z"
        },
        {
            "id": "cca9fc1a-c422-4e93-a99b-7e128f187437",
            "consent_type": "ONBOARDING",
            "has_consented": false,
            "program_consent_definition_id": "26ccbce0-8931-4c42-af43-a95709cdf9ba",
            "document_id": null,
            "created_dt": "2022-09-14T22:06:27.662749Z",
            "updated_dt": "2022-09-14T22:06:27.662755Z"
        }
    ]
}

Account specific API calls will be similar in structure but under the account resource. See the Swagger Spec for a detailed list of the API for both accounts and profiles.

GET /profiles/:profile_id/accounts/:account_id/consents

{
    "consents": [
        {
            "id": "ef2c7a59-a8f3-4467-afb3-b23e1f024190",
            "consent_type": "ONBOARDING",
            "has_consented": false,
            "program_consent_definition_id": "0a4cf120-cc85-408c-b903-6d7f4ac6de51",
            "document_id": null,
            "created_dt": "2022-09-14T22:07:12.622241Z",
            "updated_dt": "2022-09-14T22:07:12.843249Z"
        }
    ]
}

Displaying Consents

During signup workflows, programs should present end users with the consent materials they are agreeing too. Depending on the type of consent definition that could mean linking the user to a separate web page, allowing them to view a document on their client device, or by generating a preview of a dynamic document they will be e-signing.

Programs should refer back to the consent definition's to find the metadata required for each definition type.

Type	Field	Usage
URL	url	The `url` should be displayed as a clickable hyperlink.
DOCUMENT	document_id	The `document_id` should be used to fetch the document file from the Documents API.
TEMPLATE	document_template_id	The `document_template_id` should be used to call the document template generate API for its corresponding entity.

Accepting Consents

When a user acknowledges and accepts a consent the corresponding consent record should be marked as has_consented=true.

Individual Update

PUT /profiles/:profile_id/consents/:consent_id

{
    "has_consented": true
}

PUT /profiles/:profile_id/accounts/:account_id/consents/:consent_id

{
    "has_consented": true
}

Batch Update

PUT /profiles/:profile_id/consents

{
    "has_consented": true,
    "ids": [
        "a86fb1f8-858e-4958-ae6c-0f25d0a7cebe",
        "aa88bcae-cf73-4a59-8d1f-cd8369238889",
        "cca9fc1a-c422-4e93-a99b-7e128f187437"
    ]
}

PUT /profiles/:profile_id/accounts/:account_id/consents

{
    "has_consented": true,
    "ids": [
        "ef2c7a59-a8f3-4467-afb3-b23e1f024190"
    ]
}

Retrieving Generated Documents

When a user accepts a TEMPLATE based consent, a PDF document will be created with its template fields injected into the original consent definition template file. This generated document will be accessible via the document_id on the entity consent record through the Documents API.

Entity Status Impact

Onboarding consents are integrated into the opening and approval process for accounts and profiles. Consents can be accepted at any time, but if other checks (KYC/AML, etc.) complete first, the entity will move to a CONSENT_REQUIRED status until all onboarding consents have been accepted.

Preconsent API

info

Preconsent API requires active consent definitions

The preconsent APIs can be used to consent in advance for a profile if you would like to gather all documents and have the user consent to them prior to creating a sub-profile resource such as accounts. The preconsent can be used later to link the consents to the newly created sub-profile resource.

You can create as many preconsents for a profile as you like. A sample use case would be when a user has signed their consent document but later updated their profile and therefore needed to have their consent documents updated. An example is shown below to delete an existing preconsent and creating a new one.

Each preconsent can only be used once to link the underlying consents to the sub-profile resource. The preconsent would no longer be available after being used.

Creating a Preconsent

POST /profiles/:profile_id/preconsents

{
    "id": "5cab23c2-0237-44b5-bd50-e8c5198a4b06",
    "type": "ACCOUNT"
}

Response:

{
    "id": "5cab23c2-0237-44b5-bd50-e8c5198a4b06",
    "profile_id": "fcee3f44-8cd1-458a-8426-6628efcef99f",
    "type": "ACCOUNT",
    "consents": [
        {
            "id": "006dc2be-4501-414a-ad6a-998632b0dd87",
            "consent_type": "ONBOARDING",
            "has_consented": false,
            "program_consent_definition_id": "22de85f5-8b23-4181-aec9-5969ca0d5f6e",
            "document_id": null,
            "created_dt": "2023-06-13T19:31:41.809721Z",
            "updated_dt": "2023-06-13T19:31:41.809727Z"
        }
    ]
}

Generating a Preconsent Document Preview

If your consent definitions has document templates, a sample can be generated for that profile.

GET /profiles/:profile_id/preconsents/:preconsent_id/document-templates/:document_template_id/generate

Response:

Binary stream of the document

Updating Preconsent

The underlying consents for the preconsent can be updated if the user has consented to them.

PUT /profiles/:profile_id/preconsents/:preconsent_id
{
    "consent_ids": [
        "006dc2be-4501-414a-ad6a-998632b0dd87"
    ],
    "has_consented": true
}

Response:

{
    "id": "5cab23c2-0237-44b5-bd50-e8c5198a4b06",
    "profile_id": "fcee3f44-8cd1-458a-8426-6628efcef99f",
    "type": "ACCOUNT",
    "consents": [
        {
            "id": "006dc2be-4501-414a-ad6a-998632b0dd87",
            "consent_type": "ONBOARDING",
            "has_consented": true,
            "program_consent_definition_id": "22de85f5-8b23-4181-aec9-5969ca0d5f6e",
            "document_id": null,
            "created_dt": "2023-06-13T19:31:41.809721Z",
            "updated_dt": "2023-06-13T19:31:41.809727Z"
        }
    ]
}

Creating a Sub-Profile Resource With Preconsent

info

Preconsent do not have to be consented to when it is used to create the sub-profile resource

You can now use the preconsent when creating the sub-profile resource. In the example below we'll be creating an account with the preconsent.

POST /profiles/:profile_id/accounts

{
    "id": "c38c23e0-b8b8-4aaa-9cce-a7a854ba431b",
    "name": "test",
    "preconsent_id": "5cab23c2-0237-44b5-bd50-e8c5198a4b06"
}

Deleting a Preconsent

Deleting a preconsent would remove the underlying consents and any consented generated documents derived from the consent definition template.

DELETE /profiles/:profile_id/preconsents/:preconsent_id

Response:

200 HTTP status code with no body

Onboarding Consents

Consent Definitions​

Creating Definitions​

Definition Types​

Template Fields​

Querying Consent Definitions​

Consents API​

Fetching Consents​

Displaying Consents​

Accepting Consents​

Individual Update​

Batch Update​

Retrieving Generated Documents​

Entity Status Impact​

Preconsent API​

Creating a Preconsent​

Generating a Preconsent Document Preview​

Updating Preconsent​

Creating a Sub-Profile Resource With Preconsent​

Deleting a Preconsent​

Consent Definitions

Creating Definitions

Definition Types

Template Fields

Querying Consent Definitions

Consents API

Fetching Consents

Displaying Consents

Accepting Consents

Individual Update

Batch Update

Retrieving Generated Documents

Entity Status Impact

Preconsent API

Creating a Preconsent

Generating a Preconsent Document Preview

Updating Preconsent

Creating a Sub-Profile Resource With Preconsent

Deleting a Preconsent