Skip to main content

API

Before you begin: You need to be registered as an Unum ID customer to create a brand API key. You can register zero to many brands, depending on your use case. For API keys to use for authentication please reach out to support@unumid.co. Our self service dashboard is coming soon!

note

Postman documentation of this API can be found here.

Overview

Integrating with Unum ID can be completed with minimal effort by following this documentation. That said, if you desire further assistance, please do not hesitate to reach out to support@unumid.co. Once complete, you will be able to boast 1-click (or free KYC) onboarding and secure additional revenue streams for any user data shared with other network partcipants.

Authentication

Every request detailed below requires an Unum ID ApiKey as an Authorization Bearer token header, which is used to authenticate requests to the Unum ID cloud.

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 Unum ID API. Your clients should never have direct access to your Unum ID API key.

Environments

Upon the ApiKey creation you will receive one for each environment: Sandbox and Production. We encourage that all integration work be done against the Sandbox environment.

The base url for the Sandbox API is https://core-api.sandbox-unumid.co.
The base url for the Production API is https://core-api.unumid.co.

Functionality

The Unum ID API lets your company partcipate in the Unum ID identity data network. You can use the API methods to check if

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.
Example: 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.
users have credentials of interest, create
A request (or credentials 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 for and retrieve user data in the form 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 using the Server SDK, and an app stores credentials using the Mobile SDK.
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 using the Server SDK, and an app stores credentials using the Mobile SDK.
credentials of user data, and update previously issued credential statuses (e.g. to invalidate a credential)

Jump to:


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 using the Server SDK, and an app stores credentials using the Mobile SDK.
credentials. If so, a
A request (or credentials 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 Unum ID network. Each user has at least one phone or emails associated with them. They can have multiple of either.
Example: 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.
user's consent to share the data.

Method: POST
Path: /hasMatchingCredentials

You need to provide:

  1. credential request(s)

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 using the Server SDK, and an app stores credentials using the Mobile SDK.
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 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.
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; // if credential is required (default is true)
}

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.

  1. user's email or phone
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

{
credentialRequests: CredentialRequest[], // a list of one or more CredentialRequest objects. Encodes which credentials are being asked for.
email?: string, // user's email address; optional if phone is provided
phone?: string, // user's phone number; optional if email is provided
}

Response Body:

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

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 using the Server SDK, and an app stores credentials using the Mobile SDK.
credential data shared by a
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.
Example: 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.
user.

Method: GET
Path: /sharedCredentials/{uuid}

When a

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.
Example: 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.
user responds to a
A request (or credentials 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 uuid 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 using the Server SDK, and an app stores credentials using the Mobile SDK.
credentials data related to the
A request (or credentials 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:

  1. the uuid that was returned after redirecting the user to the url 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 data map 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 using the Server SDK, and an app stores credentials using the Mobile SDK.
credentials to a
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.
Example: 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.
user.

Method: POST
Path: /credentials

You need to provide:

  1. Credentials data array
  2. Either a phone and/or email attribute

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

An exmaple Credentials object is below:

Credentials
{
"type": string, // credential type
"data": Map<string, any> // credential data map that matches the credential type's JSON Schema definition
"expirationDate?": number // when the expires as a milliseconds since epoch unix timestamp; optional
}
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 Update Credentials coming soon.

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 Unum ID network. Each user has at least one phone or emails associated with them. They can have multiple of either.
Example: 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.
user agrees to share with.

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; optional if email is provided
}

Response Body:

Credential[]
[{
"id": string, // credential id
"type": string, // credential type
"email": string, // user's email address if provided
"phone": string, // user's phone number if provided
"data": Map<string, any> // credential data map 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 expires as a milliseconds since epoch unix timestamp; optional
}]

The created and issued credentials 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. If you only store the credential id, it'll be very difficult to later remember what the id corresponds to.