Generic Action Processing¶

Unauthenticated¶

The simplest POST you could make to create an Action includes only a page and a user email (or an akid token).

$ curl -i -X POST -H 'Content-type: application/json; charset=utf-8' https://docs.actionkit.com/rest/v1/action/ -d '{ "page": "signup", "email": "signup@example.com" }'
HTTP/1.1 201 CREATED
Date: Mon, 05 Mar 2012 13:19:01 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: text/html; charset=utf-8
Location: https://docs.actionkit.com/rest/v1/signupaction/1/

{"action_id": 21, "akid": ".3.jcWz_1", "rd": 1, "redirect_url": "/cms/thanks/signup/?action_id=21&akid=.3.jcWz_1&rd=1"}

For unauthenticated requests, ActionKit returns only basic information about the newly created Action. You can use the redirect_url to redirect the end-user. Or use the akid token to give them a personalized link to other actions.

While the Location header contains the URI of the newly created action, there is no unauthenticated access to previously created actions.

Authenticated¶

If you submit a POST using authentication, ActionKit will return the full details of the Action, including a link to the User who took the action:

$ curl -u user:password -i -X POST -H 'Content-type: application/json; charset=utf-8' https://docs.actionkit.com/rest/v1/action/ -d '{ "page": "signup", "email": "signup@example.com" }'
HTTP/1.1 201 CREATED
Date: Fri, 09 Mar 2012 11:38:32 GMT
Vary: Cookie,Accept-Encoding,User-Agent
Content-Type: application/json; charset=utf-8
Location: https://docs.actionkit.com/rest/v1/action/24/
Transfer-Encoding: chunked

{
   "akid": ".1.iWxeUd",
   "created_at": "2012-03-09T11:42:53.147877",
   "created_user": false,
   "fields": {},
   "link": null,
   "mailing": null,
   "opq_id": "",
   "page": "/rest/v1/signuppage/10/",
   "referring_mailing": null,
   "referring_user": null,
   "resource_uri": "/rest/v1/action/26/",
   "source": "website",
   "status": "complete",
   "subscribed_user": false,
   "taf_emails_sent": null,
   "type": "Signup",
   "updated_at": "2012-03-09T11:42:53.174844",
   "user": "/rest/v1/user/1/"
 }

There are a couple of fields you shouldn't miss:

• subscribed_user - A boolean indicating if this action subscribed the user, including Users who are resubscribed.
• created_user - A boolean indicating if this action created the user.
• user - a URI to the full User resource.

Stub Payment Accounts¶

ActionKit comes configured with a "Default ActBlue" stub account. You can use a single stub payment account for all of your external donations, or configure multiple stubs with different names if you want to distinguish between several types of external donations, such as varying fund-raising channels, payment processors, or bank accounts. To configure additional accounts, go to the gear menu, then Configure ActionKit->Donation Settings->Payment Accounts->edit, where you can add or change stub accounts.

Once that configuration change is in place, when you use the admin interface to define donation pages you will be able to choose these stubs in the "Payment account" menu.

You can either create dedicated donation pages linked to each stub payment account, or use existing donation pages and override the payment account via the account parameter described below.

Donations made with a stub payment account won't result in a credit card charge -- it's assumed that you've already collected the payment some other way -- but the donation will be recorded as database rows in the core_order and core_transaction tables for use in your site's reports.

You can send 'donation_date' and 'created_at' to control the dates ActionKit will save in core_action and core_order. The logic is similar to that used by Imports:

• created_at - (optional) Use any of the supported date formats (see above) to set the created_at timestamp in core_order, core_transaction, and core_action. If you don't include this column, or it's empty for a given row, ActionKit uses the current timestamp.
• donation_date - (optional) Use any of the supported date formats to set the created_at timestamp in core_order and core_transaction only. Core_action is set to the current time.

These accounts do not support recurring donations.

Donation Action Requests¶

To record individual donations via the REST API, make a POST request to the Action list_endpoint, passing either the name of a donation page linked to a stub payment account, or the name of a regular donation page plus the name of a stub payment account.

You can use unauthenticated requests to create donations, but the response from authenticated requests includes additional information; in particular, only authenticated requests will receive the status value in responses, which is needed to detect failures due to incorrect card_code values.

$ curl -u user:password -i -X POST -H 'Content-type: application/json; charset=utf-8' https://docs.actionkit.com/rest/v1/action/ -d '{ "page": "your_donation_page", "payment_account": "Your Stub Account", "card_num": "4111111111111111", "card_code": "007", "exp_date_month": "12", "exp_date_year": "25", "name": "Jane Doe", "email": "my-api-donor@example.com", "address1": "123 Main Street", "city": "New York", "state": "NY", "zip": "90210",  "amount_other": "123.45" }'

{
  "akid": ".11.sE5Sju",
  "created_at": "2014-02-25T21:38:39.197149",
  "created_user": false,
  "fields": {},
  "id": 48,
  "ip_address": "47.37.134.18",
  "is_forwarded": false,
  "link": null,
  "mailing": null,
  "opq_id": "",
  "page": "/rest/v1/donationpage/15/",
  "redirect_url": "/cms/thanks/your_donation_page?action_id=48&akid=.11.sE5Sju&ar=1&rd=1&total=123.45",
  "referring_mailing": null,
  "referring_user": null,
  "resource_uri": "/rest/v1/donationaction/48/",
  "source": "restful_api",
  "status": "complete",
  "subscribed_user": false,
  "taf_emails_sent": null,
  "type": "Donation",
  "updated_at": "2014-02-25T21:38:39.487840",
  "user": "/rest/v1/user/11/"
}

The "email" field is required. The "name" field is required unless a user with the given email address already exists. The address-related fields are optional and may be skipped if you want to avoid overwriting the user's current location.

The "card_num" value can not be empty, but it does not need need to be a valid credit card number. The last four characters of the value you send will be saved in the core_order table, so you can send the full card number, or just the last four digits, or a placeholder value such as "4111111111111111".

The "card_code" must always contain the stub payment account's verification number, which is typically "007" unless ActionKit support has specifically assigned you a different code.

Products And Candidates¶

You can import product purchases and candidate donations as long as you first set up appropriately-configured donation pages.

You can record purchases of products by selecting those products on the donation page's "Action basics" screen and then including the purchased quantity in a parameter named "product_1". You can record shipping addresses by including fields named "shipping_address1", "shipping_address2", "shipping_city", "shipping_state", and "shipping_zip".

You can record donations to candidates by selecting those candidates on the donation page's "Action basics" screen and then including the donation amount in a parameter named "candidate_1".

Donation Responses¶

A successful request will receive a response containing "status": "complete" as well as other details about the request. The donation may be declined if you provide the wrong card_code, or if you submit the exact same transaction twice in a row; in these cases, the response hash will instead contain "status": "failed".