Overview¶

Authentication¶

Requests to ActionKit's REST API require authentication using HTTP Basic Auth.

The user is a user account from the list of staff users. We recommend creating staff accounts that are dedicated to API use. You can connect with the standard account password.

You can use the Permissions Groups to grant access to the REST API. To grant access to all objects in the database, add an account to the "All Models - View, Edit, and Delete" group. However, for security it's preferable to restrict an account's access to just the kinds of objects it will need.

You can test if an account has view access to a particular resource in the API by loading a URL like:

https://{User}:{Password}@[ YOUR ACTIONKIT HOSTNAME ]/rest/v1/

Resource List¶

You can browse the API at /rest/v1/ to see the full list of resources. Each resource listed includes the URI of a list endpoint and a schema, like so:

'action': { 'list_endpoint': /rest/v1/action/,
            'schema': /rest/v1/action/schema/},

Request Formats¶

ActionKit looks at the Content-Type header to decide how to parse any data sent in the request. The same request can be represented in JSON or XML. Your requests should include a Content-Type header with a value of 'application/xml' or 'application/json'.

XML requests should use a root element named request: '<request type="hash"></request>'. XML responses have a root element of response or object.

All requests must be encoded in UTF-8.

If there are other formats you'd like to see, please let us know.

Read more about Requests.

Response Formats¶

ActionKit looks at the Accept header to decide how to format responses. You can also use a format parameter in the query string to request a specific format. If the request query string includes a callback parameter, ActionKit will always return a JSONP callback.

We support the following formats. The Accept header uses the mime-types, the format parameter uses the names on the left, e.g. 'jsonp':

json  : application/json
jsonp : text/javascript
xml   : application/xml
html  : text/html
form  : text/html

We recommend using JSON.

Here's an example of a request using the Accept header to format the response in JSON:

$ curl -i -u user:password -H 'Accept: application/json' https://docs.actionkit.com/rest/v1/list/
HTTP/1.1 200 OK
Date: Tue, 20 Mar 2012 12:06:43 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{
    "meta": {
        "previous": null,
        "total_count": 1,
        "offset": 0,
        "limit": 20,
        "next": null
    },
    "objects": [
        {
            "name": "Main email list",
            "created_at": "2012-03-14T09:06:01",
            "updated_at": "2012-03-14T09:06:01",
            "is_default": false,
            "hidden": false,
            "resource_uri": "/rest/v1/list/1/"
        }
    ]
}

And here's an example of a request using the format parameter in the query string. This time we'll ask for xml:

$ curl -i -u user:password 'https://docs.actionkit.com/rest/v1/list/?format=xml'
HTTP/1.1 200 OK
Date: Tue, 20 Mar 2012 12:08:06 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/xml; charset=utf-8
Transfer-Encoding: chunked

<?xml version="1.0" encoding="utf-8"?>
<response>
  <objects type="list">
    <object>
      <name>Main email list</name>
      <created_at>2012-03-14T09:06:01</created_at>
      <updated_at>2012-03-14T09:06:01</updated_at>
      <is_default type="boolean">False</is_default>
      <hidden type="boolean">False</hidden>
      <resource_uri>/rest/v1/list/1/</resource_uri>
    </object>
  </objects>
  <meta type="hash">
    <next type="null"/>
    <total_count type="integer">1</total_count>
    <previous type="null"/>
    <limit type="integer">20</limit>
    <offset type="integer">0</offset>
  </meta>
</response>

Response Codes¶

Response codes used by ActionKit are summarized below. Refer to https://tools.ietf.org/html/rfc7231#section-6 for the canonical definitions.

Filtering And Ordering¶

The fields and operators in filtering and ordering are based on the Django QuerySet syntax. The schema for each resource lists the fields on which you can filter under 'filtering', and on which you can order under 'ordering'. Fields sent as parameters in they querystring will be used for filtering, if they are fields on the resource. Ordering will check for an 'order_by' parameter in the querystring.

High Level APIs¶

We've added a few high level APIs and methods to provide short cuts for certain common usecases or extended functionality.

• Generic Action Processing handles all action creation.
• The Donation Push API streamlines the process of sending externally processed donations to be recorded in your ActionKit database.
• The Mailer API provides tools for creating, targeting, proofing and sending mailings.
• Reports can be run synchronously or asynchronously using the /run/ and /background/ methods for the report resource.
• The upload resource has a /stop/ method.
• The usermerge endpoint creates a user merge job to combine records from two or more users.
• The eraser endpoint is used to delete user data.
• The salesforcemap endpoint is used to manage users in the Salesforce sync.

Action Processing¶

Almost all user actions should be created by via generic action processing. The action processor provides validation for actions of all types, such as checking that starts_at is in the future when creating events. And some ActionKit features such as "Act as Host" don't work without an eventcreateaction, which is only created via generic action processing.

You can create Actions by POSTing to the collection of Actions, i.e. the list_endpoint for the Action resource: /rest/v1/action/.

The only required parameters for action processing are page - the name of the Page - and user email. However, there are many other parameters to control processing and collect information from users.

POSTing to the generic action collection is like submitting a form from the cms or a page hosted outside of ActionKit. You can submit actions as JSON, XML, or x-www-form-url-encoded data.

You can process actions without authenticating. This is very similar to submitting a form in a page hosted on the ActionKit CMS or on your servers. The response from ActionKit will contain more information if the connection is authenticated.

Read more about Generic Action Processing.

Creating Pages¶

Action pages are created in a three step process, mimicking the process of creating pages through the ActionKit admin.

POST /rest/v1/petitionpage/

{
  "fields": {
    "custompagefield1": "First custom page field value",
    "custompagefield2": "Second custom page field value"
  },
  "name": "climate-change",   // required
  "required_fields": [
    {
      "id": "2",
      "name": "zip",
      "resource_uri": "/rest/v1/formfield/2/"
    },
    {
      "id": "11",
      "name": "name",
      "resource_uri": "/rest/v1/formfield/11/"
    }
  ],
  "title": "Climate Change Is Real",
  "tags": [
    {
      "name": "climate",
      "resource_uri": "/rest/v1/tag/1/"
    }
  ]
}

POST /rest/v1/petitionform/

{
  "about_text": "Let me tell you about the issue.",
  "page": "/rest/v1/petitionpage/1234/",    // required for all page types
  "statement_leadin": "Tell the President:",
  "statement_text": "Climate change is real.",
  "thank_you_text": "Thanks for signing."   // required for all page types
}

POST /rest/v1/pagefollowup/

{
  "page": "/rest/v1/petitionpage/1234/",  // required
  "email_body": "Thanks for signing, now please share by forwarding this message to your friends.",
  "email_from_line": "/rest/v1/fromline/1/",
  "email_subject": "You're almost done.",
  "email_wrapper": "/rest/v1/emailwrapper/1/",
  "send_email": true,
  "send_taf": false,
  "share_description": "We're almost out of time to save the planet.",
  "share_image": "https://climate.nasa.gov/system/internal_resources/details/original/103_shutterstock_88550854-740px.jpg",
  "share_title": "Sign and share: Climate change is real.",
  "url": "/cms/thanks/my-test-page/"      // required
}