Users

Introduction

The user object contains first and last name, primary email and (optional) external metadata.
It may also hold a reference to a superior, used for report approval.

Custom fields may be specified, as a hash/dictionary of key/value pairs (strings only).
Typically used for Cost-Center, Project IDs or similar.

Complete example

{
  "data": {
    "id": "a4ca67716af128ba14bae35f0cc1a6f7",
    "type": "users",
    "attributes": {
      "first_name": "Grace",
      "last_name": "Hopper",
      "primary_email": "[email protected]",
      "role": "finance",
      "external_identifier": "acme-employee-010",
      "external_metadata": {
        "department": "acme-finance",
        "pension_plan": "premium"
      },
      "custom_fields": {
        "project": "acme-pr-campaign-001",
        "cost_center": "computing-revolution"
      }
    },
    "relationships": {
      "branch": {
        "data": {
          "type": "branches",
          "id": "a1dc46dba8a15acebb217749e3b73ac7"
        }
      },
      "superior": {
        "data": {
          "type": "users",
          "id": "51ce875242e653b2b6f090d1a0b6f5df"
        }
      },
      "delegates": {
        "data": [
          {
            "type": "users",
            "id": "5844a15e76563fedd11840fd6f40ea7b"
          }
        ]
      }
    }
  }
}

📘
Unrecognized Custom Fields
Unrecognized keys and values will be silently ignored when creating or updating users.
This will occur if there is no custom field with the given key (or in the case of pre-defined values a corresponding, pre-existing value).
To detect if keys were ignored the client can diff the hash it sent with the response.