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
Systems¶
Custom Fields¶
CRM¶
- Accounts
- Contacts
- Authenticating Contacts
- Enquiries
- Form Submissions
- Leads
- Marketing Activities
- Marketing Campaigns
- Marketing Lists
- Opportunities
- Fields
- Getting Opportunities
- Getting more than one Opportunity
- Creating an Opportunity
- Updating an Opportunity
- Deleting an Opportunity
- Adding Interests to an Opportunity
- Adding a Document to an Opportunity
- Generating a Quote for an Opportunity
- Getting the PDF for an Opportunity quote
- Sending an Email for an opportunity
- Opportunity Steps
- Source Types
- Tasks
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.