Types

`1ClickEntity`

1ClickEntity Type
{
    "identifiers": {
        [identifierKey: string]: string
    },
    "credentials": {
        [credentialKey: string]: 
            string     // Single string value when `multi` is false and `children` isn't included in the credential requests
            | [string] // Array of string values when `multi` is true and `children` isn't included in the credential requests
            | Object   // Single object value when `multi` is false and `children` is included in the credential requests
            | [Object] // Array of object values when `multi` is true and `children` is included in the credential requests
    },
    "metadata": {
        "identifiers": {
            [identifierKey: string]: {
                [metadataKey: string]: string
            }
        },
        "credentials": {
            [credentialKey: string]: {
                // Follows the same structure as `credentials` and maintains the same order for array items when `multi` is set to `true`
                [metadataKey: string]: 
                string     // Single string value when `multi` is false and `children` isn't included in the credential requests
                | [string] // Array of string values when `multi` is true and `children` isn't included in the credential requests
                | Object   // Single object value when `multi` is false and `children` is included in the credential requests
                | [Object] // Array of object values when `multi` is true and `children` is included in the credential requests
            }
        }
    }
}

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",
            "zipCode": "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",
                    "zipCode": "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",
                "zipCode": "94303",
                "country": "US"
            },
            {
                "line1": "9536 Meadow Dr",
                "line2": "Apt 301",
                "city": "San Francisco",
                "state": "CA",
                "zipCode": "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",
                        "zipCode": "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",
                        "zipCode": "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 (up to a maximum of 3). But if we can only source a single value, we'll still return it in an array, to ensure the data type is predictable.

Multi Does Not Apply to Child Credential Requests

The multi option does not work on children credential requests. It only applies to the parent credential request.

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",
            "zipCode": "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",
                    "zipCode": "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": "+12125550010"
    },
    "credentials": {
        "fullName": {
            "firstName": "Richard",
            "lastName": "Hendricks"
        },
        // Array because `multi` was set to `true` in the address credential request
        "address": [
            {
                "line1": "5320 Newell Rd",
                "city": "Palo Alto",
                "state": "CA",
                "zipCode": "94303",
                "country": "US"
            }
        ],
        "birthDate": "1989-08-01",
        "ssn": "000456789"
    },
    "metadata": {
        "identifiers": {
            "verificationMethod": {
                "phone": "otp"
            },
            "riskSignals": {
                "overall": {
                    "score": 0, // included in Basic
                    "level": "low", // included in Basic
                    "recommendation": "allow", // included in Basic
                    "reasonCodes": [ // included in Advanced
                        "OCR10021"
                    ]
                },
                "phone": { // included in Advanced
                    "carrier": {
                        "id": 0,
                        "name": "Example Carrier"
                    }
                    "reasonCodes": [
                        "OCR20004",
                        "OCR20005",
                        "OCR20007",
                        "OCR20101"
                    ]
                },
                "email": { // included in Advanced
                    "reasonCodes": [
                        "OCR60001",
                        "OCR60002"
                    ]
                }
            }
        },
        // Follows the same structure as `credentials` and maintains the same order for array items when `multi` is set to `true`
        "credentials": {
            "verificationMethod": {
                "fullName": {
                    "firstName": "phone_carrier",
                    "lastName": "phone_carrier"
                },
                // Array because `multi` was set to `true` in the address credential request
                "address": [
                    {
                        "line1": "credit_bureau",
                        "city": "credit_bureau",
                        "state": "credit_bureau",
                        "zipCode": "credit_bureau",
                        "country": "credit_bureau"
                    }
                ],
                "birthDate": "phone_carrier",
                "ssn": "phone_carrier"
            }
        }
    }
}

`RiskSignals`

See Risk Signals on the Data page for details about the attributes and when they're included.

tip

You can configure which risk signals you receive using the risk signals brand setting:

Option	Description
Basic	Include only high level risk signals (Overall Score, Level, and Recommendation).
Advanced Extra	Include all risk signals (Reason Codes, carrier data, and more).
Off Not Recommended	Include no risk signals.

If Basic or Advanced risk signals are enabled, we will block users with an Overall Score greater than 600 and return a OCE017 error.

