Skip to main content

Issuance Guide

Time to read: 5 min

Time to implement: 2-4 hours

Overview​

Verified Inc. enables brands to provider their users with best in class onboarding with partners. This particular guide only focuses on how and why to become 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 that issues Verified Inc.
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.

By issuing credentials your brand can unlock Free IDV. Please see the Use Case section for more information.

tip

You will need an API key and an email and/or phone for each user. Below is a valid API Key and URL for your initial usage along with suggested test email and phone values.

If you use these suggested test email and/or phone values you can authenticate to the wallet using those values, i.e. richard@piedpiper.net, using a static OTP of 111111.

Sandbox API Key
yVg3LEnF08y0MDmpHcPxB+sZWFcDARmPRKdY2M906ng=
Sandbox URL
https://core-api.sandbox-verifiedinc.com
Sandbox User Email
richard@piedpiper.net
Sandbox User Phone
+10123456789
Sandbox User Wallet Authentication OTP
111111

Motivations​

If you issue digital ID cards, Verified Inc. may be willing to cover your identity verification costs in order to create a truly win-win-win scenario for you, your partners, and your users. Simply put, you issue a digital ID card to any of your users (new or existing) with verified identity data, and we pay you for it. The core motivations for such an arrangement are multifaceted:

  1. You get your identity verification costs covered with any provider(s) of your choosing.
  2. You get a new revenue stream when the user uses your verified data to onboard with 1-Click.
  3. Your users get to enjoy 1-click onboarding with any of your partners or other third parties that accept your verified data, which also means increased brand awareness through a delightful UX.
  4. Verified Inc. gets more identity into the identity network, which is why we are willing to subsidize your costs.

UX Strategies​

There are many user experiences that can be implemented to seamlessly issue credentials to your users. Below are just a few recommendations with an accompanying demo of each.

  • Next User Sign In
    Demo of Next User Sign In

    Richard is an existing, verified Hooli user. The next time he signs in, Hooli asks him if he wants to activate his Hooli digital ID card. When he clicks the Activate button, Hooli issues the card, and Verified Inc. reimburses Hooli for the cost of the identity verification performed by Hooli for Richard.

  • After User Sign Up
    Demo of After User Sign Up

    Richard has just completed Hooli account sign up which included identity verification via a third party service of Hooli's choosing. In the terms and service section Richard agrees to being issued an Hooli branded Verified Inc. digital ID card. Hooli issues the card with the verified identity data and Verified Inc. reimburses Hooli for the cost of the identity verification performed by Hooli for Richard.

  • Marketing Email
    Demo of Marketing Email

    Richard is an existing, verified Hooli user. He receives a promotional email from Hooli which encourages him to accept a digital Verified Inc. card. Upon clicking the link and being directed to the app Hooli confirms with him he wants to activate his Hooli digital ID card. When he clicks the Activate button, Hooli issues the card, and Verified Inc. reimburses Hooli for the cost of the identity verification performed by Hooli for Richard.

  • In App Offer
    Demo of In App Offer

    Richard is an existing, verified Hooli user. Upon signing into the app he notices an in app offer which encourages him to accept a digital Verified Inc. card. When he clicks the Activate button, Hooli issues the card, and Verified Inc. reimburses Hooli for the cost of the identity verification performed by Hooli for Richard.

Implementation​

The implementation goal is to 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. When you do, Verified Inc. will pay you according to your contract. The steps for completing the implementation are as follows:

You must get user consent. Ask the user if they want to activate their digital ID card (from your brand), and include Verified Inc. legal language:

By clicking the button below, you agree to Verified Inc.’s Terms of Use and direct YOUR_COMPANY_NAME to share your personal information with Verified Inc. to provide its digital ID card services, in accordance with its Privacy Policy.

"Terms of Use" should be underlined or colored and hyperlinked to https://www.verified.inc/legal/terms-of-use. "Privacy Policy" should be underlined or colored and hyperlinked to https://www.verified.inc/legal/privacy-policy.

info

You must obtain user consent before issuing credentials. Not doing so violates our terms and will prevent us from paying you for issuing credentials.

2. Issue Credentials​

Call /credentials with the user's verified email and/or phone and one or more credentials. For each credential, include a type and data in accordance with one of our schemas.

If we don't have a schema that suits your needs, email us and we'll make one for you.

For example, if you have a verified Social Security Number (SSN) and a Full Name for a user, you can issue them a SsnCredential and FullNameCredential. Just call the /credentials endpoint with the user's email and/or phone, the SsnCredential and FullNameCredential type, and the SSN and Full Name data:

Example Issue Credentials Request Body
{
  "email": "test@example.com",
  "phone": "+10123456789",
  "trackingId": "moc.elpmaxe@tset", // optional; your preferred tracking id used for credential usage attribution
  "credentials": [
    {
      "type": "SsnCredential",
      // based on the properties attribute of the schema
      "data": {
        "ssn": "111223333"
      },
      "expirationDate": 1893484800
    },
    {
      "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"
          }
        }
      ]
    }
  ]
}

Format the credential data according to the properties attribute of the credential schema. In this case, the schema is for a SsnCredential which can found found at https://schema.verified.inc/jsonSchema/SsnCredential and for a FullNameCredential which can be found at https://schema.verified.inc/jsonSchema/FullNameCredential.

