API at a glance

Description: This API adds multiple users to a custom user list in a single request. Maximum 25 users per API call in sync mode, or up to 500 users per API call in async mode using the async query parameter.

Authorization: Basic encoded_value

Things to know before you start

• List ID required: Obtain the list ID from the Create empty list response or from the Blueshift dashboard.

You can find the list ID in the URL when viewing a custom user list in the Blueshift app. For example, if you open a custom user list in the Blueshift app, its URL looks like https://app.getblueshift.com/dashboard#/app/custom_list/<LIST_ID>/edit.

• Batch limit: Maximum 25 users per API call in sync mode. Set the async query parameter to true to send up to 500 users per API call.
• Async mode: In async mode, the request runs in the background after it is accepted. The response format is the same in both modes.
• Identifier types: Use email or customer_id to identify users.

• Use case: Best for adding multiple users to custom lists, bulk list updates, and managing targeted audience segments.

Request parameters

Example requests & responses

{
  "identifier_key": "email",
  "identifier_values": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

{
  "status": "ok",
  "errors": []
}

{
  "identifier_key": "customer_id",
  "identifier_values": [
    "23a1fae1-2103-4e18-b58c-9db0ea9f7bf7",
    "35b2gbf2-3214-5f29-c69d-0ec1fb0g8cg8",
    "46c3hcg3-4325-6g30-d70e-1fd2gc1h9dh9"
  ]
}

{
  "status": "ok",
  "errors": []
}

curl --request PUT \
     --url 'https://api.getblueshift.com/api/v1/custom_user_lists/bulk_add_users_to_list/{list_id}?async=true' \
     --header 'accept: application/json' \
     --header 'authorization: Basic <encoded_api_key>' \
     --header 'content-type: application/json' \
     --data '{
  "identifier_key": "email",
  "identifier_values": [
    "[email protected]",
    "[email protected]"
  ]
}'

{
  "status": "ok",
  "errors": []
}

📘

List updates after an async request

After an async request, the list can take a few minutes to update. To get the updated user count, go to the Customer Lists page, click the more options (...) icon for the list, and click Refresh.

{
  "error": "You can add maximum 25 users in one api call"
}

{
  "error": "You can add maximum 500 users in one async api call"
}