Skip to main content

API Reference

note

See also our Postman docs.

Authentication​

Every request detailed below requires an Verified Inc. API key as an Authorization header value.

Sandbox Testing

To test in our sandbox environment, you can use our test brand and user:

Test Brand API Credentials
Sandbox API Key
yVg3LEnF08y0MDmpHcPxB+sZWFcDARmPRKdY2M906ng=
Sandbox URL
https://core-api.sandbox-verifiedinc.com

To get an API key for your own brand, email us at Support@Verified.Inc.

Test User Login Credentials
Phone
+10123456789
Email
richard@piedpiper.net
Verification Code
111111

These are Hooli and Richard Hendricks — yes, the ones from Silicon Valley! 😂

caution

API keys are sensitive, so please only use them in a secure backend service environment. This means that ideally your clients will communicate with your own backend service, which will then call the Verified Inc. API. Your clients should never have direct access to your Verified Inc. API key.

Environments​

We have two environments. Please do all integration against the sandbox environment.

EnvironmentBase URLWallet URL
Sandboxhttps://core-api.sandbox-verifiedinc.comhttps://wallet.sandbox-verifiedinc.com
Productionhttps://core-api.verified.inchttps://wallet.verified.inc
note

The sandbox domain is sandbox-verifiedinc.com but the production domain is verified.inc. This is purely because .inc domains are quite expensive!

Development​

While developing your integration you can use a dummy user account if you would like.

email: richard@piedpiper.net || richard.hendricks@verified.inc
phone: +10123456789 || +550123456789

By using these test identifiers you can authenticate to the wallet using a static OTP value of 111111, allowing you to test the full flow of the integration more easily. We recommend using a proper test email or phone to recieve actual verification messages during the final stages of development.

caution

Credentials issued to the test user will be deleted every day at 05:00 UTC.

Core Functionality​

The core functionality of our API allows your brand to participate in the Verified Network through 1-Click Signup. For more advanced use cases like Issue to Earn, please refer to our advanced API section.

1-Click​

Begin a 1-Click Signup flow, so a

A user is an individual in the Verified Inc. network. Each user has at least one phone or emails, aka userIdentifiers associated with them. They can have multiple of either.
Example: Richard is a user in your account system and potentially of the Verified Inc. network. He has two email addresses and one phone with him. Credentials can be issued to or requested of him using any of these identifiers.
Components: Referenced in API endpoints `/hasMatchingCredentials` and `/issueCredentials`. User data is associated by using these user identifiers that you already keep on your users.
user can easily share their verified
A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials.

Method: POST
Path: /1-click

You need to provide:

  1. User's phone
  2. (Optional) User's email.
  3. (Optional) Verification option(s). Controls the SMS verification messaging.
  4. (Optional) Content object of request page options. To allow for minor messaging adjustments to the Wallet request page from which the user provides consent to share data.
  5. (Optional) Credential request(s). (if you would like to deviate from the default credential requests).
  6. (Optional) Redirect URL. If you would like to redirect the user to a different URL than the one provided in your settings.
  7. (Optional) isHosted. If you would like to do the non-hosted integration .
  8. (Optional) User's birthDate. Only required if you are using the non-hosted integration.

A credential requests encodes which

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials you're asking the user to share with your
A brand is a company entity that has a corresponding unique api key, name, and card image. Brands can issue, request and receive credentials to and from users.
Example: ACME Bank is an Verified Inc. customer. However, they have two separate brands: ACME Lending and ACME Savings. Each brand has a unique api key, name, and card image.
Components: Each brand has an associated umbrella customer. It is totally okay if your customer only has one brand. We want to have the flexibility to support multiple brands per customer.
brand. It's a list of one or more CredentialRequest objects.

CredentialRequest
{
  type: string, // the type of credential data being requested
  issuers: string[], // list of acceptable brandIds; if empty, all issuer brands are valid
  required?: boolean, // @deprecated - Use mandatory field instead. If the credential is required
  mandatory?: 'yes' | 'no' | 'if_available' // if the credential is required, not required, or required if available.
  description?: string // a description field that is shown to the user; can be used to explain why the information is being requested
  allowUserInput?: boolean // when true, the user will be shown an input to add their own information if they choose.
  children?: CredentialRequest[] // list of sub-credentials relevant to the parent credential (e.g. FullNameCredential(FirstNameCredential, MiddleNameCredential LastNameCredential)
}

The endpoint comes with a default credential requests configuration shown below which should be suffice for most customers.

Default 1-Click Credential Requests

[
  {
    "type": "FullNameCredential",
    "children": [
      {
        "type": "FirstNameCredential"
      },
      {
        "type": "MiddleNameCredential"
      },
      {
        "type": "LastNameCredential"
      }
    ],
    "allowUserInput": true
  },
  {
    "type": "EmailCredential",
    "allowUserInput": true
  },
  {
    "type": "PhoneCredential"
  },
  {
    "type": "AddressCredential",
    "children": [
      {
        "type": "Line1Credential"
      },
      {
        "type": "Line2Credential"
      },
      {
        "type": "CityCredential"
      },
      {
        "type": "StateCredential"
      },
      {
        "type": "CountryCredential"
      },
      {
        "type": "ZipCodeCredential"
      }
    ],
    "allowUserInput": true
  },
  {
    "type": "BirthDateCredential",
    "allowUserInput": true
  },
  {
    "type": "SsnCredential",
    "allowUserInput": true
  }
]

note

