Skip to main content

Terminology

We use a few specialized terms and concepts. It's not necessary to understand these in full detail, but knowing a little about them will help you deploy and use our tech.

tip

We've included helpful tooltips like this one (hover over it) throughout the docs. These offer quick definitions, examples, and links to dive in deeper. Anytime you see an underline, hover over it to see the tooltip!

The tooltips you'll see most often refer to the terms described in this section (for example:

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).

ID Card​

A digital ID card is a collection of

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 issued by a
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 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.

Credential​

A credential is a collection of data about 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. It's issued by a
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 and can be
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.
requested by other
A customer is a company entity that serves as a parent to brands and their corresponding ApiKeys.
Example: ACME Bank is the Verified Inc. customer where their self service dashboard access rights are defined.
Components: The admins of the customer can manage individual brand settings.
customers, with 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.

Example: Hooli and Kredita are

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.
brands, and Richard is 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.

API:

Credential Data is Stored Securely

The data is stored securely using a data privacy vault and is only available to the user and brands the user agrees to share with.

At a high level, a credential contains three pieces of information:

  1. type
  2. user identifier
  3. user data

The data must match the data schema for the credential type.

Atomic​

Atomic credentials contain single data points. For example, an EmailCredential is an atomic credential that contains an email address.

Some atomic credentials can be contained within composite credentials. For example, FirstNameCredential is an atomic credential that can be contained within the composite FullNameCredential.

Example Atomic EmailCredential
{
  "id": "8a1d4e35-413d-496b-b499-8810b55cfb5c", // the credential id
  "type": "EmailCredential", // the type of credential
  "issuer": "32ef9562-312d-4a8b-8f3e-ccb8df500b55", // the brand uuid of the issuer
  "issuanceDate": "1671847264479", // date the credential was issued in milliseconds since unix epoch
  "expirationDate": "1871839024044", // date the credential expires in milliseconds since unix epoch
  // the data attribute must match the SsnCredential JSON schema properties as mentioned in the Data Schema section.
  // i.e. https://schema.verified.inc/jsonSchema/SsnCredential
  "data": {
    "email": "test@verified.inc"
  }
}

Composite​

Composite credentials are composed of multiple atomic credentials. For example, a FullNameCredential can be composed of a FirstNameCredential and a LastNameCredential. It can also include a MiddleNameCredential.

Example Composite FullNameCredential
{
  "id": "1be7c008-3f0c-4a21-9aad-69ca1c4251d2", // the credential id
  "type": "FullNameCredential", // the type of credential
  "issuer": "32ef9562-312d-4a8b-8f3e-ccb8df500b55", // the brand uuid of the issuer
  "issuanceDate": "1671847264479", // date the credential was issued in milliseconds since unix epoch
  "expirationDate": "1871839024044", // date the credential expires in milliseconds since unix epoch
  // the data attribute must match the FullNameCredential JSON schema properties as mentioned in the Data Schema section.
  // i.e. https://schema.verified.inc/jsonSchema/FullNameCredential
  "data": [
    {
      "id": "2e6a7b9a-e93e-43ba-98a9-c554f4e16457", // `FirstNameCredential` credential id
      "type": "FirstNameCredential", // the type of credential
      "issuer": "32ef9562-312d-4a8b-8f3e-ccb8df500b55", // the brand uuid of the issuer
      "issuanceDate": "1671847264479", // date the credential was issued in milliseconds since unix epoch
      "expirationDate": "1871839024044", // date the credential expires in milliseconds since unix epoch
      "data": {
        "firstName": "Richard"
      }
    },
    {
      "id": "9a5817ef-e621-4277-8c48-c8ee3776b6c4", // `LastNameCredential` credential id
      "type": "LastNameCredential", // the type of credential
      "issuer": "32ef9562-312d-4a8b-8f3e-ccb8df500b55", // the brand uuid of the issuer
      "issuanceDate": "1671847264479", // date the credential was issued in milliseconds since unix epoch
      "expirationDate": "1871839024044", // date the credential expires in milliseconds since unix epoch
      "data": {
        "lastName": "Hendricks"
      }
    }
  ]
}

Request​

A request (or credentials request) is a request for

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. It's created when a customer successfully checks if 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 has matching credentials, via /hasMatchingCredentials. A request is only created if the user has the type of credentials the customer needs.

Example: Hooli FinTech checks if Richard has a SSN and FullName 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 customer checks if a user has the needed types of credentials by using /hasMatchingCredentials. If 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 does not have the right credentials, then a request is not created. If the user does, a request is created and returned to the customer via the url attribute in the /hasMatchingCredentials response body.

The customer then directs the user to the url, where the user authenticates and agrees to share the relevant data.

