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 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;

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

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,
    "marketing_lists": [],
    "salutation": null,
    "address_postcode": null,
    "email2": 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,
    "tasks": [],
    "address_street": 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,
    "is_tutor": false,
    "tutor_bio": null,
    "dormant": null,
    "is_deleted": false,
    "address_country_id": null,
    "mobile": null,
    "notes": null,
    "overall_attendance": null,
    "is_staff": false,
    "no_third_party": 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 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;

Using Python:

import json
import requests

response = requests.get('http://YOUR-SUBDOMAIN.administrateapp.com/api/v2/crm/contacts',
                         auth=('<username>', '<password>'))

print response.json

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,
        "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,
        "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,
        "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
    },
    {
        "membership_number": null,
        "last_name": "Bobson",
        "tel": null,
        "address_unit": null,
        "contract_notes": null,
        "created_on": "2017-02-21T16:13:30",
        "inactive": true,
        "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,
        "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,
        "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
    }
]

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 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;

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

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,
    "marketing_lists": [],
    "salutation": null,
    "address_postcode": null,
    "email2": 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,
    "tasks": [],
    "address_street": 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,
    "is_tutor": false,
    "tutor_bio": null,
    "dormant": null,
    "is_deleted": false,
    "address_country_id": null,
    "mobile": null,
    "notes": null,
    "overall_attendance": null,
    "is_staff": false,
    "no_third_party": 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 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;

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

Example response:

{
    "membership_number": null,
    "last_name": "Smith",
    "tel": null,
    "address_unit": null,
    "contract_notes": null,
    "created_on": "2017-02-21T16:13:31",
    "inactive": false,
    "marketing_lists": [],
    "salutation": null,
    "address_postcode": null,
    "email2": 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,
    "tasks": [],
    "address_street": 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,
    "is_tutor": false,
    "tutor_bio": null,
    "dormant": null,
    "is_deleted": false,
    "address_country_id": null,
    "mobile": null,
    "notes": null,
    "overall_attendance": null,
    "is_staff": false,
    "no_third_party": 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 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;

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

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,
    "marketing_lists": [],
    "salutation": null,
    "address_postcode": null,
    "email2": 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,
    "tasks": [],
    "address_street": 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,
    "is_tutor": false,
    "tutor_bio": null,
    "dormant": null,
    "is_deleted": true,
    "address_country_id": null,
    "mobile": null,
    "notes": null,
    "overall_attendance": null,
    "is_staff": false,
    "no_third_party": 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.:

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.