This endpoint performs a similar role to /hasMatchingCredentials but with a few key differences:

  • Can only be used with a user's phone number
  • Triggers an SMS verification message to the user that Verified Inc. sends
  • Much greater chance of success getting user data than the standard acceptance flow because data is pulled on demand
caution

The same API key necessary to call /1-click grants you, and only, you access to the encrypted credential data documented in Get Shared Credentials. Please keep this key secure.

Request Body​

1-Click Request
{
  phone: string, // user's phone number in E.164 format
  email?: string, // user's email address; optional
  verificationOptions?: 'only_link' | 'only_code' | 'both_link_and_code' // Optional: controls the SMS verification messaging. Default is 'only_code'.
  content?: {
    title?: 'Signup' | 'Verify' | 'Apply', // Optional: title of the request page. Default is 'Signup'
    description?: string, // Optional: description displayed under the consent page header. Default is 'Make sure everything is correct:'
  }
  credentialRequests?: CredentialRequest[], // Optional: a list of one or more CredentialRequest objects. Encodes which credentials are being asked for
  redirectUrl?: string, // Optional: redirect url to redirect user to after the user has completed the 1-click flow. Default is the redirect url provided in your settings.
  isHosted?: boolean, // Optional: if you would like to do the non-hosted integration. Default is true.
  birthDate?: string // Optional: user's birth date in YYYY-MM-DD format. Required if you are using the non-hosted integration.
}

Response Body​

1-Click Response
{
  "url": string // Verified Inc. Web Wallet url to redirect user to for credential request handling. It will redirect back to your client. Only present if match is true.
  "match": boolean // indicates whether we can provide the user with a 1-Click Signup flow
  "smsBody": string // the SMS body that we recommend sending to the user; You will only have to handle sending the SMS in Production.
}

The url from the response ought to then be enriched with a redirectUrl query param that will take the next step in your target service's user onboarding webpage. More information on this can be found in the 1-Click Guide.

Trusted 1-Click​

The "trusted" 1-click sign-up flow is very similar to the standard 1-click sign-up flow, but allows for the user to skip the phone OTP step with us. The "trusted" nomenclature comes from Verified Inc. having to perform additional integration checks prior to enabling this feature for your brand.

Method: POST
Path: /1-click/trusted

You need to provide:

  1. User's phone
  2. User's birth date.
  3. (Optional) User's email.
  4. (Optional) Credential request(s). If you would like to update from the default credential requests.

A credential requests encodes which

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials you're asking the user to share with your
A brand is a company entity that has a corresponding unique api key, name, and card image. Brands can issue, request and receive credentials to and from users.
Example: ACME Bank is an Verified Inc. customer. However, they have two separate brands: ACME Lending and ACME Savings. Each brand has a unique api key, name, and card image.
Components: Each brand has an associated umbrella customer. It is totally okay if your customer only has one brand. We want to have the flexibility to support multiple brands per customer.
brand. It's a list of one or more CredentialRequest objects.

CredentialRequest
{
  type: string, // the type of credential data being requested
  issuers: string[], // list of acceptable brandIds; if empty, all issuer brands are valid
  required?: boolean, // @deprecated - Use mandatory field instead. If the credential is required
  mandatory?: 'yes' | 'no' | 'if_available' // if the credential is required, not required, or required if available.
  description?: string // a description field that is shown to the user; can be used to explain why the information is being requested
  allowUserInput?: boolean // when true, the user will be shown an input to add their own information if they choose.
  children?: CredentialRequest[] // list of sub-credentials relevant to the parent credential (e.g. FullNameCredential(FirstNameCredential, MiddleNameCredential LastNameCredential)
}

The endpoint comes with a default credential requests configuration shown below which should be suffice for most customers.

Default 1-Click Credential Requests

[
  {
    "type": "FullNameCredential",
    "children": [
      {
        "type": "FirstNameCredential"
      },
      {
        "type": "MiddleNameCredential"
      },
      {
        "type": "LastNameCredential"
      }
    ],
    "allowUserInput": true
  },
  {
    "type": "EmailCredential",
    "allowUserInput": true
  },
  {
    "type": "PhoneCredential"
  },
  {
    "type": "AddressCredential",
    "children": [
      {
        "type": "Line1Credential"
      },
      {
        "type": "Line2Credential"
      },
      {
        "type": "CityCredential"
      },
      {
        "type": "StateCredential"
      },
      {
        "type": "CountryCredential"
      },
      {
        "type": "ZipCodeCredential"
      }
    ],
    "allowUserInput": true
  },
  {
    "type": "BirthDateCredential",
    "allowUserInput": true
  },
  {
    "type": "SsnCredential",
    "allowUserInput": true
  }
]

note

This endpoint performs a similar role to /1-click but with a few key differences:

  • You must handle user's phone verification within the same session of calling this endpoint
  • The user's
    A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
    Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
    Components: A company issues credentials following the steps in the Issuance Guide.
    credentials are returned synchronously in the response body

Request Body​

Trusted 1-Click Request
{
  phone: string, // user's phone number in E.164 format
  birthDate: string // user's birth date in YYYY-MM-DD format. Required if you are using the non-hosted integration.
  email?: string, // Optional; user's email address;
  credentialRequests?: CredentialRequest[], // Optional: a list of one or more CredentialRequest objects. Encodes which credentials are being asked for
}

Response Body​

Trusted 1-Click Response
{
  "uuid": string // the 1-click uuid that can be used to update the user's credentials if they edit them post retrieval in your sign up form
  "identifiers": {
      [identifierType: string]: string
  },
  "credentials": {
      [shortenedCredentialType: string]: string
  },
  "metadata": {
      "identifiers": {
          [identifierType: string]: {
              [metadataType: string]: string
          }
      },
      "credentials": {
          [shortenedCredentialType: string]: {
              [metadataType: string]: string
          }
      }
  }
}