RiskSignals Type
{
    "overall": {
        "score": integer, // included with Basic (default) and Advanced
        "level": "low" | "medium-low" | "medium" | "medium-high" | "high", // included with Basic (default) and Advanced
        "recommendation": "allow" | "flag" | "block", // included with Basic (default) and Advanced
        "reasonCodes": [string] // included with Advanced
    },
    "phone": { // included with Advanced
        "carrier": {
            "id": integer,
            "name": string
        }
        "reasonCodes": [string]
    },
    "email": { // included with Advanced
        "reasonCodes": [string]
    }
}

When enabled, the risk signals appear in identifiers metadata in a 1ClickEntity and in an error for the OCE017 error code:

1ClickEntity
{
    ...
    "metadata": {
        "identifiers": {
            "riskSignals": RiskSignals,
            ...
        },
        ...
    }
}

OCE017 Error
{
    "name": "BadRequest",
    "message": "1-Click Blocked: Risk Score Too High",
    "code": 400,
    "className": "bad-request",
    "data": {
        "errorCode": "OCE017",
        "riskSignals": RiskSignals
    }
}

Example

RiskSignals Example
{
    ...
    "metadata": {
        "identifiers": {
            ...
            "riskSignals": {
                "overall": {
                    "score": 0, // included with Basic (default) and Advanced
                    "level": "low", // included with Basic (default) and Advanced
                    "recommendation": "allow", // included with Basic (default) and Advanced
                    "reasonCodes": [ // included with Advanced
                        "OCR10021"
                    ]
                },
                "phone": { // included with Advanced
                    "carrier": {
                        "id": 0,
                        "name": "Example Carrier"
                    }
                    "reasonCodes": [
                        "OCR20004",
                        "OCR20005",
                        "OCR20007",
                        "OCR20101"
                    ]
                },
                "email": { // included with Advanced
                    "reasonCodes": [
                        "OCR60001",
                        "OCR60002"
                    ]
                }
            }
        },
        ...
    }
}

`Error`

Error Type
{
    "name": string,
    "message": string,
    "code": number,
    "className": string,
    "data": {
        "errorCode": string,
        "additionalInputs": [string], // only for error code OCE011
        "inputAttemptsExceeded": [string], // only for error code OCE019
        "riskSignals": RiskSignals // only for error codes OCE011, OCE012, OCE013, OCE017, and OCE019
    }
}

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` See Error Codes for possible values	3 letters and 3 digits (0-9)	Verified error code	`"OCE011"`
`data.additionalInputs`	`[string]`	`camelCase`	Additional inputs to source credentials for user, where multiple values indicates inclusive OR (only included for `OCE011`)	`["birthDate", "ssn4"]`
`data.inputAttemptsExceeded`	`[string]`	`camelCase`	Input(s) for which the attempts limit (3 for each input) has been exceeded (only included for `OCE019`)	`["birthDate", "ssn4"]`
`data.riskSignals`	`RiskSignals`	`Object`	Verified risk signals associated with the 1-Click Signup event (only included for `OCE011`, `OCE012`, `OCE013`, `OCE017`, and `OCE019`)	See `RiskSignals` example

Example

Error Example
{
    "name": "BadRequest",
    "message": "1-Click Blocked: Risk Score Too High",
    "code": 400,
    "className": "bad-request",
    "data": {
        "errorCode": "OCE017",
        "riskSignals": {
            "overall": {
                "score": 1000, // always enabled
                "level": "high", // always enabled
                "recommendation": "block", // always enabled
                "reasonCodes": [ // add on (ask Verified support to enable)
                    "OCR10032"
                ]
            },
            "phone": { // add on (ask Verified support to enable)
                "carrier": {
                    "id": 1,
                    "name": "Risky Carrier"
                }
                "reasonCodes": [
                    "OCR20009",
                    "OCR20107",
                    "OCR21012",
                    "OCR21003"
                ]
            },
            "email": { // add on (ask Verified support to enable)
                "reasonCodes": [
                    "OCR60006",
                    "OCR60006"
                ]
            }
        }
    }
}

`CredentialRequest`

CredentialRequest 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

CredentialRequest
{
    "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​

Example​

RiskSignals​

Example​

Error​

Example​

CredentialRequest​

Example​

`1ClickEntity`

Example

`RiskSignals`

Example

`Error`

Example

`CredentialRequest`

Example