The Profile API is available to all Zeotap accounts and supports up to 10,000 requests per minute. However:
- Concurrency must not exceed 200 requests per second.
- The average profile response size must not exceed 1 KB.
Key Features of Profile API
The following are some of the key features of the Profile API:- Fast response times – Fetch traits from a user profile under 200ms
- Real-time data – Query streaming data on the user profile
- One identity – Query an end user’s interactions across web, mobile, server, and third-party touch-points
- Rich data – Query
IDs,Profile,Consent,Marketing PreferencesandCalculated Attributes - Any external ID – The API supports queries from
user_id,advertising IDs,anonymous_idandcustom external IDs
Profile API Workflow
As a best practice, avoid making direct queries to the Profile API from your app’s front end. Instead, create a dedicated back-end service to successfully implement personalisation using the Profile API. This service can be integrated into your existing backend framework or operate as a standalone service. It serves as a mediator between your front end and the Profile API, thereby enhancing efficiency and security. The following steps outline how the Profile API works:Client Request
Your app client requests specific personalisation data, such as product recommendations, from your personalisation service, providing the user’s identity.
Backend Interaction
The back-end personalisation service interacts with the Profile API, determining the appropriate app behaviour based on the user’s profile information.
Get Started
To start using Profile API, reach out to your Customer Success Manager or Zeotap Support Team to activate the feature and get the necessary Authentication Token — which in this case is the API Key associated with your Organisation. Ensure that you familiarise yourself with critical technical concepts, such as:- Creating an authorisation header
- Structuring the payload body
- Understanding status codes and responses
Manage User Profiles
You can use our Profile API to perform the following operations:| Operation | Description |
|---|---|
| Read | Allows to fetch up to 5 immutable IDs per API call |
| Write | Allows to create/update one immutable ID per API call |
| Delete | Allows to delete up to 400 IDs per API call |
→ Fetch User Profiles
Use this POST request to read or look up a user profile in the Zeotap system. View Fetch User Profiles API Reference →→ Create or Update User Profiles
Use this POST request to create or update a user profile in the Zeotap system. View Create or Update User Profiles API Reference →→ Delete User Profiles
Use this POST request to delete a user profile from the Zeotap system. View Delete User Profiles API Reference →Base URL
Use the appropriate production endpoint based on your preferred data transport method:- HTTPS Requests:
https://api.zeotap.com - mTLS Requests:
https://mtls-api.zeotap.com
Authentication
Currently, Zeotap supports API Key authentication only. However, we extend support to additional authentication schemes based on the need. API Key Authentication — This method utilises a unique identifier (API Key) assigned to an Organisation to authenticate API requests. This API Key is generated by Zeotap when your Organisation is created within the Zeotap system. You can include this key in the HTTP header or URL parameters of API requests, which enables the Zeotap server to validate and authorise the request.Data Transport Protocols/Methods
The following are the protocols/methods supported for secure data transmission:- HTTPS (Hypertext Transfer Protocol Secure) — Encrypts data sent between your application and the Zeotap server, ensuring secure communication over the internet.
- mTLS (Mutual Transport Layer Security) — Allows both your application and the Zeotap server to authenticate each other and establish an encrypted connection, thereby enhancing security for data transmission. For information about how to configure mTLS, refer to How to Configure mTLS.
Quotas and Rate Limits
Currently, there are no limitations on the number of API calls to the Zeotap server. Moreover, the platform has the capability to autoscale to handle fluctuations or spikes in API requests.Payload Size
The following are the limitations on the number of immutable IDs (unique profiles) that can be managed through Profile API:| Operation | Description |
|---|---|
| Read | Allows to fetch up to 5 immutable IDs per API call |
| Write | Allows to create/update one immutable ID per API call |
| Delete | Allows to delete up to 400 IDs per API call |
Status Codes and Responses
We use the conventional HTTP response codes to indicate the success or failure of an API request. The following table lists the status/error codes that are returned by the API requests:| Status/Error Code | Description |
|---|---|
200 - OK | This is the response when your request is accepted and processed successfully. |
204 - No Content | This is the response when your request is accepted. |
400 - Bad Request | This is the response when your request is unacceptable, which is often due to a required parameter that is missing. |
401 - Unauthorized | This is the response when your request is not processed due to inadequate user permissions or invalid access token. |
403 - Forbidden | This is the response when you are forbidden from accessing a valid URL. |
404 - Not Found | This is the response when you request a resource that does not exist. |
429 - Too Many Requests | This is the response when too many requests hit the API too quickly. |
500, 502, 503, 504 - Server Errors | This is the response when there is an issue at Zeotap’s end. |
400 - Bad Request / Response: Search failed as no Identifier found in the request | This is the response when you send a null or empty ID value. |
400 - Bad Request / Response: Request failed as no Org ID was found in request | This is the response when you send a request without the Org ID key or value. |
Best Practices and Recommendations
The following are the best practices and recommendations that we suggest:Invoke once per session
Invoke once per session
We recommend you invoke the Profile API once per session only. As the response is unlikely to change, even if the API is called multiple times, you can cache the response locally for subsequent use within the session. However, note that calling the API multiple times is still counted against your usage metrics.
Avoid calls with no ID
Avoid calls with no ID
To avoid unnecessary count against your usage metrics, we advise you to add a check to prevent calling the Profile API when there is no ID to look up.
Use separate API token per interface
Use separate API token per interface
We recommend you use a separate API token for each interface. This ensures that each interface is uniquely identified and managed separately. Using separate API tokens also enhances the security of your system by limiting access to individual interfaces when one token is compromised.
Use immutable or primary IDs for lookups
Use immutable or primary IDs for lookups
For user lookups, we recommend you use one of the immutable IDs or primary IDs that you have selected for ID resolution. This ensures that the user is identified uniquely and the lookup is consistent across different systems.
Implement via a backend service layer
Implement via a backend service layer
To ensure security, we do not recommend you implement Profile API on a web interface. Instead, we recommend you implement the API remotely using a service layer. This approach minimises the risk of unauthorised access and other security vulnerabilities that may arise when implementing the API on a web interface.
Use the Fetch node for specific attributes
Use the Fetch node for specific attributes
To call a specific attribute of a user, we recommend you use the Fetch node. This allows you to retrieve only the required attribute instead of calling all user attributes on the client side.
Related Topics
- For information about how to use Read API to read or look up a user profile in Zeotap, refer to Fetch User Profiles.
- For information about how to use Write API to create or update a user profile in Zeotap, refer to Create or Update User Profiles.
- For information about how to use Delete API to delete a user profile in Zeotap, refer to Delete User Profiles.
- For Read API – Sample Requests and Responses, refer to Fetch User Profiles.
- For Write API – Sample Requests and Responses, refer to Create or Update User Profiles.
- For Delete API – Sample Requests and Responses, refer to Delete User Profiles.