API usage guidelines covering parameter validation, batching, payload limits, formatting, error handling, and rate limits.
- Please make sure you send the correct app_id.
- Always send valid profile_ids, they must only include digits, letters and dash (-).
Batching Requests
For optimal performance, we recommend batching multiple profiles or events in a single request. The recommended batch size is 10 to 100 items per request.
Payload Size Limits
- Maximum total payload size: 10MB
- Maximum size for a single array item: 1MB
Date and Time Formatting
All date and time values must be formatted according to the ISO 8601 standard, in UTC timezone:
YYYY-MM-DDTHH:MM:SS.SSSZExample: 2024-10-28T00:10:02.471Z
Insert ID
We suggest that you send a UUID value for the “urm_insert_id” field for easy record tracking.
Key Values
- All Event and Profile attributes must have no special characters in their “key”
- The “event” attribute’s value can have no special characters (an event name cannot have any special characters)
Error Handling
- Implement proper error handling in your code to account for potential API errors
- Retry failed requests with an exponential backoff strategy
- Log detailed error information for troubleshooting
Rate Limiting
To ensure system stability, API requests are subject to rate limiting:
- Maximum 100 requests per minute
- Maximum 5,000 requests per hour
Exceeding these limits will result in a 429 Too Many Requests response.
Your API rate limits will be increased beyond the standard limits based on volume. Please let us know as soon as you think we should adjust them for you.
