The Verifications API

Note that for historical reasons the globaliD APIs refer to verifications as attestations. This will be fixed when the APIs are updated in future.

Understanding Verifications

A verification is a statement, made by a third party, about an identity. For example, a company may state that the identity has a valid email address. In this case, has valid email address is the verification, and the company that verifies the email address is called the verifier. To perform this verification, the verifier may require a user to submit their email addresses, to which the verifier will send a message containing a randomly-generated PIN. When the user confirms that PIN code, the verifier confirms that the user is able to receive emails at the submitted email address, and so the verifier is willing to stand behind the has valid email address verification and will cryptographically sign the verification.

Verifications can contain Personally Identifiable Information, or PII. The PII associated with a verification is always private to its associated user, though that user may provide explicit consent to share their PII with others. In the case of a has valid email address verification, the PII would be the email address that the user has supplied.

Note that verifications are always public: anybody can see the list of verifications associated with an identity, along with additional details like the verifier, the type of verification, when it was verified, etc. For example:

       Date/Time              Verification                  Verifier    Public Data
       -------------------    --------------------------    --------    -----------
       2019-01-19 11:26:52    Has valid phone number        Twilio      USA
       2019-01-19 12_03:40    Has valid email address       Mandrill
       2019-01-19 12:08:28    Has valid Facebook account    Facebook

While the verification itself is public, the underlying PII is not. If a user were to have the above-listed set of public verifications associated with their Identity, they can rest assured that the associated email address, phone number and Facebook account IDs used to generate those verifications will remain private unless the user grants explicit consent to share it with a specific third party or unless legally compelled.

Note that some verifications may include public data. This is information may be made public, without revealing anything particularly identifiable about the identity. In the above example, the country associated with the phone number is considered public data and is therefore included in the phone number verification. This helps people to know a bit more about the identity, without revealing any PII.

The user is always in control of the verifications attached to their identity. The user initiates a verification by sending a verification request to the verifier, and providing the required information. The verifier then signs the verification, thereby asserting that the verification is valid. The user sees the results of the verification, including both the PII and public data, and can choose whether or not to accept the verification. If the user accepts the verification, this is equivalent to their counter-signing the verification. Only if both the verifier and the user sign the verification, will it be attached to the user's identity.

Retrieving the Verifications for an Identity

If you have a valid access token associated with an identity, you can easily retrieve that identity's verifications by calling the GET /v1/attestations endpoint. For example:

Request:

    GET /v1/attestations
    BEARER <access_token>

Response:

    HTTP/1.1 200 OK

    [
      {
        "uuid": "...",
        "type": "phone_number",
        "attestor": "twilio",
        "attestor_signed_at": "...",
        "attestee_signed_at": "...",
        "public_data": "...",
        ...
      },
      ...
    ]

As you can see, the API endpoint returns an array of verifications. Each verification's object includes the following fields:

  • uuid: a UUID value uniquely identifying this verification.
  • type: a string identifying the type of verification.
  • attestor: the globaliD name of the verifier. Note that the name of this field will change when we update this API.
  • created_at: the date and time at which this verification was created, in ISO-8601 format.
  • updated_at: the date and time at which this verification was last updated, in ISO-8601 format.
  • attestor_signed_at: the date and time at which the verifier signed this verification, in ISO-8601 format.
  • attestee_signed_at: the date and time at which the user signed this verification, in ISO-8601 format.
  • public_data: an optional string containing any additional public information related to this verification.

Whiel additional fields may be returned about each verification, these are the fields that you will most likely find useful.

In addition to retrieving a complete list of all the verifications for an identity, you can filter the results by specifying two additional query-string parameters when making the API call:

* __fieldName__: the name of the field you wish to filter on.
* __fieldValue__: the value to compare the given field against.

For example, to retrieve only phone number verifications, you could use both fieldName and fieldValue to call:

`GET /v1/attestations?fieldName=type&fieldValue=phone_number`

As well as this type of simple filtering, you can also search for a range of values by appending one of gt, gte, lt or lte to the field name. For example, the following query will return all verifications signed by the owner after the specified date and time:

`GET /v1/attestations?fieldName=attestee_signed_atgt&fieldValue=2019-05-07T12:00:00`

Searching the Public Verification Database

Because verifications are public, it is also possible to search the globaliD public verification database, either for verifications associated with a given identity, or using any other desired search criteria. This can be done using the GET /v1/attestations/search API endpoint:

Request:

    GET /v1/attestations/search

Response:

    {
      "data": [
        {
          "uuid": "...",
          "attestee": "...",
          "attestee_uuid": "...",
          "attestor": "...",
          "type": "...",
          "created_at": "...",
          "updated_at": "...",
          "attestee_signed_at": "...",
          "attestor_signed_at": "...",
          "public_data": "...",
          ...
        },
        ...
      ],
      "meta": {
        "page": 1,
        "per_page": 50,
        "total": 11020
      }
    }

Note that this API endpoint is public; you do not need to have an access token to call this endpoint.

The data field contains an array holding a number of verifications. For each verification, the same information is returned as for the GET /v1/attestations API endpoint described in the previous section.

Pagination

Because there are too many verifications to return all at once, the results returned by the /v1/attestations/search endpoint are paginated. The meta object returned by the search results give you information about the current page of results, and you can call this endpoint again, with different parameters, to page through the entire list of verifications.

The meta object includes the following fields:

  • page is the page number of the results, starting at 1.
  • per_page is the number of verifications returned in each page of results.
  • total is the total number of verifications that match the current filter criteria.

To paginate the results, simply start by calling the /v1/attestations/search endpoint with no additional parameters. This returns the first page of results. You can then set the page query-string parameter to obtain further pages of results, like this:

`GET /v1/attestations/search`
`GET /v1/attestations/search?page=2`
`GET /v1/attestations/search?page=3`
...

You can also control how many identities are returned in each page of results by setting the per_page parameter. For example:

`GET /v1/attestations/search?page=3&per_page=100`

If you do not specify a per_page value, the API will use a default of 50 verifications per page. Do not set the per_page parameter too high, or you'll get timeouts on the HTTP response.

Filtering

You can filter the list of returned verifications using the fieldName and fieldValue query-string parameters, just like you can do for the GET /v1/attestations endpoint, described above. For example:

`GET /v1/attestations/search?fieldName=attestee&fieldValue=johnsmith`
`GET /v1/attestations/search?fieldName=type&fieldValue=phone_number`
`GET /v1/attestations/search?fieldName=created_atgt&fieldValue=2019-05-07T12:00:00`