The 1-click/trusted response is identical to the Get 1-Click Credentials response, but with the addition of the uuid attribute. This uuid can be used to update the user's credentials if they edit them post-retrieval in your sign-up form. You are inventive in calling the update endpoint for the benefit of issue to earn.

Get 1-Click Credentials​

Get the

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials of a user who has completed a 1-Click Signup flow.

Method: GET
Path: /1-click/{uuid}

When a

A user is an individual in the Verified Inc. network. Each user has at least one phone or emails, aka userIdentifiers associated with them. They can have multiple of either.
Example: Richard is a user in your account system and potentially of the Verified Inc. network. He has two email addresses and one phone with him. Credentials can be issued to or requested of him using any of these identifiers.
Components: Referenced in API endpoints `/hasMatchingCredentials` and `/issueCredentials`. User data is associated by using these user identifiers that you already keep on your users.
user completes a 1-Click Signup flow, the
A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials are sent and stored securely awaiting retrieval. Additionally, as mentioned above in 1-Click, upon the user completing the flow, the user will be redirected back to your client with a 1ClickUuid as a query parameter.

This endpoint allows you to retrieve the

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials related to the
A request (or credential request) is a request for a credentials to be shared by a user. It's created when a company successfully checks if a user has matching credentials, via /hasMatchingCredentials. Only if the user has the ability to response with the matching credentials is a request created.
Example: Hooli FinTech checks if Richard has a SSN and LastName credential issued by ACME Lending. Because he does, a request is created for those credentials specifically from ACME Lending. Hooli presents this request to Richard by directing him to the `url` received in the `/hasMatchingCredentials` response body.
Components: A company creates a user specific request by using /hasMatchingCredentials.. If it is case the user does not have the desired credentials then a request is not created. If it is the case the user does, a request is created and is returned in the form of a `url` attribute in response to the client.
request created as a result of a successful 1-Click Signup flow.

You need to provide:

  • the 1ClickUuid that was returned in the query param after redirecting the user to the redirectUrl attribute from the /1-click response
info

Your brand's access to 1-Click credentials is deleted after 5 minutes of the initial credential data retrieval.

info

If in the 1-Click Response, the credentials attribute is not present, then means the user opted out of sharing their credentials. But you can still use the 1ClickUuid to check if the user verified their phone number or email address.

Definitions
  • An identifier is a phone number or email address the user uses to verify for 1-Click Signup.
    • identifierType is the type of identifier (phone or email).
  • A credential is a piece of data the user shares (e.g. birth date or SSN).

    • A credential type is a string indicating the type of a credential (e.g. SsnCredential or FirstNameCredential). It's formatted in PascalCase and always includes the word Credential at the end.

    • shortenedCredentialType is the shortened credential type in camelCase. The shortened credential type is just the type without the word Credential (e.g. birthDate or ssn). For subcredentials of a composite credential, it includes the shortened credential type of its parent credential(s) (e.g. fullName.firstName).

      Accepted Values

      Currently, accepted values for shortenedCredentialType are:

      • email
      • fullName.firstName
      • fullName.middleName
      • fullName.lastName
      • birthDate
      • address.line1
      • address.line2
      • address.city
      • address.state
      • address.zipCode
      • address.country
      • ssn
  • Data in this context means identity information about a user (e.g. their name, contact information, etc.)
  • Metadata in this context means any additional data that's not identity information about a user (e.g. the verification method for their identity information).

    • metadataType is the type of metadata.

      Accepted Values

      Currently, possible values for metadataType are:

      • id: unique identifier for a credential
        • UUID
        • Applies only to credentials
      • verificationMethod: how an identifier or credential was verified
        • enum: "phone_carrier", "otp", "self_attested", or null
        • Applies to both identifiers and credentials
      • status: status of a credential
        • enum: "valid" or "revoked"
        • Applies only to credentials
      • issuerUuid: brand that issued a credential
        • UUID
        • Applies only to credentials
      • issuanceDate: date a credential was issued
        • Unix timestamp
        • Applies only to credentials
      • expirationDate: date a credential expires
        • Unix timestamp
        • Applies only to credentials

Response Body​

1-Click Response
{
  "identifiers": {
      [identifierType: string]: string
  },
  "credentials": {
      [shortenedCredentialType: string]: string
  },
  "metadata": {
      "identifiers": {
          [identifierType: string]: {
              [metadataType: string]: string
          }
      },
      "credentials": {
          [shortenedCredentialType: string]: {
              [metadataType: string]: string
          }
      }
  }
}
tip

One particularly valuable piece of metadata is verificationMethod, which describes how the credential (piece of user data) was verified. It can take the following values:

  • "phone_carrier": verified via phone carrier records
  • "otp": verified via an OTP (one time passcode)
  • "self_attested": attested by the user themselves (not verified)
  • null
User Data Format

We support a few different formats for user data, for example the default format for the dateBirth credential is a unixTimestamp, but you can also request it different formats (e.g. MM/DD/YYYY or YYYY-MM-DD), or for the state credential, you can request it as a 2-letter abbreviation (e.g. CA) or as the full state name (e.g. California).

Accepted Formats

