Public Profiles

Each identity in globaliD has a public profile which others can use. The user is able to set up their public profile by entering information or uploading an image to be displayed as part of the public profile. For example, the user might enter their display name and description, and also upload a new profile picture. All of this information will then be displayed on the user's public profile.

NOTE: in the globaliD app, the user's public profile also includes the verifications associated with the user's identity. This information can be obtained separately, as described in the section on verifications, below.

Anyone can view a public profile, but only the owner of the identity is able to change it. In this section, we will look at how to obtain the public profile for any identity, and how to change the profile for the identity associated with your access token.

Retrieving a Public Profile

To retrieve the public profile for an identity, you can call the GET /v1/identities/<gid_uuid> endpoint, replacing <gid_uuid> with the UUID of the desired identity. Assuming the identity exists, the body of the response will contain the identity's public profile:

    HTTP/1.1 200 OK

    {
      "gid_uuid": "d58f094f-6d28-4aa1-9bf9-afe517c396b9",
      "gid_name": "jsmith",
      "type": "individual",
      "status": "in_use",
      "created_at": "2019-04-03t21:19:12z",
      "released_at": null,
      "completed": true,
      "public_signing_key": "...",
      "public_encryption_key": "...",
      "purpose_personal": false,
      "purpose_professional": true,
      "purpose_recreational": false,
      "display_name": "John Smith",
      "description": "Professional carpenter based in San Jose, CA",
      "display_image_url": "...",
      "region_code": "NM",
      "region_name": "North America",
      "country_code": "USA",
      "country_name": "United States",
      "state_code": "USA-CA",
      "state_name": "California",
      "metro_code": "USA-CA-SFO",
      "metro_name": "San Francisco"
    }

If there is no identity with that UUID value, then a 404 (Not Found) error will be returned instead.

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

Changing an Identity's Display Name

To change the display name for an identity, call the POST /v1/identities/<gid_uuid>/updates endpoint. <gid_uuid> must be the UUID of the identity you want to change the name for, and the body of the request should contain the new display name you wish to use:

    {
      "display_name": "NEW_DISPLAY_NAME"
    }

Because this is a protected endpoint, you must supply an access token. Note that you can only change the display name for the identity that gave you the access token; if you try to change the details for any other identity, a 403 (Forbidden) error will be returned.

In globaliD, display names are moderated — that is, the new name will not be used until it has been checked to ensure that the name is not obscene or otherwise unacceptable. Thus, the POST /v1/identities/<gid_uuid>/updates endpoint creates a new request to change the display name. This request will be returned, along with a 201 (Accepted) response:

    HTTP/1.1 201 (Accepted)

    {
      "uuid": "...",
      "created_at": "2019-04-03t21:19:12z",
      "updated_at": "2019-04-03t21:19:12z",
      "gid_uuid": "...",
      "field_name": "display_name",
      "current_value": "OLD_DISPLAY_NAME",
      "new_value": "NEW_DISPLAY_NAME",
      "status": "pending"
    }

Each request has a UUID which uniquely identifies this update request. To see if the request has been processed, you can call the GET /v1/identities/<gid_uuid>/updates/<uuid> endpoint, supplying the gid_uuid of the identity and the UUID of the update request. The status value still be 'pending' if the update hasn't been processed yet, or it will be changed to either 'approved' or 'rejected' as appropriate. If the request was rejected, the returned object will have an additional field, moderation_response, which describes why the requested name was rejected.

Changing an Identity's Description

Because the description is also moderated, the process for updating an identity's description is very similar to the process for updating the name. You call the POST /v1/identities/<gid_uuid>/updates endpoint with the new description in the body of the request:

    {
      "description": "NEW_DESCRIPTION"
    }

The pending update request record will be returned:

    HTTP/1.1 201 (Accepted)

    {
      "uuid": "...",
      "created_at": "2019-04-03t21:19:12z",
      "updated_at": "2019-04-03t21:19:12z",
      "gid_uuid": "...",
      "field_name": "description",
      "current_value": "OLD_DESCRIPTION",
      "new_value": "NEW_DESCRIPTION",
      "status": "pending"
    }

You can then call the GET /v1/identities/<gid_uuid>/updates/<uuid> endpoint, supplying the gid_uuid of the identity and the UUID of the update request. The status field will change to 'approved' if the new description was accepted, or 'rejected' if the new description was unacceptable.

Changing an Identity's Profile Image

Each identity can have a number of images associated with it. These images are uploaded, and must pass moderation before they can be used. Once an image has been successfully moderated, it can be selected as the user's current profile image. This is the image which will be returned in the display_image_url field in the identity's public profile.

To upload a new image, call the POST /v1/identities/<gid_uuid>/images endpoint. The body of the request should include the image to upload, encoded in base-64 format. The encoded string should be passed in a parameter named data, like this:

  POST /v1/identities/<gid_uuid>/images
    BEARER <access_token>

  {
    data: "..."
  }

As usual, only the owner of the identity can make changes to it; attempting to upload an image for a different identity will result in a 403 (Forbidden) response.

When the image has been uploaded, the API endpoint will return information about the uploaded image:

    HTTP/1.1 201 (Accepted)

    {
      "uuid": "...",
      "created_at": "2019-04-03t21:19:12z",
      "updated_at": "2019-04-03t21:19:12z",
      "gid_uuid": "...",
      "url": "...",
      "status": "pending",
      "is_main_image": false
    }

As with the display name and description, the status field shows the moderation status for the image, and the uuid field gives a unique UUID for this uploaded image.

To check if the image has been moderated, you can call the GET /v1/identities/<gid_uuid>/images/<uuid> endpoint. This returns the updated information for the given image. If the image was approved, the status field will be changed to 'approved', and there will be a new field, approved_at, which contains the date and time at which the image was approved.

If the image was rejected, status will be set to 'rejected', the rejected_at field will be set to the date and time at which the image was rejected, and rejected_reason will hold a string explaining why the image was rejected.

Once the image has been accepted, you can choose to make it the main profile image for the identity. To do this, call the PUT /v1/identities/<gid_uuid>/images/<uuid> endpoint with the UUID of the image that you want to use as the main profile image. This endpoint will return a 200 (OK) response if the image was set to be the identity's main image. If the image has not yet been moderated, a 422 (unprocessable entity) response will be returned instead.

To obtain a list of all the images which have been uploaded for this identity, call the GET /v1/identities/<gid_uuid>/images endpoint. This will return an array of uploaded images:

    HTTP/1.1 200 (OK)

    {
      "data": [
        {
          "uuid": "...",
          "url": "...",
          "status": "accepted",
          "is_main_image": true,
          ...
        },
        {
          "uuid": "...",
          "url": "...",
          "status": "rejected",
          "is_main_image": false,
          ...
        },
        ...
      ]
    }

Finally, to remove an uploaded image, call the DELETE /v1/identities/<gid_uuid>/images/<uuid> endpoint with the UUID of the image you want to delete. If the image was successfully deleted, the API endpoint will return a status of 204 (No Content). If you attempt to delete the identity's main image, the API endpoint will respond with a status of 422 (unprocessable entity), as you must select a different main image before the image can be deleted.