Types

`CredentialRequest`

Full Definition

note

We recommend looking at the partial definitions below under the integration type tabs (Hosted, Semi-Hosted, and Non-Hosted) because they show only the properties relevant to the integration type you choose. The full definition here shows all possible properties, but some may not be relevant to your integration type.

CredentialRequest Type
{
    type: string,
    mandatory?: "yes" | "no" | "if_available",
    children?: CredentialRequest[],
    description?: string,
    allowUserInput?: boolean,
    multi?: boolean
}

Property	Required?	Type	Format	Default	Description	Example
`type`	required	`enum` Most common values: `"PhoneCredential"` `"EmailCredential"` `"FullNameCredential"` `"FirstNameCredential"` `"MiddleNameCredential"` `"LastNameCredential"` `"BirthDateCredential"` `"AddressCredential"` `"Line1Credential"` `"Line2Credential"` `"CityCredential"` `"StateCredential"` `"ZipCodeCredential"` `"CountryCredential"` `"SsnCredential"`	`PascalCase`	none	The type of user data a credential has	`"FirstNameCredential"`
`mandatory`	optional	`enum`	`snake_case`	`"no"`	Whether the credential is required, not required, or required if available (accepted values `"yes"`, `"no"`, and `"if_available"`)	`"if_available"`
`children`	optional	`CredentialRequest[]`	See `CredentialRequest`	none	List of child `CredentialRequest`s relative to the parent `CredentialRequest`	Child `CredentialRequest`s with `type`s `"FirstNameCredential"` and `"LastNameCredential"` relative to a parent `CredentialRequest` with type `"FullNameCredential"`
`description`	optional	`string`	`Sentence case`	none	Text shown to the user on the form field corresponding to the credential	`"We are required by federal regulation to collect your SSN"`
`allowUserInput`	optional	`boolean`	`boolean`	`true`	Whether to allow user input on the form field corresponding to the credential	`false`
`multi`	optional	`boolean`	`boolean`	`false`	Whether the credential should contain multiple values if available	`true`

Hosted
Semi-Hosted
Non-Hosted

note

With the Hosted tab active above, your brand's integration type setting should be set to Hosted in the Dashboard. See Determine integration type if you need help deciding which type is right for you.

CredentialRequest Type (Hosted Integration Type)
{
    type: string,
    mandatory?: "yes" | "no" | "if_available",
    children?: CredentialRequest[],
    description?: string,
    allowUserInput?: boolean
}

Property	Required?	Type	Format	Default	Description	Example
`type`	required	`enum` Most common values: `"PhoneCredential"` `"EmailCredential"` `"FullNameCredential"` `"FirstNameCredential"` `"MiddleNameCredential"` `"LastNameCredential"` `"BirthDateCredential"` `"AddressCredential"` `"Line1Credential"` `"Line2Credential"` `"CityCredential"` `"StateCredential"` `"ZipCodeCredential"` `"CountryCredential"` `"SsnCredential"`	`PascalCase`	none	The type of user data a credential has	`"FirstNameCredential"`
`mandatory`	optional	`enum`	`snake_case`	`"no"`	Whether the credential is required, not required, or required if available (accepted values `"yes"`, `"no"`, and `"if_available"`)	`"if_available"`
`children`	optional	`CredentialRequest[]`	See `CredentialRequest`	none	List of child `CredentialRequest`s relative to the parent `CredentialRequest`	Child `CredentialRequest`s with `type`s `"FirstNameCredential"` and `"LastNameCredential"` relative to a parent `CredentialRequest` with type `"FullNameCredential"`
`description`	optional	`string`	`Sentence case`	none	Text shown to the user on the form field corresponding to the credential	`"We are required by federal regulation to collect your SSN"`
`allowUserInput`	optional	`boolean`	`boolean`	`true`	Whether to allow user input on the form field corresponding to the credential	`false`

note

With the Semi-Hosted tab active above, your brand's integration type setting should be set to Semi-Hosted in the Dashboard. See Determine integration type if you need help deciding which type is right for you.

CredentialRequest Type (Semi-Hosted Integration Type)
{
    type: string,
    mandatory?: "yes" | "no" | "if_available",
    children?: CredentialRequest[],
    multi?: boolean
}

