Skip to main content

Users API

The users API is used to manage your customers within the Atomic Platform.

You can interact with the Users API using Insomnia (follow the Insomnia instructions) or curl.

You can find detailed specs and examples in the Atomic API spec for the Users API endpoint.

A credential role of either events or workbench is necessary to interact with the Users API. The Atomic API spec lists all requests with the required token in their name.

This guide lists a few request and response examples using curl. When using curl, you must set up your Authentication first.

List all customers (token: events)​

This request lists all customers in an environment. It is possible to add query parameters to limit the number of customers.

The example below returns only customers from a specific segment and limits the response size to 50.

curl -X GET "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/users?limit=50&segmentId=$SEGMENT_ID" \
    --header "Authorization: Bearer $TOKEN"

The response will look similar to the example below:

{
    "data": {
      "users": [
        {
          "id": "123",
          "preferences": {
            "timezone": "Pacific/Auckland",
            "notificationsEnabled": true
          },
          "preferencesUpdated": "2022-04-10T23:28:43.060Z",
          "created": "2022-01-20T01:55:58.643Z",
          "profile": {
            "name": "Sam Smith",
            "email": "sam.smith@example.com",
            "phone": "",
            "timezone": "Pacific/Auckland",
            "user_type": "test",
            "last_browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36",
            "last_seen_at": "2022-07-13T22:57:27.269Z",
            "first_seen_at": "2022-03-11T00:48:36.635Z",
            "shopping_interests": "music, art, nature",
            "last_android_device": "Android 10; SM-A015F",
            "last_android_seen_at": "2022-05-25T05:00:31Z",
            "last_browser_seen_at": "2022-06-03T03:43:00.524Z",
            "last_expired_card_at": "2022-05-24T04:56:35.479Z",
            "last_completed_card_at": "2022-07-13T22:57:27.269Z",
            "last_dismissed_card_at": "2022-05-23T04:56:16.784Z",
            "last_displayed_card_at": "2022-06-03T03:43:00.524Z",
            "last_published_card_at": "2022-06-03T03:42:58.727Z",
            "first_expired_card_at": "2022-05-24T04:56:35.479Z",
            "first_completed_card_at": "2022-07-13T22:57:27.269Z",
            "first_dismissed_card_at": "2022-05-23T04:56:16.784Z",
            "first_displayed_card_at": "2022-06-03T03:43:00.524Z",
            "first_published_card_at": "2022-06-03T03:42:58.727Z",
            "last_android_sdk_version": "1.0.3",
            "last_browser_sdk_version": "0.19.2"
          },
          "segments": {
              "XQ19azQe": {
                  "active": true
              }
          },
          ...
        }
      ]
    }
  }

Create custom profile fields (token: workbench)​

Customer records can have custom fields. Creating custom fields can be done in the workbench (as described in the Customers guide) or via the API.


CUSTOM_FIELDS_PAYLOAD='[{
    "name": "fname",
    "label": "First name"
    "type" : "text" #type can be text or date
}]'

curl -X PUT "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/users/custom-profile-fields" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data $CUSTOM_FIELDS_PAYLOAD

The response will list all custom fields in that environment and will look similar to the example below:

{"data":[{"name":"fname","type":"text","label":"First Name"},{"name":"lname","type":"text","label":"Last Name"}]}

Create new or update existing customers (token: events)​

When creating a new customer, the only mandatory parameter that needs to be passed is the id field in the payload.

In this example, we will also add some other profile fields (name and email), and the custom fields (fname and lname) we created in the previous section.


NEW_CUSTOMER_PAYLOAD='{
  "users": [
    {
      "id": "userid-123",
      "profile": {
        "name": "Sam Smith",
        "email": "Sam.Smith@example.com",
        "fname": "Sam",
        "lname": "Smith"
      }
    }
  ]
}'

curl -X POST "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/users" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data $NEW_CUSTOMER_PAYLOAD

The response contains the user record for the newly created customer and will look similar to the example below:

{"data":{"users":[{"id":"userid-123","profile":{"name":"Sam Smith","email":"Sam.Smith@example.com","fname":"Sam","lname":"Smith"}}]}}

Pass customer data via auth token​

Rather than hitting the Users API separately to create or update customers, you can pass information with the auth token in the SDKs. The following customer fields can be updated using this approach:

  • profile fields (external id, name, email, phone, city, country, region)
  • custom fields

You will need to have already set up SDK authentication and added your public key to the workbench. You can read how to do this in the SDK authentication guide.

  1. Navigate to Configuration > SDK > API keys. Alternatively, open the command palette and type 'API key'.
  2. Click on the name of the API key used to sign the JWT in your SDK.
  3. Note the box at the bottom: Map JWT claims data to existing profile fields.
    The link in this box takes you to an overview of existing custom fields. This view also allows you to create any additional fields you need.
  4. This is where you map the fields you wish to add. e.g. {"city":"city", "ph":"phone"}. This maps the token data to custom fields. i.e. 'ph' in the token is mapped to the Atomic customer field 'phone'.
    In these key-value pairs, the key (on the left) is the token field, and the value (on the right) is the Atomic customer field.

Watch the video below for a more detailed explanation of how this works and how this feature can be used to make even more use of your Atomic implementation:

Updating customer profiles via JWT claim-mapping in Atomic.io

Delete customers (token: events)​

Atomic provides an endpoint that will remove all identifiable traces of the provided customers from our system. This is a scheduled job and may take time to happen.

To delete one or more customers, you provide the user id's like the example below:


USER_IDS_TO_BE_DELETED='{
  "data": ["userid-123", "userid-456"]
}'

curl -X PUT "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/delete-users" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data $USER_IDS_TO_BE_DELETED
}

The response lists all customers that have been scheduled for removal and will look similar to the example below:

{"userIds":["userid-123","userid-456"]}
Last updated on