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 3 different API usage limitations to consider:

  1. 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. 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. 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.

 

How are the rate limits calculated?

For both the 5 password grant/hr and 20 request/min 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 is 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 either provision a user on the sub-account for the purposes of API authentication, or they can contact api@act-on.net and we will provide direct login credentials for the sub-accounts that are currently not made visible in the Agency Panel.

 

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 name of the list. 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 error responses and a description.

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.

 

 

OAuth
Grant Type Password
Grant Type Code
Grant Type Refresh
Account API
Get account information
Create new account user
Delete account users
Delete account user
Get email senders
Fact API
Upload custom events
Get upload custom event status
List API
Get listing of lists
Download a list
Create a new list
Update or merge a list
Get list upload status
Delete a list
Delete records from a list
Get hard bounce list
Get spam complaint list
Get optout list
Update optout list
Get subscription opt-outs by category
mergespecs
uploadspecs
Content API
Get logo list
Get a logo
Add a logo
Update a logo
Delete a logo
Get header list
Get a header
Add a header
Update a header
Delete a header
Get footer list
Get a footer
Add a new footer
Delete a footer
Update a footer
Get image list
Get an image
Add an image
Replace an image
Delete an image
Get media list
Get media file
Add a media file
Add a media link
Update Media File
Delete a media object
Get form list
Get promotional form URLs
Get page list
Get page
Delete page
Get promotional page URLs
Get list of programs
Reporting API
Get message report
Get message report drilldown
Get message report by time period
Get media report
Get media message report
Get a media view report
Get a media timeline report
Get form report
Get page report
Get spam complaint list
Get hard bounce list
Email Campaign API
Get message list
Send a message
Resend a message
Add new template or draft message
Update template or draft message
Delete a message
Get message report
Get message report drilldown
Get message report by time period
Get message HTML contents
Contact API
Add a contact
Get contact record
Upsert a contact record by email
Update a contact by record ID
Delete a contact
Get contact record ID based on cookie ID
Get contact from list based on cookie ID or e-mail
Get contact fact and score data
Get subscription categories
Opt in/Opt out subscription category by email address
Get subscription category opt-ins by email
Opt in/Opt out multiple subscription categories by email address
SEO API
Get SEO keywords
Get a new SEO report
Frequently Asked Questions