Property	Required?	Type	Format	Default	Description	Example
`type`	required	`enum` Most common values: `"PhoneCredential"` `"EmailCredential"` `"FullNameCredential"` `"FirstNameCredential"` `"MiddleNameCredential"` `"LastNameCredential"` `"BirthDateCredential"` `"AddressCredential"` `"Line1Credential"` `"Line2Credential"` `"CityCredential"` `"StateCredential"` `"ZipCodeCredential"` `"CountryCredential"` `"SsnCredential"`	`PascalCase`	none	The type of user data a credential has	`"FirstNameCredential"`
`mandatory`	optional	`enum`	`snake_case`	`"no"`	Whether the credential is required, not required, or required if available (accepted values `"yes"`, `"no"`, and `"if_available"`)	`"if_available"`
`children`	optional	`CredentialRequest[]`	See `CredentialRequest`	none	List of child `CredentialRequest`s relative to the parent `CredentialRequest`	Child `CredentialRequest`s with `type`s `"FirstNameCredential"` and `"LastNameCredential"` relative to a parent `CredentialRequest` with type `"FullNameCredential"`
`multi`	optional	`boolean`	`boolean`	`false`	Whether the credential should contain multiple values if available	`true`

note

With the Non-Hosted tab active above, your brand's integration type setting should be set to Non-Hosted in the Dashboard. See Determine integration type if you need help deciding which type is right for you.

CredentialRequest Type (Non-Hosted Integration Type)
{
    type: string,
    mandatory?: "yes" | "no" | "if_available",
    children?: CredentialRequest[],
    multi?: boolean
}

Property	Required?	Type	Format	Default	Description	Example
`type`	required	`enum` Most common values: `"PhoneCredential"` `"EmailCredential"` `"FullNameCredential"` `"FirstNameCredential"` `"MiddleNameCredential"` `"LastNameCredential"` `"BirthDateCredential"` `"AddressCredential"` `"Line1Credential"` `"Line2Credential"` `"CityCredential"` `"StateCredential"` `"ZipCodeCredential"` `"CountryCredential"` `"SsnCredential"`	`PascalCase`	none	The type of user data a credential has	`"FirstNameCredential"`
`mandatory`	optional	`enum`	`snake_case`	`"no"`	Whether the credential is required, not required, or required if available (accepted values `"yes"`, `"no"`, and `"if_available"`)	`"if_available"`
`children`	optional	`CredentialRequest[]`	See `CredentialRequest`	none	List of child `CredentialRequest`s relative to the parent `CredentialRequest`	Child `CredentialRequest`s with `type`s `"FirstNameCredential"` and `"LastNameCredential"` relative to a parent `CredentialRequest` with type `"FullNameCredential"`
`multi`	optional	`boolean`	`boolean`	`false`	Whether the credential should contain multiple values if available	`true`

Example

Hosted
Semi-Hosted
Non-Hosted

note

CredentialRequest Example (Hosted Integration Type)
{
    "type": "AddressCredential",
    "children": [
        {
            "type": "Line1Credential",
            "mandatory": "if_available",
            "allowUserInput": false
        },
        {
            "type": "Line2Credential",
            "mandatory": "no",
            "description": "Apt/Unit #"
            "allowUserInput": true
        },
        {
            "type": "CityCredential",
            "mandatory": "if_available",
            "allowUserInput": false
        },
        {
            "type": "StateCredential",
            "mandatory": "if_available",
            "allowUserInput": false
        },
        {
            "type": "ZipCodeCredential",
            "mandatory": "if_available",
            "allowUserInput": false
        },
        {
            "type": "CountryCredential",
            "mandatory": "if_available",
            "allowUserInput": false
        }
    ]
}

note

CredentialRequest Example (Semi-Hosted Integration Type)
{
    "type": "AddressCredential",
    "multi": true,
    "children": [
        {
            "type": "Line1Credential",
            "mandatory": "if_available"
        },
        {
            "type": "Line2Credential",
            "mandatory": "no"
        },
        {
            "type": "CityCredential",
            "mandatory": "if_available"
        },
        {
            "type": "StateCredential",
            "mandatory": "if_available"
        },
        {
            "type": "ZipCodeCredential",
            "mandatory": "if_available"
        },
        {
            "type": "CountryCredential",
            "mandatory": "if_available"
        }
    ]
}

