Act-On REST API Frequently Asked Questions

  1. My API keys are connected to my sandbox account. How do I connect my integration with my production account instead?
  2. I'm getting an error "PUBLIC_API_FEATURE_NOT_ENABLED" when trying to authenticate using my production account. How do I enable API access for my production account?
  3. Are there any limits to API usage?
  4. How are the rate limits calculated?
  5. How can my application work with multiple Act-On accounts?
  6. I am developing an application that will be used by an Act-On agency. How does the API handle agency sub-accounts?
  7. How do I know the list ID of my target list when only the name is known?
  8. How can I find the record ID of a record with only the email address?
  9. What do the different authentication or rate limit error responses I am seeing mean?

My API keys are connected to my sandbox account. How do I connect my integration with my production account instead?

The API keys that were provided with your developer registration are not tied to a specific Act-On account. To use your integration with your production account, enter the username and password of a production user when using the password or authorization_code requests to obtain an access token. All requests using this access token will target the account tied to the username and password used to generate the token.

I'm getting an error "PUBLIC_API_FEATURE_NOT_ENABLED" when trying to authenticate using my production account. How do I enable API access for my production account?

API access is not enabled on all production accounts by default. While Act-On does offer a free tier (1000 requests/day) of API usage there is a cost if you exceed this limit. Please reach out to the Customer Success Manager of the production account to have API access enabled if you are getting this message.

Are there any limits to API usage?

There are 4 different API usage limitations to consider when developing your solution:

  1. Auth Requests: 5 password grant authentication requests per hour - Access tokens last for a 1 hour period and can be refreshed using the refresh grant without counting toward the 5 per hour limit. This limit applies to the password grant request only and can be successfully mitigated with the recommended authentication logic flow. More detail about this can be found on our oAuth documentation page.
  2. API Request Rate: 20 API requests per minute of any type  - Your application will need to account for this limitation by catching and retrying requests that are rejected because they have exceeded the rate limit. If your application will be adding or updating a large amount of records to Act-On in separate transactions, a good best practice is to batch several updates into one request using the update or merge a list endpoint instead of adding each individually with the update or insert contact endpoint.
  3. API Request Usage: 30,000 Requests per day  - Whether you are developing an integration for a specific Act-On client, or are a 3rd party developer and intend on offering your integration to the entire Act-On client base it is a good idea to keep this in mind.
  4. Upload File Size: 400MB - If you need to upload a file that is of a larger size, such as a .csv, this file can be split into multiple files.

How are the rate limits calculated?

For both the 5 password grant/hr and 5 request/sec limits at the time of a given request, we look back over the timeframe of the limit, and if there have been more requests than are allocated, we will reject the request. This means that it is possible to continue extending the lockout period indefinitely if additional requests are issued at a fast enough rate.

How can my application work with multiple Act-On accounts?

The API client ID and secret are tied to your application, not a specific Act-On account. If you are developing for a single client with multiple accounts, your application can store credentials for each account, and issue the password grant request to obtain distinct access tokens for each.

If you are a third-party developer using the code authorization grant the same concept applies, each code that is returned is tied to the specific Act-On user's account.

Whether using the code or password authorization grant, the aforementioned rate limits are per Act-On account, not per application. If you are using 2 different access tokens for different accounts simultaneously the rate limits are tallied for each account separately.

I am developing an application that will be used by an Act-On agency. How does the API handle agency sub-accounts?

The API treats agency sub-accounts as distinct Act-On accounts and distinct access tokens can be requested for each sub-account using the methods outlined in the above FAQ question.

Because agency managers often do not have direct logins to the sub accounts created, the manager will need to provision a non-managed marketing user on the sub-account for the purposes of API authentication. This user will have direct authentication which is available via the API. To complete this you can reference the Act-On University article on user management here.

How do I know the list ID of my target list when only the name is known?

The listID of a given list can be obtained by using the get list listing endpoint and parsing the response for the list name. The ID will be included in the JSON element for the given list.

How can I find the record ID of a record with only the email address?

The record ID of an email address in a list can be obtained by using the download a list endpoint and parsing the list for the email address but because a list can have tens or hundreds of thousands of records this can be somewhat costly from a performance perspective. If there are specific lists your integration is targeting one option would be to periodically update a local copy of the list using the download a list endpoint and searching against that.

Another option is to use the update or insert contact endpoint with an empty JSON object - {}.  This will return the record ID of the record but will not change the record, as we are updating it with the same value.

For Example:

  1. Issue PUT /api/1/list/{listID}/record?email=example@email.com with a an empty JSON object in the body - {}
  2. If the record exists the JSON response will show "Record updated", the recID of the record will be returned.
  3. If the record does not exist the response will show "Record inserted", the record will be created and the recID of the record would be returned. Based on your needs you would want to delete the record using the delete a contact endpoint at this time.

What do the different authentication or rate limit error responses I am seeing mean?

Below is a table which includes several common error responses and a description. If you don't see your error listed here, please check the Response Body for context on the specific error.

Response Header Error Message Description
400 Bad Request
{
error: "invalid_grant"
error_description: "Username\/Password incorrect or too many login attempts. Only 5 auth attempts allowed per hour."
}
Your application has exceeded the maximum number of authentication requests per hour (5) or the username and password being used for the password grant is incorrect.
503 Service Unavailable
<amt:fault xmlns:amt="http://wso2.org/apimanager/throttling">
<amt:code>900800</amt:code>
<amt:message>Message Throttled Out</amt:message>
<amt:description>You have exceeded your quota</amt:description>
</amt:fault>
Your application has exceeded the maximum number of overall requests per minute. (20)
401 Unauthorized
<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
<ams:code>900904</ams:code>
<ams:message>Access Token Inactive</ams:message>
<ams:description>Access failure for API: /api, version: 1 with key: b53cfb1a31e32bc74c502f616ee819</ams:description>
</ams:fault>
The access token being used for the request is expired.
401 Unauthorized
<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
<ams:code>900901</ams:code>
<ams:message>Invalid Credentials</ams:message>
<ams:description>Access failure for API: /api, version: 1 with key: b53cfb1a3kjkjkjkjk1e32bc74c502f616ee819</ams:description>
</ams:fault>
The access token being used for the request is incorrect.
400 Bad Request
{
error: "invalid_grant",
error_description: "Provided Authorization Grant is invalid."
}
The refresh token being used for a refresh grant request is invalid.
401 Unauthorized {"errorCode": "PUBLIC_API_FEATURE_NOT_ENABLED","message": "API feature has not been enabled for this account"} The access token you are using was issued for an Act-On account that does not have API access enabled. An error should be returned recommending the end user contact their Customer Success Manager at Act-On to enable access to the API.