Verifications

Note that for historical reasons the globaliD APIs refer to verifications as attestations. This will be fixed when the APIs are updated in the 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. Has valid email address is the verification, and the company that verified the email address is called the verifier. To perform this verification, the verifier may require the user to enter their email address, and send a message to that address containing a randomly-generated PIN code. When the user types in that PIN code, the verifier knows that the user is able to receive emails sent to that email address, and so the verifier is willing to stand behind the has valid email address verification. They do this by cryptographically signing the verification.

Verifications can contain personally identifiable information, or PII. The PII associated with a verification is always private, though the user may choose 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 supplied.

Note that verifications are always public: anybody can see the list of verifications associated with an identity, along with additional details like the identity of 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 PII is not -- despite having the above set of public verifications associated with an identity, the email address, phone number and facebook account ID that was used to generate those verifications is not revealed.

Note that some verifications may include public data. This is information which is deliberately made public, without revealing anything particularly identifiable about the identity. In the above example, the country associated with the phone number was 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 which verifications are recorded against them. The user initiates the verification by sending a verification request to the verifier, and providing whatever information the verifier may require. The verifier then signs the verification, indicating that they agree that the verification is valid. The user is then presented with all the results of the verification, including the PII and public data, and can choose whether or not to accept the verification. If the user accepts the verification, then they too sign the verification. Only if both the verifier and the user sign the verification will it be added to the 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 the API is updated.
  • 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 additional public information related to this verification.

Extra fields are returned about each verification, but these are the fields you are most likely to 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 the phone number verifications, you could 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:

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

will return all verifications signed by the owner after the given date and time.

Searching the Public Verification Database

Because verifications are public, it is also possible to search the public verification database, either for verifications associated with a given identity, or using any other search criteria you may wish to use. 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 the 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`