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.

Detailed specs and examples can be found in the Atomic API spec for the Users API endpoint.

A credential role of either events or workbench is required 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'll need to 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 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",
            "last_stream_displayed_at": "2022-06-03T03:42:52.365Z",
            "first_stream_displayed_at": "2022-06-03T03:42:52.365Z"
          },
          "segments": {
              "XQ19azQe": {
                  "active": true
              }
          },
          ...
        }
      ]
    }
  }

Create custom profile fields (token: workbench)​

It is possible for customer records to have custom fields. To do this, you need to:

  1. Create the custom fields (in the Workbench or via an API request).
  2. Create or update a customer record with the new custom field.

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

Delete customers (token: events)​

Atomic provides an endpoint which will remove all identifiable trace of the provided customers from our system. This is a scheduled job and may not happen immediately.

To delete one or more customers, you simply 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