Users

updated 1 year ago

In this article:

The User object
Create a User
Retrieve a User
Update attributes
Delete attribute
Delete device token
Track User event
Merge Users
Add User to Lists
Remove User from Lists
Change User type
Add Customer to Accounts
Remove Customer from an Account
Change Account Role
Get Account members
List Users
Archive a Customer or Account
Delete Customer or Account

The User Resource allows you to interact with your Customers and Accounts on Engage. Remember, an Account is also a Customer so these APIs also apply to creating and managing Accounts.

The User object

{
  "id": "5fc6477241fcec31a9548e98",
  "uid": "user_123",
  "uid_updateable": true,
  "first_name": "Akinyele",
  "last_name": "Jinadu",
  "number": null,
  "email": "[email protected]",
  "devices": [{ "token": "ExponentPushToken[4rawn2Obx9qjS9IHGeZaS1]", "platform": "android" }],
  "accounts": [{ "id": "633f7ff3d25cbeb22dde3fdf", "role": "Admin" }],
  "is_account": false,
  "member_count": null,
  "archived": true,
  "lists": [{ "id": "user_876", "subscribed": true }],
  "segments": [{ "id": "62bbdd2e5bfea4dca4834045", "suppressed": false }],
  "meta": {
    "plan": "pro",
    "age": 34
  },
  "created_at": "2021-01-12T05:24:39.062+00:00",
  "last_interaction": "2021-01-12T05:24:39.062+00:00",
  "stats": {
    "delivered": 6,
    "failed": 0,
    "opened": 3,
    "clicked": 0,
    "unique_opens": 3,
    "unique_clicks": 0
  }
}

id - An internal unique identifier for the user object.
uid - The user’s unique identifier in your application. This is what you will subsequently use for retrieving or updating the user.
first_name - The user’s first name if added.
last_name - The user’s last name if added.
number - The user’s number if added.
email - The user’s email.
is_account - If the user is an account or a customer. Learn more about Accounts.
member_count - The number of members if the user is an account. If the user is a customer, this will be null
devices - An array of objects with the properties token and platform containing the user’s last 5 device tokens and platform (android or ios) if synced.
lists - An array of objects with the properties id and subscribed containing the ID and subscription status of Lists the user belongs to.
segments - An array of objects with the properties id and suppressed containing the ID and suppression status of Segments the user belongs to. Suppressed means the user has unsubscribed from a broadcast sent to this segment and will no longer get new broadcasts.
accounts - An array of objects with the properties id and role containing the ID and role of Accounts the customer belongs to. If role does not exist, it will be null. Note that the id here is the uid of the Account entity.
archived - This will be true if the user is archived and false otherwise.
created_at - Date created if exists.
last_interaction - Date of last interaction. This could be the date of interaction with an engagement, when the user attribute was last updated, or when an event was last sent.
meta - Additional attributes attached to the user will be available as properties under meta.
stats - An object showing message stats for the user.

Important note on uid: If an ID wasn’t attached to the user data at creation (if the user was created through an integration for example), uid_updateable in the response object with the value true. This means you can make an update request to update the uid. Otherwise, you cannot update the uid.

Create a User

Adds a new user to your Engage account. Use this to sync customer data with Engage when there is a sign-up on your application.

Works with username authentication.

POST /v1/users

Parameters:

id - Required. An identifier for the user in your application. This is what is returned as uid in the response object. You can subsequently use it to update or retrieve the user. Ensure that whatever parameter you are using is unique across your user data. Don't use a user attribute that can later be updated by the user; email for example. We recommend you use the ID field of your user database table. It can only contain alphanumeric characters.
lists - Optional. An array of IDs of Lists you want to subscribe the user to. Opt-in confirmations are not sent for these even if enabled for the Lists.
accounts - Optional. An array of objects with id and optional role containing the ID of the account to add the user to and the user's role in this account. Note that the id here is the uid of the Account entity.
first_name - Optional. The user’s first name.
last_name - Optional. The user’s last name.
is_account - Optional. If true, the user will be created as an Account.
device_token - Optional. The user’s device token.
device_platform - Optional. The device platform. Supported values are android or ios.
number - Optional. The user’s phone number in international format.
email - Optional. The user’s email.
created_at - Optional. Date the user signed up on your application. Should be a valid date string.
meta - Optional. An object that can contain additional user attributes. The values can be a string, number, or boolean.

Example request data (Creating an account):

{
  "id": "user_144",
  "first_name": "Awesome Corp",
  "is_account": true,
  "email": "[email protected]",
  "meta": {
    "plan": "Pro"
  },
  "created_at": "2021-01-12T05:24:39.062+00:00"
}