Currently, accepted formats for user data are:

  • dateBirth: unixTimestamp, or any combination of y(year), M(month), d(day), /(slash), and -(dash)
  • state: 2-letter abbreviation, full state name
  • country: 2-letter abbreviation, full country name
  • address: instead getting a object with all keys, you can get a string with any combination, (e.g. line1, city, state-country)
  • fullName: instead getting a object with all keys, you can get a string with any combination, (e.g. firstName, lastName)

Update 1-Click Credentials​

This endpoint is to be used for updating the 1-click credentials passed to your brand in the 1-click non-hosted and 1-click trusted flows.

Method: POST
Path: /1-click/{uuid}/credentials

You need to provide:

  1. The 1-click uuid
  2. The credential values in same format they were provided. See example below.
Example Simplified Credentials Format
{
    "fullName": {
        "firstName": "Leonardo",
        "lastName": "Messi"
    },
    "ssn": "111111110",
    "email": "leonardo@verified.inc"
}

This is an optional endpoint only relevant for the 1-click non-hosted and trusted variants. Because we send the user's data directly to your application, without the user using our web Wallet (which is part of the hosted variant), the user never gets a chance to update any of the data that's autofilled for them. If you allow them to editing and/or enrich their data on your side, within a UI/UX that you manage and implement, you can use this endpoint to pass that information back to us (and earn revenue share as a result).

important

If this endpoint is optional, why use it?

If you to call this endpoint after the user has made edits to their data on your side, you will earn a share of the revenue generated when the user uses that data elsewhere.revenue streams.

Request Body​

Update 1-Click Credentials Request Body
{
  "uuid": string // the 1-click uuid from the POST /1-click/trusted response
  "credentials": {
      [shortenedCredentialType: string]: string
  }
}

The response body will contain credentials conforming to credential schemas. Please see the Postman docs for examples of this response body.

Response Body​

1-Click Response
[
  {
    type: string, // credential type
    verificationMethod: string // verification method
    data: CredentialsList | {
      [credentialKey: string]: string // credential data
    },
  }
]

The response body is currently in a more verbose format than that of the response for GET /sharedCredentials or POST /1-click (both trusted and non-hosted). However, in practice, the details of the response body are non-consequential for you as long as a 201 HTTP status code is received.

Advanced Functionality​

The 1-Click Signup functionality that is covered in the core API section are higher level abstractions for these advanced endpoints. Thus, it is unlikely you will need to use these for most flows. However, for completeness please refer to this section for the advanced use cases documentation which covers endpoints mostly related to pure Issue to Earn integrations.

Check User Credentials​

Check if a user has matching

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials. If so, a
A request (or credential request) is a request for a credentials to be shared by a user. It's created when a company successfully checks if a user has matching credentials, via /hasMatchingCredentials. Only if the user has the ability to response with the matching credentials is a request created.
Example: Hooli FinTech checks if Richard has a SSN and LastName credential issued by ACME Lending. Because he does, a request is created for those credentials specifically from ACME Lending. Hooli presents this request to Richard by directing him to the `url` received in the `/hasMatchingCredentials` response body.
Components: A company creates a user specific request by using /hasMatchingCredentials.. If it is case the user does not have the desired credentials then a request is not created. If it is the case the user does, a request is created and is returned in the form of a `url` attribute in response to the client.
request is created to get the
A user is an individual in the Verified Inc. network. Each user has at least one phone or emails, aka userIdentifiers associated with them. They can have multiple of either.
Example: Richard is a user in your account system and potentially of the Verified Inc. network. He has two email addresses and one phone with him. Credentials can be issued to or requested of him using any of these identifiers.
Components: Referenced in API endpoints `/hasMatchingCredentials` and `/issueCredentials`. User data is associated by using these user identifiers that you already keep on your users.
user's consent to share the data.

Method: POST
Path: /hasMatchingCredentials

You need to provide:

  1. User's email or phone
  2. (Optional) Credential request(s). Required if Partner UUID is not provided.
  3. (Optional) Partner UUID. More information on the partner UUID use case can be found in the Issuance Guide.
  4. (Optional) List of the sub-credentials that make up the credential. If not provided, all sub-credentials will be returned.

A credential requests encodes which

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials you're asking the user to share with your
A brand is a company entity that has a corresponding unique api key, name, and card image. Brands can issue, request and receive credentials to and from users.
Example: ACME Bank is an Verified Inc. customer. However, they have two separate brands: ACME Lending and ACME Savings. Each brand has a unique api key, name, and card image.
Components: Each brand has an associated umbrella customer. It is totally okay if your customer only has one brand. We want to have the flexibility to support multiple brands per customer.
brand. It's a list of one or more CredentialRequest objects.

CredentialRequest
{
  type: string, // the type of credential data being requested
  issuers: string[], // list of acceptable brandIds; if empty, all issuer brands are valid
  required?: boolean, // @deprecated - Use mandatory field instead. If the credential is required
  mandatory?: 'yes' | 'no' | 'if_available' // if the credential is required, not required, or required if available.
  description?: string // a description field that is shown to the user; can be used to explain why the information is being requested
  allowUserInput?: boolean // when true, the user will be shown an input to add their own information if they choose.
  children?: CredentialRequest[] // list of sub-credentials relevant to the parent credential (e.g. FullNameCredential(FirstNameCredential, MiddleNameCredential LastNameCredential)
}

If you list multiple issuers, the user can include a credential issued by any one of those listed. If issuers is left empty the user can include a credential with matching type issued by any issuer.

note

The Credential

