Skip to main content

Identifying users

Overview​

In order for Dopt to power experiences for your users, Dopt needs to be aware of those users and their properties.

Developers will need to identify users to Dopt using the Dopt users API.

We support two approaches for sending your user data to Dopt: individual identification and batch identification. In both cases, we manage your user data via upsertion i.e. we provide a single set of APIs for both creating new users in Dopt and updating existing users.

Individual identification​

You can use the users API to send us data for a single user. If you've used a Customer Data Platform (CDP) like Segment before, this will be familiar to you. In practice, you might integrate individual identification code into your users CRUD handler.

API reference →

curl 'https://users.dopt.com/identify' \
 -X POST \
 -H 'Content-Type: application/json' \
 -H 'x-api-key:$USERS_API_KEY' \
 -d '{
  "identifier": "123456789",
  "properties": {
    "name": "Joe McKenney",
    "email": "joe@dopt.com",
    "city": "Oakland"
  }
}'

We recommend you use a unique user identifier that won’t change for your identifier, such as a database ID from your organization’s internal systems.

info

Nested user properties are currently unsupported, but will still be accepted as valid values.

info

When you use the users API in the browser the source’s write key is public because it runs in a user’s browser and can be accessed using the browser’s developer tools. You can also call /identify via the server which collects data from a server-based installation and isn't accessible to the user.

caution

We have deprecated the /identify/{:identifier:} API in favor of the above API. The previous API specified the identifier in the request URL while the current API specifies the identifier in the request body. We will continue to support the previous API, but we recommend that you migrate to using the current API.

Batch identification​

Many users have likely been created in your system before Dopt was integrated. To tell us about those users we offer a batch identify endpoint in the users API that allows you to send us data for many users at once. This endpoint allows you to identify up to 100 users at a time.

API reference →

curl 'https://users.dopt.com/identify/batch' \
 -X POST \
 -H 'Content-Type: application/json' \
 -H 'x-api-key:$USERS_API_KEY' \
 -d '[
  {
    "identifier": "123456789",
    "properties": {
      "name": "Joe McKenney",
      "email": "joe@dopt.com",
      "city": "Oakland"
    }
  },
  {
    "identifier": "987654321",
    "properties": {
      "name": "Alon Bartur",
      "email": "alon@dopt.com",
      "city": "Oakland"
    }
  }
]'
caution

We've removed support for the previous /identify/bulk API in favor of the current /identify/batch API above. The current API allows for greater flexibility while being less error prone during user specification.

Updating user properties​

You can update user properties by using the users API. Call the users API with a user identifier and new or updated user properties. The user properties will be updated via upsertion: if the user property doesn’t exist, it will be created. If it does exist, it will be updated.

Associating users with a group​

You can associate the currently identified user with a group by calling

curl 'https://users.dopt.com/identify' \
 -X POST \
 -H 'Content-Type: application/json' \
 -H 'x-api-key:$USERS_API_KEY' \
 -d '{
  "identifier": "2a845972-4cde-4cb4-ba14-5cb2fc15ec4c",
  "properties": {
    "name": "Evelyn Reichert",
    "email": "evelyn@example.com",
  },
  "groups": [
    {
      "identifier": "akh3j4-e14cd-cd51-33cabedac8c8a",
      "properties": {
        "name": "Acme co"
      }
    }
  ]
}'