note

CredentialRequest Example (Non-Hosted Integration Type)
{
    "type": "AddressCredential",
    "multi": true,
    "children": [
        {
            "type": "Line1Credential",
            "mandatory": "if_available"
        },
        {
            "type": "Line2Credential",
            "mandatory": "no"
        },
        {
            "type": "CityCredential",
            "mandatory": "if_available"
        },
        {
            "type": "StateCredential",
            "mandatory": "if_available"
        },
        {
            "type": "ZipCodeCredential",
            "mandatory": "if_available"
        },
        {
            "type": "CountryCredential",
            "mandatory": "if_available"
        }
    ]
}

`1ClickEntity`

1ClickEntity Type
{
    "identifiers": {
        [identifierKey: string]: string
    },
    "credentials": {
        [credentialKey: string]: string | [string] | Object | [Object]
    },
    "metadata": {
        "identifiers": {
            [identifierKey: string]: {
                [metadataKey: string]: string
            }
        },
        "credentials": {
            [credentialKey: string]: {
                [metadataKey: string]: string | [string] | Object | [Object]
            }
        }
    }
}

Property	Type	Format	Description	Example
`identifiers`	`Object`	See above	User identifiers, keyed on `identifierKey`	See Example `1ClickEntity`
`identifierKey`	`enum` Possible values (see identifiers for details): `phone` `email`	`camelCase`	The type of identifier	`"phone"`
`credentials`	`Object`	See above	User credentials, keyed on `credentialKey`	See Example `1ClickEntity`
`credentialKey`	`enum` Possible values (see credentials for details): `phone` `email` `fullName.firstName` `fullName.middleName` `fullName.lastName` `address.line1` `address.line2` `address.city` `address.state` `address.zipCode` `address.country` `birthDate` `ssn`	`camelCase`	The type of user data a credential has	`"firstName"`
`metadata`	`Object`	See above	Metadata, keyed on `metadataKey`	See Example `1ClickEntity`
`metadataKey`	`enum` Possible values: `id` `verificationMethod` `status` `issuanceDate` `expirationDate`	`camelCase`	Any additional data that's not a user's identity data (identifiers or credentials)	`"verificationMethod"`

The data keyed on a credentialKey will be one or more credential values. This data will have a type that depends on children and multi in the credential request:

Based on children:

If the credential request has children, each credential value will have type Object.

Example: Credential Value of Type Object

If the credential request has children:

CredentialRequest with children
{
    "type": "AddressCredential",
    "children": [
        {
            "type": "Line1Credential"
        },
        {
            "type": "Line2Credential"
        },
        {
            "type": "CityCredential"
        },
        {
            "type": "StateCredential"
        },
        {
            "type": "ZipCodeCredential"
        },
        {
            "type": "CountryCredential"
        }
    ]
}

Then, the credential returned will have type Object (and so will the corresponding metadata):

1ClickEntity for CredentialRequest with children
{
    ...
    "credentials": {
        "address": {
            "line1": "5320 Newell Rd",
            "city": "Palo Alto",
            "state": "CA",
            "zip": "94303",
            "country": "US"
        }
    },
    "metadata": {
        ...
        "credentials": {
            "id": {
                "address": {
                    "line1": "f5a4dc93-bc06-4bb8-bd05-17b5ba912bcd",
                    "city": "efd3820f-676a-4db1-b63e-695b66ed8ba0",
                    "state": "b65022a2-2016-41df-88f3-252e8e3a29c5",
                    "zip": "b747ff84-39d8-4df9-98f9-24a465f1a9ae",
                    "country": "d57a7bca-2a7c-4671-86ad-5647731cad02"
                },
            },
            ...
        }
    }
}

If the credential request does not have children, each credential value will have type string.

Example: Credential Value of Type string

If the credential request does not have children:

CredentialRequest without children
{
    "type": "EmailCredential",
}

Then, the credential returned will have type string (and so will the corresponding metadata):