A request (or credential request) is a request for a credentials to be shared by a user. It's created when a company successfully checks if a user has matching credentials, via /hasMatchingCredentials. Only if the user has the ability to response with the matching credentials is a request created.
Example: Hooli FinTech checks if Richard has a SSN and LastName credential issued by ACME Lending. Because he does, a request is created for those credentials specifically from ACME Lending. Hooli presents this request to Richard by directing him to the `url` received in the `/hasMatchingCredentials` response body.
Components: A company creates a user specific request by using /hasMatchingCredentials.. If it is case the user does not have the desired credentials then a request is not created. If it is the case the user does, a request is created and is returned in the form of a `url` attribute in response to the client.
requests attribute is required if a Partner UUID is not provided. If Partner UUID is provided, the Credential requests attribute is not used. Instead, a pre-defined set of accepting partner's credentials requests are used. More information on the partner UUID use case can be found in the Issuance Guide.

tip

If mandatory field are missing, then the credential will be treated as optional.

note

The Credential

A request (or credential request) is a request for a credentials to be shared by a user. It's created when a company successfully checks if a user has matching credentials, via /hasMatchingCredentials. Only if the user has the ability to response with the matching credentials is a request created.
Example: Hooli FinTech checks if Richard has a SSN and LastName credential issued by ACME Lending. Because he does, a request is created for those credentials specifically from ACME Lending. Hooli presents this request to Richard by directing him to the `url` received in the `/hasMatchingCredentials` response body.
Components: A company creates a user specific request by using /hasMatchingCredentials.. If it is case the user does not have the desired credentials then a request is not created. If it is the case the user does, a request is created and is returned in the form of a `url` attribute in response to the client.
requests objects can contain a children attribute. This attribute is used to specify the sub-credentials that make up the credential. If not provided, all sub-credentials will be returned. (eg: If you request a
A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credential of type AddressCredential and you only want the city and state sub-credentials, you can specify that in the children attribute.)

caution

The same ApiKey necessary to call /hasMatchingCredentials grants you and only you access to the encrypted credential data documented in Get Shared Credentials. Please keep this key secure.

Request Body​

{
  email?: string, // user's email address; optional if phone is provided
  phone?: string, // user's phone number; optional if email is provided
  credentialRequests: CredentialRequest[], // a list of one or more CredentialRequest objects. Encodes which credentials are being asked for; not used if partnerUuid is provided
  partnerUuid?: string, // partner's uuid; optional
  description?: string // A description displayed in the consent page header. If no description is provided, a default value will be displayed.
}

Response Body​

HasMatchingCredentials
{
  "match": boolean, // indicates whether the user has matching credentials
  "url": string // Verified Inc. Web Wallet url to redirect user to for credential request handling. It will redirect back to your client. Only present if match is true.
}

The url from the response ought to then be enriched with a redirectUrl query param that will take the next step in your target service's user onboarding webpage. More information on this can be found in the Acceptance Guide.

Example Credential Request

For example, if you want to check if a user has credentials of type SsnCredential, FullNameCredential and AddressCredential issued by any issuer you would send the following request:

Request Body

{
  "email": "richard@piedpiper.net",
  "credentialRequests": [
    {
      "type": "SsnCredential",
      "issuers": [],
      "mandatory": "yes"
    },
    {
      "type": "FullNameCredential",
      "issuers": [],
      "mandatory": "yes"
    },
    {
      "type": "PhoneCredential",
      "issuers": [],
      "mandatory": "if_available",
      "allowUserInput": true
    },
    {
      "type": "AddressCredential",
      "issuers": [],
      "children": [
        {
          "type": "CityCredential",
          "issuers": [],
          "mandatory": "if_available"
        },
        {
          "type": "StateCredential",
          "issuers": [],
          "mandatory": "yes"
        },
        {
          "type": "CountryCredential",
          "issuers": [],
          "mandatory": "yes"
        },
        {
          "type": "ZipCodeCredential",
          "issuers": []
        }
      ]
    }
  ]
}

Let's break this down to understand what is happening here:

  • SsnCredential is a "single attribute atomic credential" and therefore does not have any sub-credentials. Because it is marked as mandatory, it only matches if the user has a credential.
SnnCredential
{
  "type": "SsnCredential",
  "issuers": [],
  "mandatory": "yes"
}
  • FullNameCredential is a "composite credential" and therefore has 2 sub-credentials¹: FirstNameCredential, LastNameCredential. Because it is marked as mandatory, and it has no children attribute, it only matches if the user has a credential with all sub-credentials.
FullNameCredential
{
  "type": "FullNameCredential",
  "issuers": [],
  "mandatory": "yes"
}
  • PhoneCredential is a "single attribute atomic credential" and therefore does not have any sub-credentials. Because we set a allowUserInput attribute of true, the user will be given an opportunity to enter a new value if they choose to. Note that this have not relation with mandatory field, it just accepts and validates the user input data."
PhoneCredential
{
  "type": "PhoneCredential",
  "issuers": [],
  "mandatory": "if_available",
  "allowUserInput": true
}

  • The AddressCredential credential is made up of 6 sub-credentials: Line1Credential, Line2Credential, CityCredential, StateCredential, CountryCredential and ZipCodeCredential.

    But because we specified a children attribute, we are only asking for the CityCredential, StateCredential, CountryCredential and ZipCodeCredential sub-credentials. So Line1Credential and Line2Credential are ignored.

    AddressCredential
    {
      "type": "AddressCredential",
      "issuers": [],
      "children": [
        {
          "type": "CityCredential",
          "issuers": [],
          "mandatory": "if_available"
        },
        {
          "type": "StateCredential",
          "issuers": [],
          "mandatory": "yes"
        },
        {
          "type": "CountryCredential",
          "issuers": [],
          "mandatory": "yes"
        },
        {
          "type": "ZipCodeCredential",
          "issuers": []
        }
      ]
    }