At a high level, to create a request, a customer inputs a list containing three pieces of information for each credential which makes up the credentialsRequests atrribute.

  1. type of the credential
  2. acceptable
    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(s) that issued the credential
  3. whether the credential is required or optional (defaults to required)
  4. list of the sub-credentials that make up the credential (optional)

If multiple issuer brands are listed, a credential (of the correct type) from any one of them is acceptable. If none are listed, then any issuer brand is acceptable.

Additionally, the customer must input a user identifier email address and/or phone identifier. You might notice these are the exact inputs to /hasMatchingCredentials.

The full details of the request object aren't that important or helpful to know, as it's completely internal to Verified Inc., but here's an example of a request for a SsnCredential, PhoneCredential and FullNameCredential from the same issuing brand.

{
  "uuid": "7c9a2365-a2a3-4fec-b446-99b61a074fa8",
  "id": "854b9889-013d-40a2-93b9-68b9cf8d2540",
  "createdAt": "1673470082199",
  "updatedAt": "1673470082200",
  "email": "test@verified.inc",
  "phone": null,
  "description": "Please share the following information:",
  "credentialRequests": [
    {
      "type": "SsnCredential",
      "issuers": ["d14ca24c-5323-4b79-9dfa-6471b014d68c"],
      "required": true,
      "description": "We use your social security number for identity verification and tax reporting."
    },
    {
      "type": "PhoneCredential",
      "issuers": ["d14ca24c-5323-4b79-9dfa-6471b014d68c"],
      "mandatory": "yes",
      "allowUserInput": true
    },
    {
      "type": "FullNameCredential",
      "issuers": ["d14ca24c-5323-4b79-9dfa-6471b014d68c"],
      "required": true,
      "children": [
        {
          "type": "FirstNameCredential",
          "issuers": ["d14ca24c-5323-4b79-9dfa-6471b014d68c"]
        }
      ]
    }
  ],
  "expirationDate": null,
  "brand": {
    "uuid": "8005c39c-54d7-487e-bf4d-9eb5d39ed795",
    "id": "32ef9562-312d-4a8b-8f3e-ccb8df500b55",
    "createdAt": "1671595963109",
    "updatedAt": "1671595963109",
    "issuerName": "Hooli Issuer",
    "receiverName": "Hooli Receiver",
    "cardImageUrl": "https://VerifiedInc-dev-card-images.s3.us-west-2.amazonaws.com/ID+Card+-+Hooli.svg",
    "customerUuid": "bba94256-5366-4bd5-8e4b-6568be7aaf54"
  },
  "user": {
    "uuid": "77001639-9629-4bad-8d45-4cd0c2b7a7c8",
    "id": "e31de809-ea49-4384-9d3e-6c70d5ff05c7",
    "createdAt": "1671242870669",
    "updatedAt": "1671242870669",
    "phoneNumbers": ["+14043038080"],
    "emailAddresses": ["test@verified.inc"]
  }
}

User​

A user is an individual in the Verified Inc. network that can share verified identity data (via

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). Each user has at least one phone number or email address associated with them. They can have multiple of either.

note

Users can be referenced by email and/or phone, identifiers that you already have for your own user accounts. This prevents you from needing to use Verified Inc. specific user IDs.

Example: Richard is a user in your account system and potentially a user in the Verified Inc. network. You have two email addresses and one phone number for him. You can use any of these identifiers to issue credentials to him or check if he has matching credentials.

Components: You can issue credentials using /credentials and check for matching credentials with /hasMatchingCredentials.

{
  "id": "e31de809-ea49-4384-9d3e-6c70d5ff05c7",
  "createdAt": "1671242870669",
  "updatedAt": "1671242870669",
  "emailAddresses": ["test@verified.inc"],
  "phoneNumbers": []
}

User Identifier​

A userIdentifier is a value used to refer to an user. Due to the ubiquitous nature of phone and/or email values being associated with users we have adopted to this term to refer to either of these values.

note

A user can have many userIdentifiers of email and phones.

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.

Brand​

A brand is a customer entity that has a corresponding unique API key, name, and ID card image. Brands can issue, request and receive credentials to and from users.

note

A customer can have one to many brands. A brand can be assoicated with only one customer.

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 ID card image.

Components: Each brand has an associated parent customer. A customer can have one or more brands.

Customer​

A customer serves as a parent to brands and their corresponding API keys.

info

Our self service Dashboard is coming soon. It will allow you authenticate as a customer and create and manage 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.
brands.

note

Throughout our docs we use verbiage similar to a "customer must make an api request" or "a customer must check credentials" however we are actually referring to a "brand". This is because a brand is the entity that has a unique API key. So when we say "customer" we technically mean a customer using one of its brand API keys.

Example: ACME Bank is an Verified Inc. customer and has two brands: ACME Lending and ACME Savings.

Components: The admins of the customer can manage individual

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 settings.