Remote API

Usage

In order to use the API, you will need to write an application that can connect to the server where Civil Dispatch is located, send a request to it and handle the response it receives from your Civil Dispatch account. Usually (if using PHP) this can be done by using CURL library.

Authentication

In order to use the API, you will need a valid user account for accessing your Civil Dispatch account. The API username and password are the same as your login access to the Admin panel.

Requests

Every API request needs to have an action; that way the system knows what action to perform and what result to return.

Actions that send data to the server (add/edit actions, but not delete actions) have to be requested as POST, while actions that retrieve the data need to be requested as GET. (The exception are "delete" actions, since inputs are IDs only. Those should be submitted as GET.)

At the moment (new actions as added often), Civil Dispatch lets you run the following actions:

  • list_view - returns the list info. Input: List ID
  • list_list - returns a list of lists. Input: comma-separated list of List IDs
  • list_add - adds the list. Input: complete list settings
  • list_edit - edits the list. Input: complete list settings and List ID to edit
  • list_delete - deletes the list. Input: List ID
  • list_delete_list - deletes a list of lists. Input: comma-separated list of List IDs
  • subscriber_view - returns the subscriber info. Input: Subscriber ID or Subscriber Email
  • subscriber_view_email - returns the subscriber info. Input: Subscriber Email
  • subscriber_list - returns a list of subscribers. Input: comma-separated list of Subscriber IDs
  • subscriber_add - adds the subscriber. Input: complete subscriber info with all lists he should belong to from now on
  • subscriber_edit - edits the subscriber. Input: complete subscriber info with all lists he should belong to from now on and Subscriber ID to edit
  • subscriber_delete - deletes the list. Input: Subscriber ID
  • subscriber_delete_list - deletes a list of subscribers. Input: comma-separated list of Subscriber IDs
  • user_view - returns the user info. Input: User ID
  • user_view_email - returns the user info. Input: User email address
  • user_view_username - returns the user info. Input: User username
  • user_list - returns a list of lists. Input: comma-separated list of User IDs
  • user_add - adds the user. Input: complete user info
  • user_edit - edits the user. Input: complete user info and User ID to edit
  • user_delete - deletes the list. Input: User ID
  • user_delete_list - deletes a list of users. Input: comma-separated list of User IDs
  • message_view - returns the message info. Input: Message ID
  • message_list - returns a list of messages. Input: comma-separated list of Message IDs
  • message_add - adds the message. Input: complete message settings
  • message_edit - edits the message. Input: complete message settings and Message ID to edit
  • message_delete - deletes the list. Input: Message ID
  • message_delete_list - deletes a list of lists. Input: comma-separated list of Message IDs
  • campaign_create - adds a new campaign.
  • campaign_send - sends an existing campaign. Input: Campaign ID, Subscriber Email
  • campaign_status - changes the campaign status. Input: Campaign ID
  • campaign_delete - deletes the campaign. Input: Campaign ID
  • campaign_delete_list - deletes a list of campaigns. Input: comma-separated list of Campaign IDs
  • form_view - returns the subscription form info. Input: Subscription Form ID
  • form_list - returns a list of subscription forms. Input: comma-separated list of Subscription Form IDs
  • form_add - adds the subscription form. Input: complete subscription form settings
  • form_edit - edits the subscription form. Input: complete subscription form settings and Subscription Form ID to edit
  • form_delete - deletes the subscription form. Input: Subscription Form ID
  • form_delete_list - deletes a list of subscription forms. Input: comma-separated list of Subscription Form IDs

Result

API can return the results in:

  • serialized format - data is returned in a serialized format and can be decoded with PHP's native unserialize() function
  • JSON format - data is returned in JSON format and can be decoded with json_decode() function (included in PHP since 5.2.0)
  • XML format - write your own XML parser to handle the output

In order to set your favorite output format, change the 'api_output' variable. Possible values are 'serialize', 'xml' and 'json'.

Examples

Examples on how to use each API request can be found in your /docs/api-examples/ folder.