The globaliD Identity Namespace API

The globaliD Identity Namespace is a master directory of all registered globaliD names. The namespace includes the following different types of names:

  • Names which are currently associated with an identity.
  • Names which have been used previously and are now released.
  • Names which are reserved and cannot be used unless the user proves that they are the legitimate owner of the name. These are used for company names, etc.

The most straightforward way to retrieve entries from the Identity Namespace is to use the /v2/identities endpoint, like this:

Request:

    GET /v2/identities

Response:

    HTTP/1.1 200 (OK)

    {
      "data": [
        { <IDENTITY> },
        { <IDENTITY> },
        ...
      ],
      "meta": {
         ...
      }
    }

As you can see, the v2/identities endpoint is public; you do not need to have an access token to call it. This makes the globaliD Identity Namespace accessible to anyone.

Each entry in the data array corresponds to a single identity. For each identity, the returned data will include the following:

  • gid_uuid: the UUID of this identity.
  • gid_name: the globalID name for this identity.
  • status: the current status of this identity (pending, in_use, released, or reserved).
  • type: the type of identity (individual, group or reserved).
  • created_at: the date and time at which this identity was created, in ISO-8601 format.
  • released_at: if this identity was released, the date and time at which the identity was released, in ISO-8601 format.
  • completed: whether or not this identity was completely filled in.
  • display_name: the user's display name for this identity.
  • description": The user's description for this identity.
  • display_image_url: the URL for this identity's profile image.

Additional fields will be returned, but these are the ones you are most likely to find useful.

Pagination

Because there are too many identities in the Identity Namespace to return all at once, the results returned by the /v2/identities endpoint are paginated. That is, only a small number of identities are returned at once, and you can call the endpoint again with extra parameters to return more identities in the namespace. By calling the endpoint repeatedly, you can scan through the entire Identity Namespace if you wish.

The returned meta object gives you information you need to scan repeatedly through various pages of identities. This object will include the following fields:

  • page is the page number of the results, starting at 1.
  • per_page is the number of identities returned in each page of results.
  • total is the total number of identities currently in the globaliD Identity Namespace.

To paginate the results, simply start by calling the /v2/identities 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:

`/v2/identities`
`/v2/identities?page=2`
`/v2/identities?page=3`
...

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

`/v2/identities?page=3&per_page=100`

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

Sorting the Results

By default, the identities are sorted by date, so that the oldest identities are returned first. To change this default sort order, you can use the sort parameter. The following values are supported:

* __date__: sort the identities by creation order.
* __gid_name__: sort the identities by globaliD name.
* __display_name__: sort the identities by display name.
* __region_name__: sort the identities by geographic region.
* __country_name__: sort the identities by country.
* __state_name__: sort the identities by state.
* __metro_name__: sort the identities by metro area.

In addition to choosing the field to sort against, you can use the sort_method parameter to choose whether to sort the identities in ascending or descending order. For example:

`/v2/identities?sort=display_name&sort_method=asc`

will return the identities sorted in ascending order of their display name.

Similarly:

`/v2/identities?sort=date&sort_method=desc`

will return the identities sorted in descending order of their creation date, so that the most recently created identities will be returned first.

Filtering

By supplying additional parameters to the /v2/identities endpoint, you can filter the results. Only those identities which match the given filter criteria will be returned. The following parameters allow you to set the filter criteria:

  • gid_name: only include identities with the given globaliD name. Note that this is an exact match; only those identities which have (or had) that exact name will be returned.
  • display_name: only include identities which have the given string in their display name. Partial matches are allowed.
  • description: only include identities which have the given string in their description. Partial matches are allowed.
  • type: only include identities of the given type.
  • status: only include identities with the given status.
  • region: only include identities with the given region code.
  • country: only include identities with the given country code.
  • state: only include identities with the given state code.
  • metro: only include identities with the given metro area code.
  • before: only include identities created before the given date. The value must be in ISO-8601 format.
  • after: only include identities created after the given date. The value must be in ISO-8601 format.