1ClickEntity for CredentialRequest without children
{
    ...
    "credentials": {
        "email": "richard@piedpiper.net"
    },
    "metadata": {
        ...
        "credentials": {
            "id": {
                "email": "8a1d4e35-413d-496b-b499-8810b55cfb5c"
            },
            ...
        }
    }
}

Based on multi:

If the credential request has multi set to true, the data keyed on credentialKey will be an array of credential values.

Example: Array of Credential Values

If the credential request has multi set to true:

CredentialRequest with multi true, with children
{
    "type": "AddressCredential",
    "children": [
        {
            "type": "Line1Credential"
        },
        {
            "type": "Line2Credential"
        },
        {
            "type": "CityCredential"
        },
        {
            "type": "StateCredential"
        },
        {
            "type": "ZipCodeCredential"
        },
        {
            "type": "CountryCredential"
        }
    ],
    "multi": true
}

CredentialRequest with multi true, without children
{
    "type": "EmailCredential",
    "multi": true
}

Then, the data returned will be an array of credential values, so it will have type [Object] or [string] (and so will the corresponding metadata):

1ClickEntity for CredentialRequest with multi true, with children
{
    ...
    "credentials": {
        "address": [
            {
                "line1": "5320 Newell Rd",
                "city": "Palo Alto",
                "state": "CA",
                "zip": "94303",
                "country": "US"
            },
            {
                "line1": "9536 Meadow Dr",
                "line2": "Apt 301",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94112",
                "country": "US"
            },
            ...
        ],
    },
    "metadata": {
        ...
        "credentials": {
            "id": {
                "address": [
                    {
                        "line1": "f5a4dc93-bc06-4bb8-bd05-17b5ba912bcd",
                        "city": "efd3820f-676a-4db1-b63e-695b66ed8ba0",
                        "state": "b65022a2-2016-41df-88f3-252e8e3a29c5",
                        "zip": "b747ff84-39d8-4df9-98f9-24a465f1a9ae",
                        "country": "d57a7bca-2a7c-4671-86ad-5647731cad02"
                    },
                    {
                        "line1": "6c7350bd-ea84-485b-baa8-fba3381cc859",
                        "line2": "5311e2c8-67a1-4fe4-8ddb-88dc8a900915",
                        "city": "c315d4ed-34c6-41a9-b7ca-c17cb4bac927",
                        "state": "e3774b5f-0996-4dc7-a9b3-8ad24c9a286c",
                        "zip": "abc2e42c-2864-4bf6-b262-05cb51416957",
                        "country": "fca7d486-c99b-436e-9a92-95e221e4ba5d"
                    },
                    ...
                ],
            },
            ...
        }
    }
}

1ClickEntity for CredentialRequest with multi true, without children
{
    ...
    "credentials": {
        "email": [
            "richard@piedpiper.net",
            "richard@hooli.com",
            ...
        ],
    },
    "metadata": {
        ...
        "credentials": {
            "id": {
                "email": [
                    "8a1d4e35-413d-496b-b499-8810b55cfb5c",
                    "b82e39cf-3bb6-4105-b9c1-bfd1ed2a4dbc",
                    ...
                ]
            },
            ...
        }
    }
}

Arrays May Be Single Valued

An array of credential values may only include one value. If multi is set to true in a credential request, we'll return multiple values if we can source them. But if we can only source a single value, we'll still return it in an array, to ensure the data type is predictable.

If the credential request has multi set to false, the data keyed on credentialKey will be a single credential value.

Example: Single Credential Value

If the credential request has multi set to false:

CredentialRequest with multi false, with children
{
    "type": "AddressCredential",
    "children": [
        {
            "type": "Line1Credential"
        },
        {
            "type": "Line2Credential"
        },
        {
            "type": "CityCredential"
        },
        {
            "type": "StateCredential"
        },
        {
            "type": "ZipCodeCredential"
        },
        {
            "type": "CountryCredential"
        }
    ],
    "multi": false
}

CredentialRequest with multi false, without children
{
    "type": "EmailCredential",
    "multi": false
}

Then, the data returned will be a single credential value, so it will have type Object or string (and so will the corresponding metadata):

