Layer associates an Identity object with each user. This allows you to include information, including names and avatars, with each user. Layer will automatically sync this information to clients so it will be available when messages and conversations are rendered.

Clients can register an initial Identity object in the Identity Token. The Users Endpoints exposes endpoints to update Identity information or create new Identity objects.

Name Type Length Description
id string 128 Internal ID used by layer to identify the user
url string 128 URL for operating upon this Identity
user_id string 128 ID used within your application’s user management system
display_name string 128 Name to show on-screen for user
avatar_url string 1024 URL to the user’s profile photo
first_name string 128 First name for user
last_name string 128 Last name for user
phone_number string 32 Phone number for user
email_address string 255 Email for user
identity_type string 4 user or bot
public_key string - Public encryption key for end-to-end encryption
metadata object 16 keys Arbitrary key-value set. Values must be strings, nested objects are not supported.

Every field is optional and may be blank, except display_name which is required by some endpoints.

The following JSON represents an Identity object, and may be referred to as Identity throughout this document:

  "id": "layer:///identities/FrodoDodo",
  "url": "",
  "user_id": "FrodoDodo",
  "display_name": "Frodo the Dodo",
  "avatar_url": "",
  "first_name": "Frodo",
  "last_name": "Baggins",
  "phone_number": "13791379137",
  "email_address": "",
  "identity_type": "user",
  "public_key": "ABCDEF",
  "metadata": {
    "level": "35",
    "race": "Dodo"