Terminology
Unum ID 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 Unum ID tech.
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:
The main terms to know are:
Main Terms​
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:
- type of the credential
- identifier for the person
- 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.
{
"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.unumid.co/jsonSchema/SsnCredential
"data": {
"email": "test@unumid.co"
}
}
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.+ More...credentials. It's created when a customer successfully checks if aExample: 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 Server SDK, and an app stores credentials using the Mobile SDK.A user is an individual in the Unum ID network. Each user has at least one phone or emails associated with them. They can have multiple of either.+ More...user has matching credentials, viaExample: Richard is a user in your account system and potentially of the Unum ID 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./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 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 customer checks if a user has the needed types of credentials by using /hasMatchingCredentials. If 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.
- type of the credential
- 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.+ More...brand(s) that issued the credentialExample: ACME Bank is an Unum ID 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.
- whether the credential is required or optional (defaults to required)
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 Unum ID, but here's an example of a request for a FirstName and LastName credential from the same issuing brand.
{
"uuid": "7c9a2365-a2a3-4fec-b446-99b61a074fa8",
"id": "854b9889-013d-40a2-93b9-68b9cf8d2540",
"createdAt": "1673470082199",
"updatedAt": "1673470082200",
"email": "test@unumid.co",
"phone": null,
"credentialRequests": [
{
"type": "SsnCredential",
"issuers": ["d14ca24c-5323-4b79-9dfa-6471b014d68c"],
"required": true
},
{
"type": "LastNameCredential",
"issuers": ["d14ca24c-5323-4b79-9dfa-6471b014d68c"],
"required": true
}
],
"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://unumid-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@unumid.co"]
}
}
User​
A user is an individual in the Unum ID 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.+ More...credentials). Each user has at least one phone number or email address associated with them. They can have multiple of either.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 Server SDK, and an app stores credentials using the Mobile SDK.
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 Unum ID specific user IDs.
Example: Richard is a user in your account system and potentially a user in the Unum ID 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@unumid.co"],
"phoneNumbers": []
}
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.
A customer can have one to many brands. A brand can be assoicated with only one customer.
Example: ACME Bank is an Unum ID 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.
Our self service Dashboard is coming soon. It will allow you authenticate as a customer and create and manage your
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 Unum ID customer and has two brands: ACME Lending and ACME Savings.
Components: The admins of the customer can manage individual