How does CitrusAd work?
The CitrusAd API is organised around REST. The API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. The API uses built-in HTTP features including HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.
Authentication to the CitrusAd API is managed through the use of API keys. API keys are used during communication between your backend and the CitrusAd API.
The CitrusAd API supports the upload of products, catalogs, customers, and order data, which is used to generate ads. You can use the CitrusAd API to request ads and report on interactions with those ads.
CitrusAd endpoints
CitrusAd uses various endpoints to sync data and generate ads. A brief summary is provided below:
| Endpoint | Use | Description |
|---|---|---|
catalogs | Syncing catalog via API | Used to create catalogs via API. For single catalog namespaces, this is something your Technical Account Manager can organise for you. |
catalog-products | Syncing products via API | Used to create and update product data within a catalog. |
customers | Syncing customer data via API | Used to create and update customer data within a catalog. |
orders | Syncing order data via API | Used to send order data to CitrusAd. |
/resource/ | Reporting impressions & clicks Syncing order data via API | Used to report clicks and impressions, as well as orders if reporting via front-end. |
/ads/generate | Generating ads | Used to generate product ads and banner ads. |
/ads/bannerx | Generating ads | Used to generate banner x ads. |
You don’t need to use endpoints for catalog, product, customer, and order syncing. CitrusAd supports syncing data via file, which may be suitable for your requirements.
Content type & payload
The data payload is in JSON format. The Content-Type for these endpoints is application/json, which should be passed as a header in your requests as follows:
-H "Content-Type: application/json" \
Authenticating requests
Basic authentication
All integration resources use basic authentication which should be passed as a header with your API key as follows:
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
Your API Key can be accessed in the Integration Settings section of the retailer team. You will only need the secret API key.
OAuth2.0 authentication
CitrusAd's ad generation endpoint is additionally compatible with OAuth2.0. Review OAuth 2.0 Authentication for more information.
Base URLs
CitrusAd uses different base URLs for staging and production environments.
To receive your staging base URL, please contact CitrusAd. Once your integration is in progress, we will provide you with production base URLs.