how tos

Configure User Schema

You can use detailed user schema. You can configure all schema components over REST.

Let’s review available schema for a specific user. In this example: Querying Users, you can identify available schema properties for user [email protected].

content_copy COPY

curl -X GET \[email protected]%22 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'cache-control: no-cache'

Here’s the output:

content_copy COPY

  "schemas": [
  "Resources": [
      "accountStatus": "Active",
      "addresses": [
          "type": "work",
          "streetAddress": "6925 Hollywood Blvd",
          "locality": "Hollywood",
          "region": "CA",
          "postalCode": "90028",
          "country": "US",
          "formatted": "6925 Hollywood Blvd\nHollywood, CA 90028 USA",
          "primary": true
          "type": "home",
          "streetAddress": "2800 E Observatory Rd",
          "locality": "Los Angeles",
          "region": "CA",
          "postalCode": "90027",
          "country": "US",
          "formatted": "2800 E Observatory Rd\nLos Angeles, CA 90027 USA"
      "displayName": "Babs Jensen",
      "emails": [
          "value": "[email protected]",
          "type": "work",
          "primary": true,
          "verified": false
          "value": "[email protected]",
          "type": "home",
          "verified": false
      "id": "d0e7bf9e-a920-4d0e-a897-eb7fed8e3775",
      "ims": [],
      "locale": "en-US",
      "name": {
        "formatted": "Ms. Barbara J Jensen, III",
        "familyName": "Jensen",
        "givenName": "Barbara",
        "middleName": "Jane",
        "honorificPrefix": "Ms.",
        "honorificSuffix": "III"
      "nickName": "Babs",
      "phoneNumbers": [
          "value": "555-555-5555",
          "type": "work"
          "value": "555-555-4444",
          "type": "mobile"
      "preferences": {},
      "preferredLanguage": "en-US",
      "profileUrl": "",
      "timezone": "America/Los_Angeles",
      "title": "Master Carpenter",
      "userName": "[email protected]",
      "userType": "Customer",
      "x509Certificates": [],
      "meta": {
        "created": "2019-08-16T18:09:41.846043Z",
        "lastModified": "2019-08-16T18:09:41.846163Z"
  "totalResults": 1,
  "itemsPerPage": 1,
  "pagedResultsCookie": null

When a schema property is part of another property, both are shown. For example, the schema property for a street address is addresses.streetAddress.

User Schema Properties

These are the available schema properties for your users:

Property Description
accountStatus Active/Deactivated
addresses.type Allowed options: home, work
addresses.streetAddress Text
addresses.locality Text; normally used for town or city name
addresses.region Text; normally used for state or province
addresses.postalCode Text
addresses.formatted Generated from previous address properties
addresses.primary Boolean
custom Supports Custom User Attributes
displayName Human-readable name
emails.value Address
emails.type Allowed options: home, work
emails.primary .plain} Boolean
emails.verified Boolean
id Unique user identifier
ims Instant message address
locale Default language and location, such as en-US, per RFC-5646
name.formatted The full name, including all middle names, titles, and suffixes, when available
name.familyName Surname
name.givenName The given name of the user, or first name in most Western languages
name.middleName The middle name of the user, if available
name.honorificPrefix A prefix such as Mr., Ms., or Dr.
name.honorificSuffix A suffix such as Jr. III, or Esq.
nickname The preferred name for the user in casual situations
phoneNumbers.value Actual phone number
phoneNumbers.type Category, such as home or work
preferences TBD
preferredLanguage Default language; should be consistent with locale
profileUrl For the user’s online profile
timezone The user’s timezone, based on RFC 6557, such as America/Los_Angeles
title The user’s title, such as Prime Minister
userName Unique identifier for the user, typically for sign-ins
userType Based on the relationship between the user and organization, such as Employee, Customer, or Contractor
x509Certificates A list of certificates associated with the user
meta.created The time the user was created, in ISO 8601 format
meta.lastModifed The time user properties were last changed, in ISO 8601 format

alt text

Custom User Attributes

You can include custom user attributes. Here’s an example of a JSON blob that you could include in a REST call to create or modify a user:

content_copy COPY

"custom" : {
  "somethingOld" : "desiredValue",
  "somethingNew" : [
  "somethingBorrowed" : {
    "objectField" : "objectValue"
    "somethingBlue": true,
    "someNumber": 1000

You can set custom properties to any valid JSON data type. For example, in the noted JSON Blob, Express saves somethingBlue as a Boolean.

If you have questions email [email protected].