The user will be asked to share the CityCredential if available (this means if the user has a credential of type CityCredential it will be mandatory, but if the user does not have a credential of type CityCredential the user will still be able to share the AddressCredential credential).

StateCredential and CountryCredential are mandatory and therefore the user must have a credential of each type to match.

ZipCodeCredential is optional and therefore the user may or may not have a credential of type to match.

Get Shared Credentials​

Get verified

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credential data shared by a
A user is an individual in the Verified Inc. network. Each user has at least one phone or emails, aka userIdentifiers associated with them. They can have multiple of either.
Example: Richard is a user in your account system and potentially of the Verified Inc. network. He has two email addresses and one phone with him. Credentials can be issued to or requested of him using any of these identifiers.
Components: Referenced in API endpoints `/hasMatchingCredentials` and `/issueCredentials`. User data is associated by using these user identifiers that you already keep on your users.
user.

Method: GET
Path: /sharedCredentials/{sharedCredentialsUuid}

When a

A user is an individual in the Verified Inc. network. Each user has at least one phone or emails, aka userIdentifiers associated with them. They can have multiple of either.
Example: Richard is a user in your account system and potentially of the Verified Inc. network. He has two email addresses and one phone with him. Credentials can be issued to or requested of him using any of these identifiers.
Components: Referenced in API endpoints `/hasMatchingCredentials` and `/issueCredentials`. User data is associated by using these user identifiers that you already keep on your users.
user responds to a
A request (or credential request) is a request for a credentials to be shared by a user. It's created when a company successfully checks if a user has matching credentials, via /hasMatchingCredentials. Only if the user has the ability to response with the matching credentials is a request created.
Example: Hooli FinTech checks if Richard has a SSN and LastName credential issued by ACME Lending. Because he does, a request is created for those credentials specifically from ACME Lending. Hooli presents this request to Richard by directing him to the `url` received in the `/hasMatchingCredentials` response body.
Components: A company creates a user specific request by using /hasMatchingCredentials.. If it is case the user does not have the desired credentials then a request is not created. If it is the case the user does, a request is created and is returned in the form of a `url` attribute in response to the client.
request the verified data is sent and stored securely awaiting retrieval. Additionally, as mentioned above in Check User Credentials, upon the user responding to the request, the user will be redirected back to your client with a sharedCredentialsUuid as a query parameter.

This endpoint allows you to retrieve the shared

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials data related to the
A request (or credential request) is a request for a credentials to be shared by a user. It's created when a company successfully checks if a user has matching credentials, via /hasMatchingCredentials. Only if the user has the ability to response with the matching credentials is a request created.
Example: Hooli FinTech checks if Richard has a SSN and LastName credential issued by ACME Lending. Because he does, a request is created for those credentials specifically from ACME Lending. Hooli presents this request to Richard by directing him to the `url` received in the `/hasMatchingCredentials` response body.
Components: A company creates a user specific request by using /hasMatchingCredentials.. If it is case the user does not have the desired credentials then a request is not created. If it is the case the user does, a request is created and is returned in the form of a `url` attribute in response to the client.
request created as a result of a successful match from the /hasMatchingCredentials endpoint.

You need to provide:

  • the sharedCredentialsUuid that was returned in the query param after redirecting the user to the redirectUrl attribute from the /hasMatchingCredentialsresponse
info

Your brand's access to shared credentials is deleted after 5 minutes of the initial credential data retrieval.

The response body consists of Credential objects with the plaintext user data.

Credential
{
    "id": string, // credential id
    "type": string, // credential type
    "issuer": string, // credential issuer brandId
    "issuanceDate": number, // when credential was created as a milliseconds since epoch unix timestamp
    "expirationDate"?: number, // when credentials expires as a milliseconds since epoch unix timestamp
    "data": Map<string, any> | Credential[] // credential data map/array that matches the credential type's JSON Schema definition
}

Response Body​

SharedCredentials
{
  "uuid": string, // the uuid from the query parameter of the redirect back to your client; identifies the collection of credentials shared by the user
  "credentials": Credential[], // a list of one or more Credential objects
  "email"?: string, // the user's email from the input to /hasMatchingCredentials; only present if email was provided
  "phone"?: string // the user's phone from the input to /hasMatchingCredentials; only present if phone was provided
}

To facilitate extracting the credential data we recommend leveraging the Schema Resolver to get the schema of the credential types. Because Credential schemas are immutable they can then be cached and referenced when retrieving the credential data.

Issue Credentials​

Issue

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credentials to a
A user is an individual in the Verified Inc. network. Each user has at least one phone or emails, aka userIdentifiers associated with them. They can have multiple of either.
Example: Richard is a user in your account system and potentially of the Verified Inc. network. He has two email addresses and one phone with him. Credentials can be issued to or requested of him using any of these identifiers.
Components: Referenced in API endpoints `/hasMatchingCredentials` and `/issueCredentials`. User data is associated by using these user identifiers that you already keep on your users.
user.

Method: POST
Path: /credentials

You need to provide:

  1. Credentials data array
  2. Either a phone and/or email attribute
  3. (Optional) Partner UUID. More information on the partner UUID use case can be found in the Issuance Guide.
  4. (Optional) Tracking Identifier for credential usage attribute. More information on the tracking identifier use case can be found in the Issuance Guide.

