Identify

Users sit at the core of Attuitive. Everything revolves them and generally all data relates to a user, or users. /identify provides a way to create and read them through identifiers.

Create a new user

POST /identify

Inserts a new user to the workspace.

Headers

Name	Value
Content-Type*	application/json
Authorization*	Bearer <token>

Body

Name	Type	Description
identifiers	object	An object containing identifying properties on the user.
traits	object	An object containing attributes of the user.

Response

200

{
  "id": "usr_XXX",
  "workspaceId": "ws_XXX",
  "identifiers": {
    // Identifiers provided on the request
  },
  "traits": {
    // Traits provided on the request
  },
  "createdAt": "2025-04-10T00:10:41.840Z",
  "updatedAt": null
}

400

Important: Fields with a * must be included in your request!

Get an existing user

GET /identify/:userId

Gets a user by their ID.

Headers

Name	Value
Content-Type*	application/json
Authorization*	Bearer <token>

Query

Name	Type	Description
:userId*	string	ID of the user. usr_[A-Za-z0-9]{16}

Response

200

{
  "id": "usr_XXX",
  "workspaceId": "ws_XXX",
  "identifiers": {
    ...
  },
  "traits": {
    ...
  },
  "createdAt": "2025-01-31T01:02:54.506Z",
  "updatedAt": "2025-04-09T10:06:06.813Z" // or null
}

400

404

Search users

GET/identify

Gets users matching the provided criteria. You can use limit & pageToken parameters to paginate results. See pagination for more details.

...param includes any number of additional parameters to filter identifiers based on. The user must match all parameters. Sending no parameters is the same as retrieving all users.

For example, to search by an email you would send: /identify?email=[e-mail]

TIP: Nested searches are also supported. If your identifiers includes {"name": {"first": "John", "last": "Doe"}} you can search for this by sending /identify?name.last=Doe.

Headers

Name	Value
Content-Type*	application/json
Authorization*	Bearer <token>

Query

Name	Type	Description
limit	number	Maximum number of results to return between 1 & 100. Defaults to 50.
pageToken	string	Token for the page to retrieve. Available on requests with multiple pages of results. Starts with ey...
...param	string	Parameters that should match a property in a user's identifiers e.g. phoneNumber or email

Important: It is expected you will encode the URL to escape specific characters. For example, if searching on a phone number, the + character should be encoded as %2B.

Response

200

{
  "data": [
    {
      "id": "usr_XXX",
      "workspaceId": "ws_XXX",
      "identifiers": {},
      "traits": {},
      "createdAt": "2025-01-31T01:02:54.506Z",
      "updatedAt": "2025-04-09T10:06:06.813Z"
    }
    ...
  ],
  "meta": {
    "limit": 50,
    "nextPageUrl": "/api/v1/identify?limit=50...", // or null
    "previousPageUrl": "/api/v1/identify?limit=50...", // or null
    "url": "/api/v1/identifiy?limit=50"
  }
}

400

Update a user

POST /identify/:userId

Updates an existing user's identifiers.

Updates use a append & merge approach. Properties will override an existing value if that key already and any new properties will be added.

You do not need to send existing properties when updating, these will continue to be persisted (or overwritten per the above section). To remove a value, send the key and a null value. For example to remove phoneNumber:

{
    ...
    "phoneNumber": null
}

Headers

Name	Value
Content-Type*	application/json
Authorization*	Bearer <token>

Query

Name	Type	Description
:userId*	string	ID of the user. usr_[A-Za-z0-9]{16}

Body

Name	Type	Description
identifiers	object	An object containing identifying properties on the user

Response

200

{
  "id": "usr_XXX",
  "workspaceId": "ws_XXX",
  "identifiers": {},
  "traits": {},
  "createdAt": "2025-04-05T00:10:41.840Z",
  "updatedAt": "2025-04-09T10:06:06.813Z"
}

400

Delete a user

DELETE /identify/:userId

Delete a user by ID.

Headers

Name	Value
Content-Type*	application/json
Authorization*	Bearer <token>

Query

Name	Type	Description
:userId*	string	ID of the user. usr_[A-Za-z0-9]{16}

Response

200

{
  "id": "usr_XXX",
  "workspaceId": "ws_XXX",
  "identifiers": {},
  "traits": {},
  "createdAt": "2025-04-05T00:10:41.840Z",
  "updatedAt": "2025-04-09T10:06:06.813Z"
}