Skip to main content

API

Overview​

Integrating with Verified Inc. 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@verified.inc. 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 participants.

note

Postman documentation of this API can be found here.

Authentication​

Every request detailed below requires an Verified Inc. ApiKey as an Authorization Bearer token header, which is used to authenticate requests to the Verified Inc. cloud. For API keys to use for authentication please reach out to support@verified.inc. Our self service dashboard is coming soon!

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​

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-verifiedinc.com.
The base url for the Production API is https://core-api.verified.inc.

The wallet url for the Sandbox environment is https://wallet.sandbox-verifiedinc.com.
The wallet url for the Production environment is https://wallet.verified.inc.

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 OTP authentication messages during the final stages of development.

caution

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

Functionality​

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

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.
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 following the steps in the Issuance Guide.
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 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 following the steps in the Issuance Guide.
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 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 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 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 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 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 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 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 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:

  • 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; 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 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.
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.