Administrate

REST API

Introduction

The Administrate REST API allows developers to hook into Administrate via http requests. The REST API is implemented as JSON over HTTP using the REST commands GET and POST. Since it follows REST principles, each resource has its own URL. We use POST for both creation and updating since the only difference lies in the url request and avoids any confusion between PUT and POST definitions.

API Changes

Any changes introduced that do not affect existing users will be included if needed. In the case that we make changes that would do so otherwise, we will let users know in advance with plenty of notice. It’s best to follow our operational Twitter account (@Adm1nistrateOPS) for notice of changes.

Authentication

Authenticated use of the API is done via HTTP Basic Authentication using existing user credentials. Security for the transport of url requests is provided by SSL. We don’t access via unencrypted transport (non-SSL).

Behaviour

Common behaviours for API v2 and v2.5 are described in the sections listed below

Best Practices

We strongly recommend observing the following best practices when developing against our API:

  • Cache your requests where they make sense. Most training providers don’t update their event schedules or course offerings more than once a day, for example. It will greatly enhance the user experience if you implement simple caching within your client. While we endeavour to make the API as performant as possible, we do rate limit requests, so be prudent about how you access the API.
  • Make sure you have a full staging environment for testing and debugging purposes.
  • Subscribe to our Operational Twitter feed (@Adm1nistrateOps) for news on updates to the API and other aspects of Administrate.
  • When in doubt, first test the calls you’re making via CURL (see below). Administrate support staff can’t assist with technical requirements beyond ensuring the API works as documented and tested via CURL.

A Helpful Guide to Building an E-Commerce Site

So what does this all mean? Administrate aims to be a platform build for integrations in many contexts, but the most common use of our API is for training organisations to build e-commerce websites that are driven by the CRM and training data within Administrate. We’re put together a guide to help see how the API can be used for this purpose.

cURL

We recommend using cURL (http://en.wikipedia.org/wiki/CURL) for testing out the various features that the Administrate REST API offers. If you prefer to use something online, Hurl is another recommended option.

Note

When creating or updating existing records, it is important to set the content-type header to json.

Examples

GET Retrieve a list of fields in account 1

curl -k -u <username>:<password> https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/1

This returns the result as JSON, like the following.

{
    "account_type": "customer",
    "address_country": {
            "id": "AU",
            "name": "Australia"
    },
    "address_locality": null,
    "address_postcode": null,
    "address_region": null,
    "address_street": null,
    "address_town": "City",
    "address_unit": "Address 1",
    "bank_details": null,
    "created": "2009-11-22T00:00:00",
    "email": "[email protected]",
    "external_id": null,
    "id": 1,
    "initial_contact_id": null,
    "is_customer": false,
    "is_deleted": false,
    "name": "somename",
    "notes": null,
    "primary_contact_id": null,
    "tags": null,
    "tel": "+61 2 0000 0000",
    "url": "www.somewebsite.com"
}

POST (create) a new account

curl -k -u <username>:<password> -H "Content-Type: application/json" \
     -d '{"first_name":"Lloyd", "email":"[email protected]"}' \
     -X POST \
     https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts

POST (update) a current account

curl -k -u <username>:<password> -H "Content-Type: application/json" \
     -d '{"first_name":"Lloyd", "email":"[email protected]"}' \
     -X POST \
     https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/123

Note

Pay special attention to the difference in urls. When creating a new account, the url only indicates that we are dealing with /crm/accounts. In the second example, the url points to an already existing entity /crm/accounts/123.

DELETE a current account

curl -k -u <username>:<password> \
     -X DELETE \
     https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/accounts/123

CRM

Events

Documents

Several different document types are stored and/or created by Administrate. These can be accessed using the following methods. The access pattern we recommend is to access the document meta data you need, then construct the URLs to fetch the specific documents you want (or fetch them yourself). Examples of these are provided below.

Orders

Note

This API call and documentation require the Sales Opportunities system from Administrate, which is available to you and will not work with the former lead system Leads. If you are not certain that the CRM -> Sales Opportunity menu item in Administrate displays the “New Opportunities System”, please contact support@getadministrate.com to confirm.

Orders are how you sell products via the API. The orders call is a “helper” method to bring together a workflow that would otherwise require quite a few API calls to implement. Orders signal the intent of a customer to purchase event(s), item(s), and optionally to pay for them. They differ from opportunities in that the customer has made the decision to buy, rather than just being an opportunity to sell.

Time Zones

© Copyright 2013, Eaglewood Systems Limited. Last updated on Jun 26, 2019.