Objective
This article explains how to programmatically query user and account data using the Segment Profile API. By following these steps, you will learn how to generate an access token, identify a user's external ID, and execute a query to retrieve user traits, events, and identifiers for your real-time personalization or data enrichment workflows.
Product
Twilio Segment
Environment
Segment Console
User Account Permission/Role(s) Required
Workspace Owner or a user role with permissions to manage Unify settings and API access.
Procedure
- Log in to your Segment workspace and navigate to Unify, select Unify settings, and click API access.
- Create an Access Token with a name that clearly describes your use case (for example, development or production).
- Note the space ID value displayed on the screen, as you will need to pass this into your Profile API request URL later.
- Click Generate token.
- Copy the resulting Access Token and securely store it on your computer. You will pass this token into the Profile API for authorization as an HTTP Basic Auth username.
- To find a user identifier for your query, navigate to Unify, select Profile explorer, and click on the user you want to query.
- Take note of the user's available identifiers (e.g., user_id, anonymous_id, or email). The Profile API requires both the type of ID and the value, separated by a colon (for example, email:user@example.com).
- Prepare your request URL by replacing <space_id> and <external_id> using the following URL structure: https://profiles.segment.com/v1/spaces/<space_id>/collections/users/profiles/<external_id>/traits
- From the HTTP client of your choice, configure Basic Authentication using your Access Token as the username and leaving the password blank.
- Send a GET request to the URL to view the JSON object containing the queried user's assigned traits.
Additional Information
- Server-Side Use Only: The Profile API requires your secret Access Token and is intended to be used entirely server-side. It should not be implemented directly in client-side applications.
- Rate Limits: To ensure fast response times, every Space has a default rate limit of 100 requests per second. If you exceed this, you will receive a 429 Too Many Requests error.
- EU Endpoint: If you are implementing the Profile API in the European Union, you must use the regional endpoint: https://profiles.euw1.segment.com.
- URL Encoding: If the identifier contains a plus sign (like a phone number formatted as +15555555555), you must URL-encode it using %2B in place of the plus sign (for example, phone_number:%2B15555555555).