More information about credential schemas can be found in the Schema section.

Tracking Identifier​

The optional trackingId attribute is optional in most cases, however if you are operating a promotion with the partner issuance flow it maybe helpful for tracking attribution.

✅ You're done!

Example & Demo​

Please feel free to refer to the open source Hooli demo web app which demonstrates an example implementation of the Free IDV offering. More information, including mobile demo applications can also be found under the Hooli Demo section.

Partner Issuance​

First Time Issuance​

Some issuance calls can be made with a particular partner in mind, i.e. in a promotional flow. In these cases you have already authenticated the user and would like to issue them credentials for a particular partner.

To do this, you can provide your partner's static partnerUuid to the issue /credentials call. The resulting api response body will contain a url field if conditions related 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 are satisfied. If present, you should redirect the user there.

tip

You can check 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 by calling /credentialsRequests/{partnerUuid}.

This url ultimately redirects the user to a page of the partners choosing. However, the url first directs the user to the Verified Inc. wallet where they explicity consent to the data share to the partner.

Example Issue Credentials Response
{
    "email": "richard@pipedpiper.net",
    "url": "https://wallet.verifiedinc.com/request/dfb39a34-ea90-4976-a230-12005c0ddfbb?email=richard%40pipedpiper.net&redirectUrl=https%3A%2F%2Fkredita-web.demo.sandbox-verifiedinc.co%2Fregister&jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9.eyJicmFuZFV1aWQiOiI0NDFhNmI2Yy03YjQ5LTRkNTUtYWExMC01ZWMzOWRlNjdjNjEiLCJjcmVkZW50aWFsSWRzIjpbImViNzNiYTBjLTY0MWUtNDc4Zi04ZGJkLWM4NjgzMjU2YWNmMSJdLCJ0aWVyIjoxMCwiaWF0IjoxNjg0NTE2NDU4LCJleHAiOjE2ODQ1MTcwNTgsImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3QiLCJzdWIiOiJjNThkYzc2MS1hNDhjLTRmYWQtOGUyMy1iYmIwMDBjYWIyNTUiLCJqdGkiOiJjYmNmYmVlZC01ZGY1LTQ5YjItOGRlNC1jMzFjYjA5MmYzNTUifQ.QSqg2kNTfnlh42qh0VYhT0Wz_ogSNMTfudNaDQyVIiQ",
    "credentials": [{...},{...}]
}
info

This use case of issuing credentials for a particular partner is by no means required. The key difference in this flow is the user can skip authenticating with the Verified Inc wallet to share their data.

note

To make this a very streamlined experience for the user, we include a pre-authenticated JWT in the url which will automatically log them into the Verified Inc. wallet. This JWT is valid for 5 minutes and is limited in scope to only the credentials you just issued the user.

If the user does not complete the partner onboarding process within 5 minutes, they can still complete it at a later point now that they have the credentials, but we will require them to authenticate into the Verified Inc. wallet to do so.

If this is an experience you would like to provide for your partners immediately after credential issuance, please let us know so we can provide you with your partner's static UUID and enable this capability for 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.

Already Issued Credentials​

If you have already issued credentials to a user, then /hasMatchingCredentials can be called with partnerUuid. In this case, if Verified Inc. can confirm the user has credentials to satisfy the pre-defined partner credential request(s), then the resulting API response body will contain a url which you should redirect the user to. Just as in the case of the /credentials response, this url ultimately redirects the user to a page of the partner's choosing. However, the url first directs the user to the Verified Inc. wallet, where they explicitly consent to share credential data with the partner.

Example Check has Matching Credentials Response
{
  "match": "true",
  "url": "https://wallet.verifiedinc.com/request/dfb39a34-ea90-4976-a230-12005c0ddfbb?email=richard%40pipedpiper.net&redirectUrl=https%3A%2F%2Fkredita-web.demo.sandbox-verifiedinc.co%2Fregister&jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9.eyJicmFuZFV1aWQiOiI0NDFhNmI2Yy03YjQ5LTRkNTUtYWExMC01ZWMzOWRlNjdjNjEiLCJjcmVkZW50aWFsSWRzIjpbImViNzNiYTBjLTY0MWUtNDc4Zi04ZGJkLWM4NjgzMjU2YWNmMSJdLCJ0aWVyIjoxMCwiaWF0IjoxNjg0NTE2NDU4LCJleHAiOjE2ODQ1MTcwNTgsImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3QiLCJzdWIiOiJjNThkYzc2MS1hNDhjLTRmYWQtOGUyMy1iYmIwMDBjYWIyNTUiLCJqdGkiOiJjYmNmYmVlZC01ZGY1LTQ5YjItOGRlNC1jMzFjYjA5MmYzNTUifQ.QSqg2kNTfnlh42qh0VYhT0Wz_ogSNMTfudNaDQyVIiQ"
}

We recommend that you first check internally whether you've issued credentials to a user. If you have, then call /hasMatchingCredentials to confirm with Verified Inc. that the user still has these credentials. (There are cases where the user will not still have the credentials, for example if they went directly to their Verified Inc. wallet to delete them.) If the user does not still have the credentials, you can issue them new credentials, as long as you have their consent. As a precaution, you can also patch existing credentials with a status of revoked to ensure that only the new credentials you issue will be valid for use.