Example request data (Creating a user and adding the user to an account):

{
  "id": "user_566",
  "first_name": "Akinyele",
  "last_name": "Jinadu",
  "email": "[email protected]",
  "accounts": [{
    "id": "user_144",
    "role": "Member"
  }],
  "meta": {
    "created_boards": 4,
    "last_login": "2021-08-10T01:12:53.000+00:00"
  }
}

The method returns the user object. If there is an error with any of the parameters, it will return a 400 HTTP status code with details in an error object.

Retrieve a User

GET /v1/users/{uid}

The method returns the user object.

{uid} - User ID of the Customer or Account.

Note that {uid} is the ID you supplied when creating the user (this is returned as uid in the response object) and not Engage's own internal ID (returned as id) in the object.

Update attributes

Updates user data and attributes. Use this to update user data changes like changes in plan, name, location, etc. on Engage. If the user doesn’t exist, this method creates the user. If the user does not have an ID attached before (i.e., if uid_updateable is true), the request uid is set as the new ID.

Works with username authentication if not updating the user’s email. Updating the user’s email requires full (key and secret) authentication.

PUT /v1/users/{uid}

{uid} - User ID of the Customer or Account.

Parameters can be any or more of the following:

first_name - The user’s first name.
last_name - The user’s last name.
number - The user’s phone number in international format.
is_account - Optional. If true, this converts the user to an account. If false and the entity is an account, this converts the entity to a user.
email - The user’s email. Requires both username and password authentication.
device_token - Optional. The user’s device token.
device_platform - Optional. The device platform. Supported values are android or ios.
created_at - Date the user signed up on your application. Should be a valid date string.
meta - An object containing additional user attributes to add or update. Should be a string, number, or boolean.

Example request data:

{
  "meta": {
    "plan": "custom",
    "coverage": 20 
  },
  "is_account": true,
  "created_at": "2021-01-12T05:24:39.062+00:00"
}

Example request data to set a user's device token:

{
  "device_token": "fcT_94-NQ2mJ9Ux-HrQyU_:APA91bHL38i0Ljpz0LEW36ahlTWfh6v~",
  "device_platform": "android"
}

The method returns the updated user object. If there is an error with any of the parameters, it will return a 400 HTTP status code with details in an error object.

Delete attribute

Deletes a non-standard user attribute. Use this endpoint to delete any user attribute that is not one of fitst_name, last_name, email, or number (any attribute in meta in the user object).

DELETE /v1/users/{uid}/attributes/{attribute}

{uid} - User ID of the Customer or Account.

{attribute} - The attribute to be deleted.

Delete device token

Deletes a device token from the profile. Use this endpoint to delete users' device tokens when they "log out" of your mobile application so that they do not continue to receive push notifications when they are logged out.

Works with username authentication.

DELETE /v1/users/{uid}/tokens/{token}

{uid} - User ID of the Customer or Account.

{token} - The device token.

Track User event

Adds user events to Engage. Use this to add user actions and events on your application to Engage. You can later segment your users based on these actions or events.

Works with username authentication.

POST /v1/users/{uid}/events

{uid} - User ID of the Customer or Account.

Parameters:

event - Required. The event title
value - Optional. The event value. Can be a string, number, or boolean
properties - Optional. An object containing additional event properties. Property values can only be a string, number, or boolean
timestamp - Optional. Timestamp of the event. If none is provided, the current time is used.

Example request data:

{
  "event": "Add to cart",
  "timestamp": "2020-05-30T09:30:10Z",
  "properties": {
    "product": "T123",
    "currency": "USD",
    "amount": 12.99
  }
}

Another example:

{
  "event": "Paid",
  "value": 49.99
}

Example response:

{ "status": "ok" }

If there is an error with any of the parameters, it will return a 400 HTTP status code with details in an error object.

Merge Users

Merge data for a User into another User.

POST /v1/users/merge

Parameters:

source - The ID of the user to merge
destination - The ID of the user source is being merged into

Add User to Lists

Adds a Customer or Account to one or more Lists.

POST /v1/users/{uid}/lists

Parameters:

lists - Array of IDs of the Lists to add the user to

Example request data:

{
  "lists": ["62d8e70910a25022c0fcb080", "62bc1d13d2c9906305a5dd38"]
}

The method returns the updated user object.

Remove User from Lists

Removes a Customer or Account from one or more Lists.

POST /v1/users/{uid}/lists

Parameters:

lists - Array of IDs of the Lists to remove the user from

Example request data:

