The Quince release (November 2020) introduced Service Accounts allowing the use of a dedicated API user and rights. As a result, it is no longer possible to create a new API app or edit an existing one through this Apps section. Existing apps will continue to work and can still be viewed.
To use an API, Marigold Engage requires you to create an application (app), which will generate authentication and secret keys to interface with the API.
Apps are part of the Data Integration tab in Admin Configuration 
The Apps overview shows all configured apps.
From this overview you can
- Access an existing app — By clicking on an app nameor on the view icon. The properties are then displayed in a right sliding panel. No changes can be made.
- Delete an existing app — By clicking on the bin icon.
Access an app to view API authentication keys
When accessing an app, the properties are shown in a right sliding panel.
The app Nameis displayed
An authentication key and secret key are displayed and can be used within the
API.
IP filtering ensures that only calls from the given IP-adresses will be taken into account. If a call is made to the API from a different IP-adress, it won't work.
Optionally, you can also filter the organizations having access to this app. As a result, API calls will only work for the organizations in the list.
Access the API
The API can be accessed from a dedicated URL linked to your environment. (e.g. http://YOURENVIRONMENT/Portal/Api/swagger/)
When the API Explorer is launched, at the top right corner the key and secret need to be entered. You can now test the API methods.
Note: All documentation regarding the API and the use of the methods can be found directly in the API Explorer which is accessible from the Modules entry in the toolbar.
API Rate Limits
Rate limiting
A rate limit defines the number of requests that can be made to the Marigold Engage REST API within a given time period. If this limit is exceeded during a time window, the application will be throttled and API requests above the limit will be rejected.
Throttling is linked to the “APP” setup within Marigold Engage and applied to its related API key.
API Limits for Engage REST API
All Engage REST API requests are subject to rate limits. An API key is allowed to make up to 2500 requests per minute across all API paths.
Note: The API limits are only applicable to the Engage REST API ; the Campaign and Direct Mail REST API are not subject to these limits.
Responses when requests are rate limited
If requests are being made at a rate higher than the limits of :
- 2500 requests / minute
Then these requests will receive the HTTP status code 429 (Too Many Requests) with a message, like the example below, in the body of the response.
Example: API calls quota exceeded! The maximum allowed is 2500 per minute.
In the response headers additional information is presented about the rate limiting state.
Example:
X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 50
X-RateLimit-Reset: 5
- X-RateLimit-Limit — represents the maximum number of allowed requests in the time window
- X-RateLimit-Remaining — represents the number of remaining requests in the current window (1 minute)
- X-RateLimit-Reset — represents the time remaining in the current window expressed in seconds
In the event that the Marigold Engage REST API is under high load or is down for maintenance, the HTTP status code 503 (Service Unavailable) will be returned.
API inbound request limit
Most API endpoints have inbound limitations set as following:
Default inbound request limit
- Limited by a 15 seconds connection time-out, meaning that the data should posted and processed within 15 seconds.
- Data size limited is to 2MB.
- Default Rate limited to 2500 requests / minute.
The « POST /data/load » endpoints support higher inbound request limits, depending on the data transfer mode.
There are currently no quantity validation constraints on:
- the number of fields per record
- the total number of records returned
Note: The amount of fields & number of records is limited by the size of the total data object.
Example: more fields mean less records that can be submitted and vice versa.
/data/load SYNC MODE
- Limited by a 15 seconds connection time-out, meaning that the data should be posted and processed within 15 seconds.
- Data size limited to 20MB.
- Number of data fields is not specifically limited.
- Number of records is depending on the number fields.
- Default Rate limited to 2500 requests / minute.
/data/load STREAMED MODE
- No connection time limit.
- Data limited to 20MB.
- Number of data fields is not specifically limited.
- Number of records is depending on the number fields.
- Default Rate limited to 2500 requests / minute.
API Outbound response limits
The response limit is typically based on the total output of data & the time needed to retrieve the dataset, which is reflected by the number of fields defined. If the number of fields is low, the take can be higher.
Default outbound request limit
- Limited by a 15 seconds connection time-out, meaning that the data requested and returned within 15 seconds.
- Default Rate limited to 2500 requests / minute.
The « POST /data/search » endpoints support higher outbound response limits, depending on the data transfer mode.
There are currently no constraints on:
- number of export fields.
- number of records.
BUT the combination the amount of fields & number of records is limited by the size of the total data object.
/data/search SYNC MODE
- No time-out limit.
- Number of records is advised to limit to a "take" of "2500".
- Data limited to size of maximum 1MB per record.
- Default Rate limited to 2500 requests / minute.
/data/search STREAMED MODE
- No time-out limit.
- Data limited to size of maximum 1MB per record.
- Default Rate limited to 2500 requests / minute.
