Administrate

Contacts

Contacts represent people in the system.

A contact is a member of the CRM module and provides information about a system contact.

Note: In Administrate, Contacts must have a unique email address. When creating or updating a contact in the CRM if a duplicate email address is supplied then the call will be accepted and a 200 status code will be returned, however the return headers will include X-Duped-Email: yes. This duplicate can then be resolved within the application.

A contact record holds the following information:

  • membership_number
  • last_name
  • tel
  • address_unit
  • contract_notes
  • created_on
  • inactive
  • marketing_lists
  • salutation
  • address_postcode
  • email2
  • id
  • first_name
  • middle_name
  • import_ref
  • tasks
  • address_street
  • organisation
  • company_id
  • department
  • address_locality
  • email
  • job_title
  • dont_mail
  • fax
  • account_id
  • marketing_activity_id
  • lms_bio
  • address_town
  • source2
  • source1
  • is_admin
  • is_tutor
  • tutor_bio
  • dormant
  • is_deleted
  • address_country_id
  • mobile
  • notes
  • overall_attendance
  • is_staff
  • no_third_party
  • address_region
  • created_by_id
  • external_id

Getting Contacts

GET /api/v2/crm/contacts/: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/crm/contacts/6',
                         auth=('<username>', '<password>'))

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts/6     -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts/6';
$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:
{
    "membership_number": null,
    "last_name": "Smith",
    "tel": null,
    "address_unit": null,
    "contract_notes": null,
    "created_on": "2017-02-21T16:13:30",
    "tasks": [],
    "is_staff": false,
    "marketing_lists": [],
    "salutation": null,
    "address_postcode": null,
    "address_street": null,
    "id": 6,
    "custom_fields": {
        "_CustomCheck3": 0,
        "_CustomCheck2": 0,
        "_CustomCheck1": 0,
        "_CustomCheck4": 0,
        "_CustomText1": null,
        "_CustomText3": null,
        "_CustomText2": null,
        "field_2": [],
        "field_1": null
    },
    "first_name": "John",
    "middle_name": null,
    "import_ref": null,
    "email2": null,
    "organisation": null,
    "company_id": 1,
    "source1": null,
    "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,
    "overall_attendance": null,
    "inactive": false,
    "address_locality": null,
    "address_region": null,
    "created_by_id": null,
    "external_id": null
}

Getting more than one Contact

GET /api/v2/crm/contacts
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/crm/contacts',
                         auth=('<username>', '<password>'))

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts     -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts';
$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:
[
    {
        "membership_number": null,
        "last_name": "Smith",
        "tel": null,
        "address_unit": null,
        "contract_notes": null,
        "created_on": "2017-02-21T16:13:30",
        "inactive": false,
        "is_staff": false,
        "salutation": null,
        "address_postcode": null,
        "address_street": null,
        "id": 4,
        "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
    },
    {
        "membership_number": null,
        "last_name": "Bobson",
        "tel": null,
        "address_unit": null,
        "contract_notes": null,
        "created_on": "2017-02-21T16:13:30",
        "inactive": true,
        "is_staff": false,
        "salutation": null,
        "address_postcode": null,
        "address_street": null,
        "id": 5,
        "first_name": "Bob",
        "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
    }
]

Filtering

The results for a list of contacts can be filtered. See Filtering. Contacts also support filtering on custom fields. Simply prefix the custom field with custom_fields. and use the standard filtering syntax.

Example:

GET /api/v2/crm/contacts?custom_fields.field_319__eq=10

Creating Contacts

POST /api/v2/crm/contacts
Required fields:
  • first_name
  • last_name
  • account_id
statuscode 200:no error
statuscode 404:could not create
Using Python:
import json
import requests

data = {u'last_name': u'Smith', u'first_name': u'John', u'inactive': False, u'account_id': 1}

