Users

The User object

{
  "id": "5fc6477241fcec31a9548e98",
  "uid": "[email protected]",
  "uid_updateable": true,
  "first_name": "Akinyele",
  "last_name": "Jinadu",
  "number": null,
  "email": "[email protected]",
  "meta": {
    "plan": "pro",
    "age": 34
  },
  "created_at": "2021-01-12T05:24:39.062+00:00"
}

• id - A unique internal identifier for the user object
• uid - The user's unique identifier in your application. If an id wasn't attached to the user data at creation (if the user was created through an integration for example), there will be an additional uid_updateable field with value true. This means you can make an update request to update the uid. Otherwise you cannot update the uid
• 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
• meta - Additional attributes attached to the user will be available as properties under meta
• created_at - Date created if exists

Retrieve a User

GET /users/{uid}

The method returns the user object.

Create a User

Adds a new user to your Engage account. Use this to sync user data with Engage when a user signs up on your application.

Works with username authentication.

POST /users

Parameters:

• id - Required. An identifier for the user in your application. You can subsequently use this to update or retrieve the user. Can only contain alhabets and numbers.
• 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.
• first_name - Optional. The user's first name
• last_name - Optional. The user's last name
• number - Optional. The user's phone number in international format
• email - Required. 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:

{
  "id": "u144",
  "first_name": "Akinyele",
  "last_name": "Jinadu",
  "email": "[email protected]",
  "meta": {
    "plan": "pro",
    "age": 34
  },
  "created_at": "2021-01-12T05:24:39.062+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.

Update User

Update user data and attributes. Use this to update user data changes like change 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 /users/{uid}

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
• email - The user's email. Requires both username and password authentication
• 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 string, number or boolean

Example request data:

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

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.

Add User events

Add 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 /users/{uid}/events

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 string, number or boolean
• timestamp - Optional. Timestamp of the event. If none 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.