Act-on REST API Frequently Asked Questions

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 is the minimum Security Protocol required to communicate with your endpoints?
10. 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: 1000MB - 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 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 is the minimum Security Protocol required to communicate with your endpoints?

Requests made to any Act-On API endpoint must be made using Transport Security Layer (TLS) 1.2 or higher. This is in effect as of January 19, 2021. We recommend making your changes now to avoid disruption of service. See our post here for more information.

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.