1ClickEntity for CredentialRequest with multi false, with children
{
    ...
    "credentials": {
        "address": {
            "line1": "5320 Newell Rd",
            "city": "Palo Alto",
            "state": "CA",
            "zip": "94303",
            "country": "US"
        }
    },
    "metadata": {
        ...
        "credentials": {
            "id": {
                "address": {
                    "line1": "f5a4dc93-bc06-4bb8-bd05-17b5ba912bcd",
                    "city": "efd3820f-676a-4db1-b63e-695b66ed8ba0",
                    "state": "b65022a2-2016-41df-88f3-252e8e3a29c5",
                    "zip": "b747ff84-39d8-4df9-98f9-24a465f1a9ae",
                    "country": "d57a7bca-2a7c-4671-86ad-5647731cad02"
                }
            },
            ...
        }
    }
}

1ClickEntity for CredentialRequest with multi false, without children
{
    ...
    "credentials": {
        "email": "richard@piedpiper.net"
    },
    "metadata": {
        ...
        "credentials": {
            "id": {
                "email": "8a1d4e35-413d-496b-b499-8810b55cfb5c"
            },
            ...
        }
    }
}

Example

1ClickEntity Example
{
    "identifiers": {
        "phone": "+10123456789"
    },
    "credentials": {
        // Multiple emails because `multi` was set to `true` in the email credential request
        "email": [
            "richard@piedpiper.net",
            "richard@hooli.com"
        ],
        "fullName": {
            "firstName": "Richard",
            "lastName": "Hendricks"
        },
        // Multiple addresses because `multi` was set to `true` in the address credential request
        "address": [
            {
                "line1": "5320 Newell Rd",
                "city": "Palo Alto",
                "state": "CA",
                "zip": "94303",
                "country": "US"
            },
            {
                "line1": "9536 Meadow Dr",
                "line2": "Apt 301",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94112",
                "country": "US"
            },
            {
                "line1": "7292 Hanover St",
                "city": "San Jose",
                "state": "CA",
                "zip": "95122",
                "country": "US"
            }
        ],
        "birthDate": "1989-08-01",
        "ssn": "123456789"
    },
    "metadata": {
        "identifiers": {
            "verificationMethod": {
                "phone": "otp"
            }
        },
        "credentials": {
            "id": {
                "email": [
                    "8a1d4e35-413d-496b-b499-8810b55cfb5c",
                    "b82e39cf-3bb6-4105-b9c1-bfd1ed2a4dbc"
                ]
                "fullName": {
                    "firstName": "2e6a7b9a-e93e-43ba-98a9-c554f4e16457",
                    "lastName": "9a5817ef-e621-4277-8c48-c8ee3776b6c4"
                },
                "address": [
                    {
                        "line1": "f5a4dc93-bc06-4bb8-bd05-17b5ba912bcd",
                        "city": "efd3820f-676a-4db1-b63e-695b66ed8ba0",
                        "state": "b65022a2-2016-41df-88f3-252e8e3a29c5",
                        "zip": "b747ff84-39d8-4df9-98f9-24a465f1a9ae",
                        "country": "d57a7bca-2a7c-4671-86ad-5647731cad02"
                    },
                    {
                        "line1": "6c7350bd-ea84-485b-baa8-fba3381cc859",
                        "line2": "5311e2c8-67a1-4fe4-8ddb-88dc8a900915",
                        "city": "c315d4ed-34c6-41a9-b7ca-c17cb4bac927",
                        "state": "e3774b5f-0996-4dc7-a9b3-8ad24c9a286c",
                        "zip": "abc2e42c-2864-4bf6-b262-05cb51416957",
                        "country": "fca7d486-c99b-436e-9a92-95e221e4ba5d"
                    },
                    {
                        "line1": "afdaca85-4abe-4c0d-910d-7f48261bcbe0",
                        "city": "cf17d0d8-08f3-4205-82a9-812a0be747da",
                        "state": "b1480256-bd81-4ed5-a748-62890304a2e3",
                        "zip": "62d14d62-bd4e-4175-8a0d-01f21a22d833",
                        "country": "baff8fea-34cd-451c-9324-ca0cf1582dd7"
                    }
                ],
                "birthDate": "ec1ef0ce-eeed-46a4-94a9-29b46e64403d",
                "ssn": "ec1ef0ce-eeed-46a4-94a9-29b46e64403d"
            },
            "verificationMethod": {
                "email": [
                    "self_attested",
                    "credit_bureau"
                ]
                "fullName": {
                    "firstName": "phone_carrier",
                    "lastName": "phone_carrier"
                },
                "address": [
                    {
                        "line1": "credit_bureau",
                        "city": "credit_bureau",
                        "state": "credit_bureau",
                        "zip": "credit_bureau",
                        "country": "credit_bureau"
                    },
                    {
                        "line1": "credit_bureau",
                        "line2": "credit_bureau",
                        "city": "credit_bureau",
                        "state": "credit_bureau",
                        "zip": "credit_bureau",
                        "country": "credit_bureau"
                    },
                    {
                        "line1": "phone_carrier",
                        "city": "phone_carrier",
                        "state": "phone_carrier",
                        "zip": "phone_carrier",
                        "country": "phone_carrier"
                    }
                ],
                "birthDate": "phone_carrier",
                "ssn": "phone_carrier"
            },
            "status": {
                "email": [
                    "valid",
                    "valid"
                ],
                "fullName": {
                    "firstName": "valid",
                    "lastName": "valid"
                },
                "address": [
                    {
                        "line1": "valid",
                        "city": "valid",
                        "state": "valid",
                        "zip": "valid",
                        "country": "valid"
                    },
                    {
                        "line1": "valid",
                        "line2": "valid",
                        "city": "valid",
                        "state": "valid",
                        "zip": "valid",
                        "country": "valid"
                    },
                    {
                        "line1": "valid",
                        "city": "valid",
                        "state": "valid",
                        "zip": "valid",
                        "country": "valid"
                    }
                ],
                "birthDate": "valid",
                "ssn": "valid"
            },
            "expirationDate": {
                "email": [
                    "1871839024044",
                    "1885082680000"
                ],
                "fullName": {
                    "firstName": "1871839024044",
                    "lastName": "1871839024044"
                },
                "address": [
                    {
                        "line1": "1871839024044",
                        "city": "1871839024044",
                        "state": "1871839024044",
                        "zip": "1871839024044",
                        "country": "1871839024044"
                    },
                    {
                        "line1": "1871839024044",
                        "line1": "1871839024044",
                        "city": "1871839024044",
                        "state": "1871839024044",
                        "zip": "1871839024044",
                        "country": "1871839024044"
                    },
                    {
                        "line1": "1875924280000",
                        "city": "1875924280000",
                        "state": "1875924280000",
                        "zip": "1875924280000",
                        "country": "1875924280000"
                    },
                ],
                "birthDate": null,
                "ssn": null
            }
        }
    }
}

