Skip to main content

Terminology

Verified Inc. uses 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 Verified Inc. 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).

The main terms to know are:

Credential

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 using the /credentials API endpoint. 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, to issue a credential a company inputs three pieces of information:

  1. type of the credential
  2. identifier for the person
  3. data about the person

The data schema must match the corresponding credential type. Information on the data formats for each type can be found in the Data Schema section.

Atomic Credentials

Atomic credentials are the most basic credentials. They are the building blocks of more complex, "composite credentials". For example, an EmailCredential is an atomic credential.

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 Credentials

Composite credentials are credentials that are made up of multiple atomic credentials. For example, a FullNameCredential is made up of a FirstNameCredential and a LastNameCredential.

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.