OAuth Documentation

There are two options for your application to gain initial authorization access to an Act-On account.

  • For integrations that you develop in-house, where you have direct access to user account credentials, we recommend grant type: password.
  • For integrations that you develop as a third party, where you can't store user credentials within the application, and/or where you connect to several Act-On accounts, we recommend grant type: code.

Both authorization methods returns an access_token and a refresh_token. The access token is used with all other endpoints to verify your application has been authorized to access that Act-On account. The refresh_token is used only in the grant type: refresh call to the token endpoint. This provides a new pair of access and refresh tokens so that your session can continue uninterrupted.

About the Tokens

Each access_token expires 1 hour after the time it was granted. To continue using Act-On after a session access token expires, you must request a new one using the grant-type: refresh. Each refresh token can only be used once, and lasts either until it is used, or another access token is issued for the same application and username combination.

Password or Code grant types are limited to 5 authentication attempts per hour. Using the refresh token workflow avoids unneeded access token requests and prevents your application from reaching this limit. For more limits details, please see our FAQ.

If you have an Act-On Agency account, please see our Agency Authentication page for details on determining the username and setting the password for your agency's child accounts.

Getting Started

  1. If you have not yet registered for a client ID and Secret, head to our Provisioning page to sign up.
  2. Decide whether you will use the Password or Code grant types.

Even if you plan to use grant type code, an understanding of how grant type password works can be useful.

In general, the authentication portions of your application should:

  • Store the returned access_token to use to authenticate all other endpoint requests until the token expires.
  • Store the returned refresh_token for the purpose of getting a new access_token after the access token expires.
  • Use the refresh token from the immediately prior session in a refresh request. When the refresh request is granted, the response contains another access token/refresh token pair which will need to be stored for the next cycle.

Method Name

Endpoint

  • OAuth

  • Grant Type Password

  • Grant Type Code

  • Grant Type Refresh

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
Get contact fact and score data
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 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