- REST API
- Introduction
- API Changes
- Authentication
- Behaviour
- Best Practices
- cURL
- Systems
- Custom Fields
- CRM
- Events
- Financials
- Documents
- Orders
- Stock
- Time Zones
Delegates¶
Delegates represent a Contacts places on Events in the system.
A delegate is a member of the events module and provides information about a delegate as well as their related event and contact.
A delegate record holds the following information:
- registration_id
- comms_contact
- comms_contact_id
- event_id
- notes
- contact_id
- event
- overall_attendance
- contact
- cancelled_date
- passed
- num_delegates
- id
Getting Delegates¶
- GET /api/v2/event/delegates/:id¶
| statuscode 200: | no error |
|---|---|
| statuscode 404: | does not exist |
Using Python:
import json
import requests
response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates/4',
auth=('<username>', '<password>'))
print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates/4 -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates/4';
$options = array(
'http' => array(
'method' => 'GET',
'header'=> "Accept: application/json\r\n" .
"Authorization: Basic " . base64_encode($credentials)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;
Example response:
{
"registration_id": 1,
"comms_contact": null,
"passed": null,
"event_id": 1,
"notes": "hay",
"contact_id": 1,
"id": 4,
"overall_attendance": null,
"contact": {
"membership_number": null,
"last_name": "Smith",
"tel": null,
"address_unit": null,
"contract_notes": null,
"created_on": "2017-03-14T16:38:23",
"inactive": false,
"is_staff": false,
"salutation": null,
"address_postcode": null,
"address_street": null,
"id": 1,
"first_name": "John",
"middle_name": null,
"import_ref": null,
"address_region": null,
"organisation": null,
"company_id": 1,
"department": null,
"no_third_party": null,
"email": null,
"job_title": null,
"dont_mail": false,
"fax": null,
"account_id": 1,
"marketing_activity_id": null,
"lms_bio": null,
"source2": null,
"address_town": null,
"is_admin": 0,
"is_tutor": false,
"tutor_bio": null,
"dormant": null,
"is_deleted": false,
"address_country_id": null,
"mobile": null,
"notes": null,
"source1": null,
"address_locality": null,
"created_by_id": null,
"external_id": null
},
"cancelled_date": null,
"comms_contact_id": null,
"num_delegates": 1,
"event": {
"personnel_administrator": null,
"personnel_tutor": null,
"code": null,
"personnel_administrator_id": null,
"region_id": null,
"notes": null,
"personnel_tutor_id": null,
"course": null,
"tag": null,
"course_id": null,
"id": 1,
"delegates_max": null,
"venue_id": null,
"start_time": null,
"title": "User Defined",
"personnel": [],
"tax_type": null,
"company_id": null,
"delegates_reserved": 0.0,
"location": null,
"classroom_end": null,
"is_sold_out": false,
"notes2": null,
"event_template_id": null,
"type": "public",
"start_date": null,
"delegates_booked": 1.0,
"account_id": null,
"end_date": null,
"price": null,
"registration_deadline": null,
"tag_id": null,
"classroom_start": null,
"disposition": null,
"is_online": false,
"prices": [],
"delegates_actual": 1,
"account": null,
"is_provisional": false,
"non_working_days": [],
"region": null,
"is_lms": false,
"venue": null,
"overall_attendance": null,
"account_venue": null,
"end_time": null,
"tax_type_id": null,
"is_cancelled": false,
"currency_code": null
}
}
Getting more than one Delegate¶
- GET /api/v2/event/delegates¶
| statuscode 200: | no error |
|---|---|
| statuscode 404: | does not exist |
Using Python:
import json
import requests
response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates',
auth=('<username>', '<password>'))
print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates';
$options = array(
'http' => array(
'method' => 'GET',
'header'=> "Accept: application/json\r\n" .
"Authorization: Basic " . base64_encode($credentials)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;
Example response:
[
{
"registration_id": null,
"comms_contact": null,
"passed": null,
"event_id": 1,
"notes": "hay",
"contact_id": 1,
"id": 2,
"overall_attendance": null,
"contact": {
"membership_number": null,
"last_name": "Smith",
"tel": null,
"address_unit": null,
"contract_notes": null,
"created_on": "2017-03-14T16:38:23",
"inactive": false,
"is_staff": false,
"salutation": null,
"address_postcode": null,
"address_street": null,
"id": 1,
"first_name": "John",
"middle_name": null,
"import_ref": null,
"address_region": null,
"organisation": null,
"company_id": 1,
"department": null,
"no_third_party": null,
"email": null,
"job_title": null,
"dont_mail": false,
"fax": null,
"account_id": 1,
"marketing_activity_id": null,
"lms_bio": null,
"source2": null,
"address_town": null,
"is_admin": 0,
"is_tutor": false,
"tutor_bio": null,
"dormant": null,
"is_deleted": false,
"address_country_id": null,
"mobile": null,
"notes": null,
"source1": null,
"address_locality": null,
"created_by_id": null,
"external_id": null
},
"cancelled_date": null,
"comms_contact_id": null,
"num_delegates": 1,
"event": {
"personnel_administrator": null,
"personnel_tutor": null,
"code": null,
"personnel_administrator_id": null,
"region_id": null,
"notes": null,
"personnel_tutor_id": null,
"course": null,
"tag": null,
"course_id": null,
"id": 1,
"delegates_max": null,
"venue_id": null,
"start_time": null,
"title": "User Defined",
"personnel": [],
"tax_type": null,
"company_id": null,
"delegates_reserved": 0.0,
"location": null,
"classroom_end": null,
"is_sold_out": false,
"notes2": null,
"event_template_id": null,
"type": "public",
"start_date": null,
"delegates_booked": 2.0,
"account_id": null,
"end_date": null,
"price": null,
"registration_deadline": null,
"tag_id": null,
"classroom_start": null,
"disposition": null,
"is_online": false,
"prices": [],
"delegates_actual": null,
"account": null,
"is_provisional": false,
"non_working_days": [],
"region": null,
"is_lms": false,
"venue": null,
"overall_attendance": null,
"account_venue": null,
"end_time": null,
"tax_type_id": null,
"is_cancelled": false,
"currency_code": null
}
},
{
"registration_id": null,
"comms_contact": null,
"passed": null,
"event_id": 1,
"notes": "bee",
"contact_id": 1,
"id": 3,
"overall_attendance": null,
"contact": {
"membership_number": null,
"last_name": "Smith",
"tel": null,
"address_unit": null,
"contract_notes": null,
"created_on": "2017-03-14T16:38:23",
"inactive": false,
"is_staff": false,
"salutation": null,
"address_postcode": null,
"address_street": null,
"id": 1,
"first_name": "John",
"middle_name": null,
"import_ref": null,
"address_region": null,
"organisation": null,
"company_id": 1,
"department": null,
"no_third_party": null,
"email": null,
"job_title": null,
"dont_mail": false,
"fax": null,
"account_id": 1,
"marketing_activity_id": null,
"lms_bio": null,
"source2": null,
"address_town": null,
"is_admin": 0,
"is_tutor": false,
"tutor_bio": null,
"dormant": null,
"is_deleted": false,
"address_country_id": null,
"mobile": null,
"notes": null,
"source1": null,
"address_locality": null,
"created_by_id": null,
"external_id": null
},
"cancelled_date": null,
"comms_contact_id": null,
"num_delegates": 1,
"event": {
"personnel_administrator": null,
"personnel_tutor": null,
"code": null,
"personnel_administrator_id": null,
"region_id": null,
"notes": null,
"personnel_tutor_id": null,
"course": null,
"tag": null,
"course_id": null,
"id": 1,
"delegates_max": null,
"venue_id": null,
"start_time": null,
"title": "User Defined",
"personnel": [],
"tax_type": null,
"company_id": null,
"delegates_reserved": 0.0,
"location": null,
"classroom_end": null,
"is_sold_out": false,
"notes2": null,
"event_template_id": null,
"type": "public",
"start_date": null,
"delegates_booked": 2.0,
"account_id": null,
"end_date": null,
"price": null,
"registration_deadline": null,
"tag_id": null,
"classroom_start": null,
"disposition": null,
"is_online": false,
"prices": [],
"delegates_actual": null,
"account": null,
"is_provisional": false,
"non_working_days": [],
"region": null,
"is_lms": false,
"venue": null,
"overall_attendance": null,
"account_venue": null,
"end_time": null,
"tax_type_id": null,
"is_cancelled": false,
"currency_code": null
}
}
]
Creating Delegates¶
- POST /api/v2/event/delegates¶
Required fields:
- event_id
- contact_id
Note: When creating delegates you need to check for possible overbooking the event. This api call is not preventing overbooking on the event. To check if you are not going to overbook the event please use the get private/public events endpoint.
| statuscode 200: | no error |
|---|---|
| statuscode 404: | could not create |
Using Python:
import json
import requests
data = {u'event_id': 1, u'notes': u'hay', u'contact_id': 1}
response = requests.post('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates',
data=json.dumps(data),
headers={'content-type': 'application/json'},
auth=('<username>', '<password>'))
print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates -H "Content-Type: application/json" -k -u (login):(password) -X POST -d '{"event_id": 1, "notes": "hay", "contact_id": 1}'
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates';
$data = array("event_id" => 1, "notes" => u'hay', "contact_id" => 1);
$options = array(
'http' => array(
'method' => 'POST',
'content' => json_encode($data),
'header'=> "Content-Type: application/json\r\n" .
"Accept: application/json\r\n" .
"Authorization: Basic " . base64_encode($credentials)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;
Example response:
{
"registration_id": 1,
"comms_contact": null,
"passed": null,
"event_id": 1,
"notes": "hay",
"contact_id": 1,
"id": 4,
"overall_attendance": null,
"contact": {
"membership_number": null,
"last_name": "Smith",
"tel": null,
"address_unit": null,
"contract_notes": null,
"created_on": "2017-03-14T16:38:23",
"inactive": false,
"is_staff": false,
"salutation": null,
"address_postcode": null,
"address_street": null,
"id": 1,
"first_name": "John",
"middle_name": null,
"import_ref": null,
"address_region": null,
"organisation": null,
"company_id": 1,
"department": null,
"no_third_party": null,
"email": null,
"job_title": null,
"dont_mail": false,
"fax": null,
"account_id": 1,
"marketing_activity_id": null,
"lms_bio": null,
"source2": null,
"address_town": null,
"is_admin": 0,
"is_tutor": false,
"tutor_bio": null,
"dormant": null,
"is_deleted": false,
"address_country_id": null,
"mobile": null,
"notes": null,
"source1": null,
"address_locality": null,
"created_by_id": null,
"external_id": null
},
"cancelled_date": null,
"comms_contact_id": null,
"num_delegates": 1,
"event": {
"personnel_administrator": null,
"personnel_tutor": null,
"code": null,
"personnel_administrator_id": null,
"region_id": null,
"notes": null,
"personnel_tutor_id": null,
"course": null,
"tag": null,
"course_id": null,
"id": 1,
"delegates_max": null,
"venue_id": null,
"start_time": null,
"title": "User Defined",
"personnel": [],
"tax_type": null,
"company_id": null,
"delegates_reserved": 0.0,
"location": null,
"classroom_end": null,
"is_sold_out": false,
"notes2": null,
"event_template_id": null,
"type": "public",
"start_date": null,
"delegates_booked": 1.0,
"account_id": null,
"end_date": null,
"price": null,
"registration_deadline": null,
"tag_id": null,
"classroom_start": null,
"disposition": null,
"is_online": false,
"prices": [],
"delegates_actual": 1,
"account": null,
"is_provisional": false,
"non_working_days": [],
"region": null,
"is_lms": false,
"venue": null,
"overall_attendance": null,
"account_venue": null,
"end_time": null,
"tax_type_id": null,
"is_cancelled": false,
"currency_code": null
}
}
Deleting Delegates¶
- DELETE /api/v2/event/delegates/(int: id)¶
| statuscode 200: | deleted entity successfully |
|---|---|
| statuscode 404: | entity not found |
Using Python:
import json
import requests
response = requests.delete('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates/1',
auth=('<username>', '<password>'))
print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates/1 -X DELETE -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/event/delegates/1';
$options = array(
'http' => array(
'method' => 'DELETE',
'header'=> "Accept: application/json\r\n" .
"Authorization: Basic " . base64_encode($credentials)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
echo $result;
Example response:
{
"registration_id": null,
"comms_contact": null,
"passed": null,
"event_id": 1,
"notes": "hay",
"contact_id": 1,
"id": 1,
"overall_attendance": null,
"contact": {
"membership_number": null,
"last_name": "Smith",
"tel": null,
"address_unit": null,
"contract_notes": null,
"created_on": "2017-03-14T16:38:23",
"inactive": false,
"is_staff": false,
"salutation": null,
"address_postcode": null,
"address_street": null,
"id": 1,
"first_name": "John",
"middle_name": null,
"import_ref": null,
"address_region": null,
"organisation": null,
"company_id": 1,
"department": null,
"no_third_party": null,
"email": null,
"job_title": null,
"dont_mail": false,
"fax": null,
"account_id": 1,
"marketing_activity_id": null,
"lms_bio": null,
"source2": null,
"address_town": null,
"is_admin": 0,
"is_tutor": false,
"tutor_bio": null,
"dormant": null,
"is_deleted": false,
"address_country_id": null,
"mobile": null,
"notes": null,
"source1": null,
"address_locality": null,
"created_by_id": null,
"external_id": null
},
"cancelled_date": null,
"comms_contact_id": null,
"num_delegates": 1,
"event": {
"personnel_administrator": null,
"personnel_tutor": null,
"code": null,
"personnel_administrator_id": null,
"region_id": null,
"notes": null,
"personnel_tutor_id": null,
"course": null,
"tag": null,
"course_id": null,
"id": 1,
"delegates_max": null,
"venue_id": null,
"start_time": null,
"title": "User Defined",
"personnel": [],
"tax_type": null,
"company_id": null,
"delegates_reserved": 0.0,
"location": null,
"classroom_end": null,
"is_sold_out": false,
"notes2": null,
"event_template_id": null,
"type": "public",
"start_date": null,
"delegates_booked": 0.0,
"account_id": null,
"end_date": null,
"price": null,
"registration_deadline": null,
"tag_id": null,
"classroom_start": null,
"disposition": null,
"is_online": false,
"prices": [],
"delegates_actual": null,
"account": null,
"is_provisional": false,
"non_working_days": [],
"region": null,
"is_lms": false,
"venue": null,
"overall_attendance": null,
"account_venue": null,
"end_time": null,
"tax_type_id": null,
"is_cancelled": false,
"currency_code": null
}
}
Naming Unnamed Delegates¶
Using the REST API, we can ‘name’ unnamed delegates. Unnamed delegate rows have no contact_id, but instead have a value num_places. Naming a delegate will decrement the num_places attribute, and create a new ‘named’ delegate row. If the unnamed delegate has a num_places of 0 after this operation, it is deleted.
- POST /api/v2/event/delegates/(int: id)/name¶
Required Fields
- contact_id
| statuscode 200: | no error |
|---|---|
| statuscode 400: | no contact_id supplied |
| statuscode 404: | delegate or contact do not exist |
Using Curl:
curl -k -u (user):(password) https://YOUR-SUBDOMAIN/api/v2/event/delegates/1/name \
-H 'Content-type: application/json' \
-d '{
"contact_id": 47403
}'
Example Response
{
"event_id":1,
"notes":null,
"contact_id":47403,
"event":{
"personnel_administrator":null,
"personnel_tutor":null,
"code":null,
"personnel_administrator_id":null,
"region_id":null,
"price":null,
"course":null,
"tag":null,
"course_id":null,
"id":1,
"delegates_max":null,
"venue_id":null,
"title":null,
"personnel":[
],
"tax_type":null,
"company_id":null,
"location":null,
"type":"public",
"start_date":null,
"end_time":null,
"account_id":null,
"end_date":null,
"start_time":null,
"tag_id":null,
"disposition":null,
"delegates_actual":null,
"account":null,
"is_provisional":null,
"non_working_days":[
],
"region":null,
"is_lms":false,
"venue":null,
"personnel_tutor_id":null,
"tax_type_id":null,
"currency_code":null
},
"contact":{
"membership_number":null,
"last_name":"Smith",
"tel":null,
"address_unit":null,
"contract_notes":null,
"created_on":"2013-10-30T14:05:00",
"inactive":false,
"salutation":null,
"address_postcode":null,
"address_street":null,
"id":47403,
"first_name":"John",
"middle_name":null,
"import_ref":null,
"address_region":null,
"organisation":null,
"company_id":1,
"department":null,
"address_locality":null,
"email":null,
"job_title":null,
"dont_mail":false,
"fax":null,
"account_id":1,
"marketing_activity_id":null,
"lms_bio":null,
"address_town":null,
"source2":null,
"source1":null,
"is_admin":0,
"user_id":null,
"is_tutor":false,
"tutor_bio":null,
"dormant":null,
"is_deleted":false,
"address_country_id":null,
"mobile":null,
"notes":null,
"is_staff":false,
"no_third_party":null,
"created_by_id":null,
"external_id":null
},
"id":1,
"num_delegates": 1
}
Delegate Scores¶
Viewing Scores¶
- GET /api/v2/event/delegates/:id/scores¶
Example Response:
[
{
mapping: {
label: "Date Of Exam",
id: 137,
type_id: 3
},
value: "2014-02-12"
},
{
mapping: {
label: "Attended Exam?",
id: 138,
type_id: 1
},
value: "on"
},
{
mapping: {
label: "Score",
id: 139,
type_id: 9
},
value: "91"
}
]
Setting Scores¶
Scores can be set by POSTing a dictionary of mapping_id:value pairs to the a specific delegates’ /scores endpoint.
The mappings which are available to each delegate depend on the event that they are registered to, and can be checked using the following series of API calls:
> /api/v2/event/public_event/<id>
From this, you can retrieve the event_template_id. Then,
> /api/v2/system/custom_template/<id>
This will include a list of mappings including their ID’s and types.
- POST /api/v2/event/delegates/:id/scores¶
Using cURL:
curl https://YOUR-SUBDOMAIN/api/v2/event/delegates/(id)/scores \
-v -u (login):(password) \
-X POST \
-H "Content-type: application/json" \
-d {"137": "2014-10-10", \
"138": "on", \
"139": "87", \
}'
Example Response:
[
{
mapping: {
label: "Date Of Exam",
id: 137,
type_id: 3
},
value: "2014-10-10"
},
{
mapping: {
label: "Attended Exam?",
id: 138,
type_id: 1
},
value: "on"
},
{
mapping: {
label: "Score",
id: 139,
type_id: 9
},
value: "87"
}
]
REST API
Administrate API Events - Delegates
Administrate API Events - Delegates