> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeotap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Profile API
> High-level overview of the Zeotap Profile API — functionality, authentication, rate limits, and best practices.
This section provides a high-level overview of our API, covering its functionality and applications. Currently, we have enabled Profile API using which, you can call traits or profile attributes, consent or marketing preferences of an identity's user profile. This API can be used to provide personalised experiences for your users across any channel.
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**.
For details on payload size limitations, refer to the [Payload Size](#payload-size) section.
## 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 Preferences` and `Calculated Attributes`
* **Any external ID** – The API supports queries from `user_id`, `advertising IDs`, `anonymous_id` and `custom 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:
Your app client requests specific personalisation data, such as product recommendations, from your personalisation service, providing the user's identity.
The back-end personalisation service interacts with the Profile API, determining the appropriate app behaviour based on the user's profile information.
Subsequently, the personalisation service exclusively furnishes your app's front end with the essential information required to implement the desired personalisation.
## 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](#status-codes-and-responses)
Once you have understood these fundamentals, you can proceed to make your first API call using the [Base URL](#base-url) along with the operation you want to perform.
## 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 →](/api-reference/fetch-user-profiles)
### → 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 →](/api-reference/create-or-update-user-profiles)
### → Delete User Profiles
Use this POST request to delete a user profile from the Zeotap system.
[View Delete User Profiles API Reference →](/api-reference/delete-user-profiles)
## 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](/profile-api/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:
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.
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**.
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.
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.
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.
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](/profile-api/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](/profile-api/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](/profile-api/delete-user-profiles).
* For **Read API – Sample Requests and Responses**, refer to [Fetch User Profiles](/profile-api/fetch-user-profiles#sample-requests-and-responses).
* For **Write API – Sample Requests and Responses**, refer to [Create or Update User Profiles](/profile-api/create-or-update-user-profiles#sample-requests-and-responses).
* For **Delete API – Sample Requests and Responses**, refer to [Delete User Profiles](/profile-api/delete-user-profiles#sample-requests-and-responses).