`Error`

Error Type
{
    "name": string,
    "message": string,
    "code": number,
    "className": string,
    "data": {
        "errorCode": string
    }
}

Property	Type	Format	Description	Example
`name`	`string`	`PascalCase`	Name of the error	`"BadRequest"`
`message`	`string`	`Sentence case`	Message for developer that explains the error	`"Additional information is required to source data for user: birthDate"`
`code`	`number`	3 digits (0-9)	HTTP response status code	`400`
`className`	`string`	`kebab-case`	Class of error	`bad-request`
`data.errorCode`	`enum` Possible values (see Error Codes for details): `"ERR001"` `"OCE001"` `"OCE002"` `"OCE003"` `"OCE004"` `"OCE005"` `"OCE006"` `"OCE007"` `"OCE008"` `"OCE009"` `"OCE0010"` `"OCE0011"` `"OCE0012"` `"OCE0013"` `"OCE0014"` `"OCE0015"`	3 letters and 3 digits (0-9)	Verified error code	Verified specific error code (see Error Codes)	`"OCE011"`

Example

Error Example
{
    "name": "BadRequest",
    "message": "Additional information is required to source data for user: birthDate"
    "code": 400,
    "className": "bad-request",
    "data": {
        "errorCode": "OCE011"
    }
}

CredentialRequest​

Example​

1ClickEntity​

Example​

Error​

Example​

`CredentialRequest`

Example

`1ClickEntity`

Example

`Error`

Example