response = requests.post('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts',
                        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/crm/contacts     -H "Content-Type: application/json"     -k -u (login):(password)     -X POST     -d '{"inactive": false, "first_name": "John", "last_name": "Smith", "account_id": 1}'
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts';
$data = array("last_name" => u'Smith', "first_name" => u'John', "inactive" => False, "account_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:
{
    "membership_number": null,
    "last_name": "Smith",
    "tel": null,
    "address_unit": null,
    "contract_notes": null,
    "created_on": "2017-02-21T16:13:30",
    "tasks": [],
    "is_staff": false,
    "marketing_lists": [],
    "salutation": null,
    "address_postcode": null,
    "address_street": null,
    "id": 6,
    "custom_fields": {
        "_CustomCheck3": 0,
        "_CustomCheck2": 0,
        "_CustomCheck1": 0,
        "_CustomCheck4": 0,
        "_CustomText1": null,
        "_CustomText3": null,
        "_CustomText2": null,
        "field_2": [],
        "field_1": null
    },
    "first_name": "John",
    "middle_name": null,
    "import_ref": null,
    "email2": null,
    "organisation": null,
    "company_id": 1,
    "source1": null,
    "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,
    "overall_attendance": null,
    "inactive": false,
    "address_locality": null,
    "address_region": null,
    "created_by_id": null,
    "external_id": null
}

Updating Contacts

PUT /api/v2/crm/contacts/(int: id)
statuscode 200:no error
statuscode 404:does not exist
Using Python:
import json
import requests

data = {u'first_name': u'My new value for first_name'}

response = requests.put('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts/8',
                        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/crm/contacts/8     -H "Content-Type: application/json"     -k -u (login):(password)     -X PUT     -d '{"first_name": "My new value for first_name"}'
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts/8';
$data = array("first_name" => u'My new value for first_name');
$options = array(
'http' => array(
'method'  => 'PUT',
'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:
{
    "membership_number": null,
    "last_name": "Smith",
    "tel": null,
    "address_unit": null,
    "contract_notes": null,
    "created_on": "2017-02-21T16:13:31",
    "tasks": [],
    "is_staff": false,
    "marketing_lists": [],
    "salutation": null,
    "address_postcode": null,
    "address_street": null,
    "id": 8,
    "custom_fields": {
        "_CustomCheck3": 0,
        "_CustomCheck2": 0,
        "_CustomCheck1": 0,
        "_CustomCheck4": 0,
        "_CustomText1": null,
        "_CustomText3": null,
        "_CustomText2": null,
        "field_2": [],
        "field_1": null
    },
    "first_name": "My new value for first_name",
    "middle_name": null,
    "import_ref": null,
    "email2": null,
    "organisation": null,
    "company_id": 1,
    "source1": null,
    "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,
    "overall_attendance": null,
    "inactive": false,
    "address_locality": null,
    "address_region": null,
    "created_by_id": null,
    "external_id": null
}

Deleting Contacts

DELETE /api/v2/crm/contacts/(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/crm/contacts/3',
                         auth=('<username>', '<password>'))

print response.json
Using Curl:
curl https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts/3     -X DELETE -k -u (login):(password)
Using PHP:
<?php
$credentials = '(username):(password)';
$url = 'https://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts/3';
$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:
{
    "membership_number": null,
    "last_name": "Smith",
    "tel": null,
    "address_unit": null,
    "contract_notes": null,
    "created_on": "2017-02-21T16:13:30",
    "tasks": [],
    "is_staff": false,
    "marketing_lists": [],
    "salutation": null,
    "address_postcode": null,
    "address_street": null,
    "id": 3,
    "custom_fields": {
        "_CustomCheck3": 0,
        "_CustomCheck2": 0,
        "_CustomCheck1": 0,
        "_CustomCheck4": 0,
        "_CustomText1": null,
        "_CustomText3": null,
        "_CustomText2": null,
        "field_2": [],
        "field_1": null
    },
    "first_name": "John",
    "middle_name": null,
    "import_ref": null,
    "email2": null,
    "organisation": null,
    "company_id": 1,
    "source1": null,
    "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": true,
    "address_country_id": null,
    "mobile": null,
    "notes": null,
    "overall_attendance": null,
    "inactive": false,
    "address_locality": null,
    "address_region": null,
    "created_by_id": null,
    "external_id": null
}

Authenticating Contacts

There may be occassions when you wish to link one of your users with a particular contact, this can be useful for tracking purchases against a particular user for example.

Administrate does not provide any means for storing hashed passwords on Contacts, so any authentication should take place within the application you wish to integrate with Administrate, and not via the Administrate API.

Example workflow

When a new user is created within your application you should create a matching contact in Administrate and store the contact_id alongside your new user registration.:

Default Workflow for Contacts Auth

Once the user has authenticated with your application and you have retrieved the Administrate contact_id you can then use this with the contacts API to retrieve that user’s contact, or you can use it alongside an event_id to register them as a delegate on an event, and so on.

Important

While you can store data within the custom fields on the contacts API these fields are not encrypted nor hashed. Because of this they should not be used for authentication as your user’s password would be stored in plain-text.