Data about the user, must comply with our credential schema definitions.

An example Credentials object is below:

Credentials
{
  "type": string, // credential type
  "data": Map<string, any> | Credentials[], // credential data map/array that matches the credential type's JSON Schema definition
  "id"?: string, // credential id - uuid formatted; optional. If not provided, a random uuid will be generated
  "expirationDate?": number // when the credential expires as a milliseconds since unix epoch; optional
}

While not required, we recommend providing a unique id following uuid format for each credential. This allows for idempotent credential issuance - meaning if a duplicate id value is seen another credential will not be created. Expect a HTTP status code of 409 if this is the case. If you do not provide an id, a random uuid will be generated for you.

note

An expiration date is not the only control on whether a credential is valid. You can also change the credential's status at any time, for example to revoke it. See Patch Credentials.

info

Credential data is stored securely via a data privacy vault that encrypts and tokenizes the data. The data is only retrieved and decrypted for the brand that the

A user is an individual in the Verified Inc. network. Each user has at least one phone or emails, aka userIdentifiers associated with them. They can have multiple of either.
Example: Richard is a user in your account system and potentially of the Verified Inc. network. He has two email addresses and one phone with him. Credentials can be issued to or requested of him using any of these identifiers.
Components: Referenced in API endpoints `/hasMatchingCredentials` and `/issueCredentials`. User data is associated by using these user identifiers that you already keep on your users.
user agrees to share with.

Composite Credentials

Composite credentials are credentials that are made up of other credentials. For example, a FullNameCredential is made up of FirstNameCredential, MiddleNameCredential(optional), and LastNameCredential. When issuing a composite credential, you must provide the child credentials as well.

Example
Composite Credential
{
  "type": "FullNameCredential",
  // based on the properties attribute of the schema
  // note that the data is an array of objects, not a single object
  "data": [
    {
      "type": "FirstNameCredential",
      "data": {
        "firstName": "Richard"
      }
    },
    {
      "type": "LastNameCredential",
      "data": {
        "lastName": "Hendricks"
      }
    }
  ]
}

See Data Schemas for more information.

Request Body​

{
  "credentials": Credentials[], // a list of one or more Credentials objects
  "email"?: string, // user's email address; optional if phone is provided
  "phone"?: string // user's phone number in E.164 format; optional if email is provided
  "trackingId"?: string // user tracking identifier
}

Response Body​

CredentialsDto
{
  "email": string, // user's email address if provided
  "phone": phone, // user's phone number if provided
  "trackingId"?: string // user tracking identifier if provided
  "credentials": [{
    "id": string, // credential id
    "type": string, // credential type
    "data": Map<string, any> | Credentials[], // credential data map/array that matches your provided data and the credential type's JSON Schema definition
    "issuanceDate": string, // when credential was created as a milliseconds since epoch unix timestamp
    "expirationDate?": string, // when the credential expires as a milliseconds since unix epoch; optional
    "status": 'valid' | 'revoked' // an enum to denote whether the credential is valid (all credentials are valid when first issued) — note that this is independent of the expirationDate
  }],
  "url"?: string // Only present if partnerUuid was provided and conditions are met. See the Issuance Guide for more information.
}

The issued credential contains an id that you should store. You'll need this, for example, if you ever want to revoke the credential. We recommend storing the entire credential, indexed on the credential id. However, it is also an acceptable to store credential ids associated with a user and use the Get Credential or Get All User Credentials endpoint to retrieve the full credential.

Patch Credential​

Patch a previously issued

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credential.

Method: PATCH
Path: /credentials/{id}

You can optionally provide any of the following in the request body:

  1. (Optional) new credential data
  2. (Optional) new credential expiration date
  3. (Optional) new credential status

Credential data must comply with our credential schema definitions.

note

If a credential is expired but the status is 'valid' it is an unusable credential. Likewise, if the credential as not expired but the status is 'revoked', it is also not usable credential.

info

Credential data is stored securely via a data privacy vault that encrypts and tokenizes the data. The data is only retrieved and decrypted for the brand that the

A user is an individual in the Verified Inc. network. Each user has at least one phone or emails, aka userIdentifiers associated with them. They can have multiple of either.
Example: Richard is a user in your account system and potentially of the Verified Inc. network. He has two email addresses and one phone with him. Credentials can be issued to or requested of him using any of these identifiers.
Components: Referenced in API endpoints `/hasMatchingCredentials` and `/issueCredentials`. User data is associated by using these user identifiers that you already keep on your users.
user agrees to share with.

Request Body​

{
  "data": Map<string, any> | Credentials[], // credential data map/array that matches the credential type's JSON schema definition
  "expirationDate?": number // when the credentials expires as a milliseconds since epoch unix timestamp; optional
  "status": 'valid' | 'revoked' // an enum to denote whether the credential is valid (all credentials are valid when first issued) — note that this is independent of the expirationDate
}

Response Body​

CredentialDto
{
  "id": string, // credential id
  "type": string, // credential type
  "data": Map<string, any> | Credentials[], // credential data map/array that matches your provided data and the credential type's JSON Schema definition
  "issuanceDate": string, // when credential was created as a milliseconds since epoch unix timestamp
  "expirationDate?": number, // when the credential expires as a milliseconds since epoch unix timestamp; optional
  "status": 'valid' | 'revoked' // an enum to denote whether the credential is valid (all credentials are valid when first issued) — note that this is independent of the expirationDate.
}

The resultant credential id remains the same, so after a 200 HTTP response code is received, nothing further needs to be updated on your end.

