Antavo APIs
The primary functions of the Antavo Loyalty Cloud are accessible through various APIs. Antavo provides REST APIs accessible with standard HTTP verbs GET, POST, PUT, and DELETE for issuing requests. Requests are accepted in URL-encoded and JSON formats, with responses provided in JSON format, including error messages.
The APIs are grouped based on the resources they access, manipulate, or create.
Postman collection
You can import our API collection into Postman through our public Postman collection documentation.
The collection includes a pre-request script at both the collection and endpoint levels, which is required for adding the API signature to enable sending signed requests from Postman. When you import the collection into Postman using the Run in Postman button, you only need to populate the environment with the data specific to your Antavo workspace (name of the environment, API key, and API secret).
If further assistance or information is needed regarding signature configuration, you can find a detailed guide in the Signing API requests in Postman article.
List of Antavo's APIs
Events API
The Events API records every customer-related interaction from e-commerce systems, point-of-sale terminals, websites, mobile apps, and other external systems.
Display API
The Display API serves as the main headless API for building the customer loyalty experience.
Points preview API
The Points preview API queries information related to product point values, including bonus points assigned by the Workflows module.
Bulk operations API
The Bulk operations API handles batch processing requests for customer reward claims, list management (add/remove), and coupon management.
Coupons API
The Coupons API allows customer-independent API calls to query coupon usage.
Coupons Pools API
The Coupons Pools API enables the creation and management of coupon pools, defining attributes such as value, expiration, and code patterns for the coupons they contain.
Customer API
The Customer API provides interfaces for delivering personalized customer experiences without compromising privacy.
Entities API
The Entities API enables access and modification of foundational components such as rewards, challenges, stores, products, and transactions within Antavo.
FAQ API
The FAQ API provides access to configured questions and answers in the Frequently Asked Questions (FAQ) module.
Leaderboard API
The Leaderboard API lists and interacts with top customers within mobile applications, responsive websites, or CRMs.
Offers API
The Offers API provides access to pre-purchase incentives that can be customized to attract new customers or engage existing loyalty program members.
Rewards API - LEGACY
The Rewards API manages the rewards system within the Management UI and enables reward claims.
The functionality of this endpoint has been replaced by the Reward endpoints of the Display API.
Rate limiting
All Antavo APIs are subject to fair use policies. The cumulative limit is 1,500 requests per minute on the shared stack and 20,000 requests per minute on dedicated stack, measured across all endpoints per API key to maintain service quality. Exceeding this limit will result in temporary request blocks based on server load. Implement error handling and monitoring to mitigate this risk. Consider request throttling and response caching to optimize performance and avoid rate limits.
Best practices for efficient API usage
To ensure optimal performance and data consistency when interacting with our API, consider the following best practices:
Implement API throttling
Regulate request rates to avoid excessive API calls, particularly those affecting the same customer. Adding sufficient time between consecutive requests helps maintain system efficiency and data integrity.
Maintain event order at submission
Events should be sent in the correct sequence as they occur. The system processes requests in the order received (FIFO), without reordering. If an event is submitted later due to an error, it will be recorded with the timestamp of when it is successfully processed without errors.
Prevent unintended duplicate requests
When a customer action triggers an event (e.g., customer clicks a Submit button), disable the triggering button to prevent multiple submissions in quick succession. This prevents redundant requests and enhances user experience.
Support for Custom Response Fields
API responses should be handled in a way that allows for flexibility when processing data. If undocumented data fields appear in responses, such as custom attributes added via Loyalty Engine configuration, make sure these do not cause failures or unexpected behavior on your end.
API Documentation Review
It is strongly recommended to thoroughly review the documentation, particularly Actions and Events, API security, and API endpoints, to determine the best approach for using our endpoints.
The API Security document outlines necessary security measures. Individual API endpoint documentation pages detail request payload, potential responses, and error handling.
Before implementation, consult your technical contact to discuss the optimal API approach for your business logic and desired outcomes.
Multi-language support
Antavo includes multi-language support via a dedicated module for translating key functionalities.
Example response from the /entities/rewards/reward endpoint containing translations in multiple languages:
{
"data": [
{
"transfer_coupon_expires_in": "2 months",
"transferable": false,
"claim_button_label": \[],
"user_notification": false,
"description": {
"en": "Enjoy a 20% discount on our Winter Collection items."
"de": "Sichern Sie sich 20% Rabatt auf Artikel aus unserer Winterkollektion."
"fr": "Profitez d'une réduction de 20% sur les articles de notre collection d'hiver."
},
"media": {
"image_urls": {
"s": "<https://antavo.s3.eu-west-1.amazonaws.com/example">,
"xs": "<https://antavo.s3.eu-west-1.amazonaws.com/examplef">,
"l": "<https://antavo.s3.eu-west-1.amazonaws.com/example">,
"m": "<https://antavo.s3.eu-west-1.amazonaws.com/example">
},
"id": "653fa4367bdfea20645c5b26",
"mime_type": "image/gif",
"url": "<https://antavo.s3.eu-west-1.amazonaws.com/example">
},
"transfer_limit": 1,
"type": "coupon",
"transfer_coupon_expiration": "remains",
"restricted_message": {
"en": "This offer is currently unavailable. Please visit us again later."
"de": "Dieses Angebot ist derzeit nicht verfügbar. Bitte besuchen Sie uns später erneut."
"fr": "Cette offre n'est pas disponible actuellement. Veuillez revenir nous voir plus tard."
},
"redeem_instructions": {
"en": "Present this coupon at checkout to apply the discount. Valid on Winter Collection items only."
"de": "Zeigen Sie diesen Gutschein an der Kasse vor, um den Rabatt zu erhalten. Gültig nur für Artikel aus der Winterkollektion."
"fr": "Présentez ce coupon lors du paiement pour appliquer la réduction. Valable uniquement sur les articles de la collection d'hiver."
},
"hide_restricted": false,
"terms": {
"en": "The 20% discount is valid only on Winter Collection items and cannot be combined with other offers or discounts."
"de": "Der 20% Rabatt gilt nur für Artikel aus der Winterkollektion und kann nicht mit anderen Angeboten oder Rabatten kombiniert werden."
"fr": "La réduction de 20% est valable uniquement sur les articles de la collection d'hiver et ne peut pas être combinée avec d'autres offres ou réductions."
},
"price": {
"EUR": 0,
"USD": 0
},
"name": {
"en": "20% Off on Winter Collection"
"de": "20% Rabatt auf die Winterkollektion"
"fr": "20% de réduction sur la collection d'hiver"
},
"id": "653fa4367bdfea20645c5b28",
"point_source": "customer",
"transfer_points": 0,
"coupon_pool": "65b9ecef16684464f73ca414",
"notifications": false,
"status": "active"
},at": "2024-11-16T23:59:59+00:00",
"type": "percentage",
"value": 20
}
}Preconfigured languages are accessible using the Accept-language header field with ISO 639-1 2-letter language code (e.g., en, de, fr) in the API request.
NotePlease note that adding multiple languages is only supported in the Entities API.
German header and response example to claim endpoint of the Display API:
POST /customers/1ec2016c-cfed-484f-aa04-38ad658d8f6f/activities/rewards/5f0360e4a7b7c714000008af/claim HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept-language: de
Accept: _/_
Host: api.<environment>.antavo.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 0
// Response
{
"reward": {
"image": {
"small": "<https://antavo.s3.eu-west-1.amazonaws.com/brands/2623/media/1698669622-PPUFf.gif">,
"large": "<https://antavo.s3.eu-west-1.amazonaws.com/brands/2623/media/1698669621-etAyk.gif">,
"medium": "<https://antavo.s3.eu-west-1.amazonaws.com/brands/2623/media/1698669621-uXBMl.gif">
},
"instructions": "Dieses Angebot ist derzeit nicht verfügbar. Bitte besuchen Sie uns später erneut.",
"description": "Sichern Sie sich 20% Rabatt auf Artikel aus unserer Winterkollektion.",
"type": "coupon",
"title": "20% Rabatt auf die Winterkollektion",
"points": 100,
"redeem_instructions": "Zeigen Sie diesen Gutschein an der Kasse vor, um den Rabatt zu erhalten. Gültig nur für Artikel aus der Winterkollektion.",
"_actions": {
"complete": {
"method": "POST",
"url": "/customers/09d9e415-521b-48ef-9b44-fbdc8dc0189c/activities/rewards/653fa4367bdfea20645c5b28/claim"
}
},
"terms": "Der 20% Rabatt gilt nur für Artikel aus der Winterkollektion und kann nicht mit anderen Angeboten oder Rabatten kombiniert werden.",
"id": "653fa4367bdfea20645c5b28",
"point_source": "customer",
"coupon_pool": "660d445af8d7fe1f252cfc5a",
"status": "active"
},
"id": "667a75a74d35705ceb678272",
"coupon": {
"claimed_at": "2024-06-25T09:45:43+02:00",
"code": "A-7995713",
"pool": "660d445af8d7fe1f252cfc5a",
"name": "%20 coupons",
"created_at": "2024-04-03T13:59:01+02:00",
"type": "amount",
"value": 100,
"customer": {
"id": "09d9e415-521b-48ef-9b44-fbdc8dc0189c"
},
"status": "claimed"
},
"spent": 0,
"last_claimed_at": "2024-06-25T09:45:43+02:00"
}Updated 5 months ago