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

{
  "status": 400,
  "message": "Invalid identifiers",
  "moreInfo": "The provided identifiers should be a valid JSON object."
}

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

{
  "status": 400,
  "message": "Invalid user ID",
  "moreInfo": "The provided user ID is not in the correct format of 'usr_[A-Za-z0-9]{16}'."
}

404

{
  "status": 404,
  "message": "User with ID not found",
  "moreInfo": "A user with the provided ID does not exist."
}

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

{
  "status": 400,
  "message": "Limit parameter out of range",
  "moreInfo": "The 'limit' parameter provided should be between 1 and 100."
}

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

{
  "status": 400,
  "message": "Invalid identifiers",
  "moreInfo": "The provided identifiers should be a valid JSON object."
}

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"
}