Monetate

This documentation for the Monetate integration describes the technical capabilities of this integration, including authorization, scopes/permissions, and utilized endpoints. For more information on how to integrate Monetate, visit our connection instructions.

Version

This integration utilizes the Monetate Consumer Data Access API v1.

Base URL

The base URL used for all Monetate API endpoints:

https://api.monetate.net/api/data/v1

---

Authentication & Authorization

The DataGrail Monetate integration connects using JWT authentication which requires the following: Retailer Short Name, Username, and Private Key.

Sensitive Credentials

Publicly exposing your API credentials can allow unauthorized access to Monetate API endpoints by a third party. DataGrail stores your API credentials encrypted and protected.

Authentication Details

Monetate authenticates API requests using RSA-signed JWT tokens. DataGrail signs a short-lived JWT using the configured Private Key and exchanges it for a bearer token via the https://api.monetate.net/api/auth/v0/refresh endpoint. All subsequent API calls include this bearer token in the Authorization header.

The JWT is signed using the RS256 algorithm. The Username configured in DataGrail must match the API user created in the Monetate portal, and the corresponding Public Key must be uploaded to that user's account in Monetate.

Credential Security

Publicly exposing your API credentials can allow unauthorized access to the Monetate API endpoints and your Monetate data by a third party. DataGrail stores your API credentials encrypted and protected.

Endpoints Utilized

DataGrail uses the following endpoints to authorize and test the connection:

Method	Endpoint	Purpose	Docs
GET	/RETAILER_SHORT_NAME/production/schema/DATASET_NAME	Verify that the privacy deletion dataset exists
GET	https://api.monetate.net/api/auth/v0/refresh	Exchange JWT for an API token

---

Limits

Limits in Monetate are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an HTTP 429 Too Many Requests error is returned. Requests succeed again after enough requests have emptied out of the bucket.

• DataGrail supports requests throttling to stay within 70-80% of specified service rate limits.
• DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

---

Capabilities

Access

DataGrail's Monetate integration provides Synchronous Access capabilities for the following supported identifier category: Service ID.

Data Interactions

For Access requests, DataGrail will take the following actions:

1. Retrieve consumer profile data by querying the /api/profile/v1/{retailer_short_name}/{customer_id}.csv endpoint using the provided Service ID (customer ID).
2. Parse the multi-section CSV response, which contains sections such as custom_target, last_customer_id, and session — each representing a different category of profile data.
3. Return all available fields and data for the matched customer.

Endpoints Utilized

Method	Endpoint	Purpose	Docs
GET	/api/profile/v1/RETAILER_SHORT_NAME/CUSTOMER_ID.csv	Retrieve consumer profile data by customer ID

---

Deletion

DataGrail's Monetate integration provides Asynchronous (Whole Record) Deletion capabilities for the following supported identifier category: Service ID.

Data Interactions

For Deletion requests, DataGrail will take the following actions:

1. Verify that the privacy deletion dataset exists by querying the schema endpoint. If the dataset does not exist, DataGrail will create it automatically before submitting any deletion requests.
2. Submit a deletion record to the /{retailer_short_name}/production/{dataset_name} endpoint for each provided Service ID, including the customer ID and the deletion request date.
3. Poll the deletion status endpoint periodically (every 24 hours, for up to 30 days) using the same endpoint with the customer ID as a query parameter. Monetate progresses deletion status through pending → found → not_found, where not_found indicates the data has been fully removed.

Endpoints Utilized

Method	Endpoint	Purpose	Docs
GET	/RETAILER_SHORT_NAME/production/DATASET_NAME	Check deletion status for a customer ID
POST	/RETAILER_SHORT_NAME/production/DATASET_NAME	Submit a deletion request for a customer ID
POST	/RETAILER_SHORT_NAME/production/schema	Create the privacy deletion dataset if it does not exist

---