Patch All User Credentials​

Patch all previously issued by your brand to a user.

Method: PATCH
Path: /userCredentials/{userIdentifier}

A

A userIdentifier is an email or phone value which is associated with a user.
Example: richard@pipedpiper.net is one of Richard Hendrick's user identifiers. He also has a phone number of +10123456789, another one of his user identifiers.
Components: We have abstracted away the complexity of dealing with a third party uuid to refer to a user. Instead, you can use the user's email or phone number to refer to and issue credentials to users in our system.
userIdentifier is either a phone number or email address associated with a user.

The only credential value that can by updated in this manner is status. A credential status must be in the request body.

note

This endpoint all modifies credentials issued to the user by your brand.

Request Body​

{
  "status": 'valid' | 'revoked' // an enum to denote whether the credential is valid (all credentials are valid when first issued) — note that this is independent of the expirationDate
}

Response Body​

UserCredentialsDto
{
  "credentials": {
    "id": string, // credential id
    "type": string, // credential type
    "data": Map<string, any> | Credentials[], // credential data map/array that matches your provided data and the credential type's JSON Schema definition
    "issuanceDate": string, // when credential was created as a milliseconds since epoch unix timestamp
    "expirationDate?": number, // when the credential expires as a milliseconds since epoch unix timestamp; optional
    "status": 'valid' | 'revoked' // an enum to denote whether the credential is valid (all credentials are valid when first issued) — note that this is independent of the expirationDate.
  }[]
}

The response body contains a list of all credentials that were modified on the credentials key.

Get Credential​

Get a previously issued

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials following the steps in the Issuance Guide.
credential.

Method: GET
Path: /credentials/{id}

This endpoint returns a credential (issued by your brand) via the credential id.

Response Body​

CredentialDto
{
  "id": string, // credential id
  "type": string, // credential type
  "data": Map<string, any> | Credentials[], // credential data map/array that matches your provided data and the credential type's JSON Schema definition
  "issuanceDate": string, // when credential was created as a milliseconds since epoch unix timestamp
  "expirationDate?": number, // when the credential expires as a milliseconds since epoch unix timestamp; optional
  "status": 'valid' | 'revoked' // an enum to denote whether the credential is valid (all credentials are valid when first issued) — note that this is independent of the expirationDate.
}

Get All User Credentials​

Get all previously issued by your brand to a user.

Method: GET
Path: /userCredentials/{userIdentifier}

A

A userIdentifier is an email or phone value which is associated with a user.
Example: richard@pipedpiper.net is one of Richard Hendrick's user identifiers. He also has a phone number of +10123456789, another one of his user identifiers.
Components: We have abstracted away the complexity of dealing with a third party uuid to refer to a user. Instead, you can use the user's email or phone number to refer to and issue credentials to users in our system.
userIdentifier is either a phone number or email address associated with a user.

note

This endpoint all modifies credentials issued to the user by your brand.

caution

It should be clear that this endpoint should not be used in place of /hasMatchingCredentials, which can check user credentials across many issuers but does not return the credentials' values.

This endpoint is simply a nice to have for an issuer to see all credentials they have issued to a user.

Response Body​

UserCredentialsDto
{
  "credentials": {
    "id": string, // credential id
    "type": string, // credential type
    "data": Map<string, any> | Credentials[], // credential data map/array that matches your provided data and the credential type's JSON Schema definition
    "issuanceDate": string, // when credential was created as a milliseconds since epoch unix timestamp
    "expirationDate?": number, // when the credential expires as a milliseconds since epoch unix timestamp; optional
    "status": 'valid' | 'revoked' // an enum to denote whether the credential is valid (all credentials are valid when first issued) — note that this is independent of the expirationDate.
  }[]
}

The response body contains a list of all credentials on the credentials key.

Get Partner Credential Requests​

Get the partner's pre-defined

A request (or credential request) is a request for a credentials to be shared by a user. It's created when a company successfully checks if a user has matching credentials, via /hasMatchingCredentials. Only if the user has the ability to response with the matching credentials is a request created.
Example: Hooli FinTech checks if Richard has a SSN and LastName credential issued by ACME Lending. Because he does, a request is created for those credentials specifically from ACME Lending. Hooli presents this request to Richard by directing him to the `url` received in the `/hasMatchingCredentials` response body.
Components: A company creates a user specific request by using /hasMatchingCredentials.. If it is case the user does not have the desired credentials then a request is not created. If it is the case the user does, a request is created and is returned in the form of a `url` attribute in response to the client.
credential requests.

Method: GET
Path: /credentialRequests/{partnerUuid}

This endpoint returns a list of credential requests that the partner has defined for their brand.

Response Body​

CredentialRequestsResponse
{
  "credentialRequests": CredentialRequest[]
}
CredentialRequest
{
  type: string, // the type of credential data being requested
  issuers: string[], // list of acceptable brandIds; if empty, all issuer brands are valid
  required?: boolean, // @deprecated - Use mandatory field instead. If the credential is required
  mandatory?: 'yes' | 'no' | 'if_available' // if the credential is required, not required, or required if available.
  description?: string // a description field that is shown to the user; can be used to explain why the information is being requested
  allowUserInput?: boolean // when true, the user will be shown an input to add their own information if they choose.
  children?: CredentialRequest[] // list of sub-credentials relevant to the parent credential (e.g. FullNameCredential(FirstNameCredential, MiddleNameCredential LastNameCredential)
}
note

This endpoint is helpful when developing the partner issuance flow. More information about partner issuance can be found in the Issuance Guide.