{
  "lists": ["62d8e70910a25022c0fcb080", "62bc1d13d2c9906305a5dd38"]
}

The method returns the updated user object.

Change User type

Converts a Customer to an Account and vice-versa.

POST /v1/users/{uid}/convert

{uid} - User ID of the Customer or Account.

Parameters:

type - The entity type you want to convert to. Can be customer or account.

The method returns the updated user object.

Add Customer to Accounts

Adds Customer to Accounts.

POST /v1/users/{uid}/accounts

{uid} - User ID of the Customer.

Parameters:

accounts - An array of objects with the id of the Account the Customer should be added to and Customer role (optional) in the Account.

This example request data adds the Customer to the Account with the user ID (uid) user_123:

{
  "accounts": [{
    "id": "user_123"
  }]
}

This adds the Customer to the Account user_886 with the role admin:

{
  "accounts": [{
    "id": "user_123",
    "role": "admin"
  }]
}

The method returns the updated user object.

Remove Customer from an Account

DELETE /v1/users/{uid}/accounts/{aid}

uid - User ID of the Customer to remove.
aid - User ID of the Account to remove the Customer from.

Change Account Role

PUT /v1/users/{uid}/accounts/{aid}

Updates the role of the Customer in the Account or sets a new one if none exists.

uid - User ID of the Customer to remove.
aid - User ID of the Account to remove the Customer from.

Parameters:

role - The new role to set.

Example request:

{
  "role": "Bookkeeper"
}

Returns the new user object

Get Account members

Returns Customers that are members of an Account

GET /v1/users/{uid}/members

uid - User ID of the Account.

Returns a data array with members of the Account as user objects.

{
  "data": [
    {
      "id": "5fc6477241fcec31a9548e98",
      "uid": "user_123",
      "uid_updateable": true,
      "first_name": "Akinyele",
      "last_name": "Jinadu",
      "number": null,
      "email": "[email protected]",
      "member_count": null,
      "devices": [{ "token": "", "platform": "android" }],
      "lists": [{ "id": "633f7ff3d25cbeb22dde3fdf", "role": "Admin" }],
      "is_account": false,
      "accounts": [{ "id": "user_876", "subscribed": true }],
      "segments": [{ "id": "62bbdd2e5bfea4dca4834045", "suppressed": false }],
      "meta": {
        "plan": "pro",
        "age": 34
      },
      "created_at": "2021-01-12T05:24:39.062+00:00",
      "stats": {
        "delivered": 0,
        "failed": 0,
        "opened": 0,
        "clicked": 0,
        "unique_opens": 0,
        "unique_clicks": 0
      }
    }
  ]
}

List Users

GET /v1/users

Parameters:

limit - Optional. Number of users to return. Defaults to 10. Maximum of 30.
next_cursor - Optional. Pagination cursor for next dataset page. See Pagination.
previous_cursor - Optional. Pagination cursor for previous dataset page. See Pagination.
email - Optional. Use this to filter results to customers with this email.

Example response:

{
  "data": [
    {
      "id": "5fc6477241fcec31a9548e98",
      "uid": "user_123",
      "uid_updateable": true,
      "first_name": "Akinyele",
      "last_name": "Jinadu",
      "number": null,
      "email": "[email protected]",
      "member_count": null,
      "devices": [{ "token": "", "platform": "android" }],
      "lists": [{ "id": "633f7ff3d25cbeb22dde3fdf", "role": "Admin" }],
      "is_account": false,
      "accounts": [{ "id": "user_876", "subscribed": true }],
      "segments": [{ "id": "62bbdd2e5bfea4dca4834045", "suppressed": false }],
      "meta": {
        "plan": "pro",
        "age": 34
      },
      "created_at": "2021-01-12T05:24:39.062+00:00",
      "stats": {
        "delivered": 0,
        "failed": 0,
        "opened": 0,
        "clicked": 0,
        "unique_opens": 0,
        "unique_clicks": 0
      }
    }
  ],
  "next_cursor": "5fc6477241fcec31a9548e98"

Remember, you can only use one of next_cursor and previous_cursor. See pagination for more.

Archive a Customer or Account

POST /v1/users/{uid}/archive

This archives the user. The user will stop being active and all engagement and events for the user will also be stopped. All messages, logs, and related data will be preserved.

uid - User ID of the Customer or Account.

Response:

{
  "status": "ok"
}

Delete Customer or Account

DELETE /v1/users/{uid}

This completely deletes all the user data.

uid - User ID of the Customer or Account.

Example response:

{
  "status": "ok"
}

Was this article helpful?