FranchiseMailer

REST API Documentation

Getting Started

Get started in minutes, follow the simple steps below:

API requests are submitted by sending a HTTPS request to a specific service URL. Request parameters are encoded in the query string. The general service URL is https://api.franchisemailer.co.uk/v1
 

Authentication

Authentication with the API is done using the Access and Secret keys, given on a per account basis as well as IP address validation.

To make an authenticated request, follow these steps:


Requests made with invalid credentials, an invalid request date value or non whitelisted IP will receive an HTTP 403 - Forbidden response.

PHP Example:
$accesskey = 'b6b581087d3a65b71f119e4db6efa6b7';
$secretkey = '7790b9c0a39bf5cffde1da8851f25b5e7fb21a95';

function api_call($method, $url, $data) {
    global $accesskey, $secretkey;
   
    $headers = array("accesskey: $accesskey", "requestdate: ".gmdate('r'), "hmac: ".hash_hmac('sha1', gmdate('r'), $secretkey), "Expect: ");
                    
    $ch = curl_init('https://api.franchisemailer.co.uk/v1'.$url);

    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 0);
    curl_setopt($ch, CURLOPT_TIMEOUT, 300);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
   
    switch (strtolower($method)) {
        case "get":
            curl_setopt($ch, CURLOPT_HTTPGET, true);
            break;
        case "post":
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
            break;
        case "put":
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
            curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
            break;
        case "delete":
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
            break;
    }
   
    curl_setopt($ch, CURLINFO_HEADER_OUT, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
   
    return $result = curl_exec($ch);       
    curl_close($ch);
}

Offices API

Refers to stores, branches, restaurants, outlets etc

List Offices - Returns a list of all offices

GEThttps://api.franchisemailer.co.uk/v1/offices

Response Parameters:
ParameterDescription
idThe unique ID of the office
nameThe name of the office
propertyThe property name / number
streetThe street name
areaThe area the office is located
townThe town the office is located in
countyThe county the office is located in
post_codeThe office post code
telephoneThe office telephone number
faxThe office fax number
emailThe office email address
websiteThe office local website address / local landing page
post_code_allocationA comma separated list of post code areas/districts allocated to the office

PHP Example Code:
api_call('GET','/offices');

JSON Example Response:
{
    "status": "success",
    "data": {
        "offices": [
            {
                "id": "1",
                "name": "Worthing",
                "property": "118",
                "street": "Long Street",
                "area": "Tarring",
                "town": "Worthing",
                "county": "West Sussex",
                "post_code": "BN14 8AD",
                "telephone": "01903 123 456",
                "fax": "01903 123 456",
                "email": "worthing@yourfranchise.co.uk",
                "website": "http://www.yourfranchise.co.uk/worthing",
                "post_code_allocation": "BN1,BN2,BN3"
            }
        ]
    }
}

Offices API

Refers to stores, branches, restaurants, outlets etc

Create Office - Creates a new office

POSThttps://api.franchisemailer.co.uk/v1/offices

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
nameThe name of the officerequired -
propertyThe property name / number--
streetThe street name--
areaThe area the office is located--
townThe town the office is located in--
countyThe county the office is located in--
post_codeThe office post code--
telephoneThe office telephone number--
faxThe office fax number--
emailThe office email address--
websiteThe office local website address / local landing page--
post_code_allocationA comma separated list of post code areas/districts allocated to the office--

Response Parameters:
ParameterDescription
idThe unique ID of the office
nameThe name of the office
propertyThe property name / number
streetThe street name
areaThe area the office is located
townThe town the office is located in
countyThe county the office is located in
post_codeThe office post code
telephoneThe office telephone number
faxThe office fax number
emailThe office email address
websiteThe office local website address / local landing page
post_code_allocationA comma separated list of post code areas/districts allocated to the office

Offices API

Refers to stores, branches, restaurants, outlets etc

Create Office - Creates a new office

POSThttps://api.franchisemailer.co.uk/v1/offices

PHP Example Code:
$params = array(
    "name" => "Worthing",
    "property" => "118",
    "street" => "Long Street",
    "area" => "Tarring",
    "town" => "Worthing",
    "county" => "West Sussex",
    "post_code" => "BN14 8AD",
    "telephone" => "01903 123 456",
    "fax" => "01903 123 456",
    "email" => "worthing@yourfranchise.co.uk",
    "website" => "http://www.yourfranchise.co.uk/worthing",
    "post_code_allocation" => "BN1,BN2,BN3"
);
api_call('POST','/offices', $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "office": {
            "id": "1",
            "name": "Worthing",
            "property": "118",
            "street": "Long Street",
            "area": "Tarring",
            "town": "Worthing",
            "county": "West Sussex",
            "post_code": "BN14 8AD",
            "telephone": "01903 123 456",
            "fax": "01903 123 456",
            "email": "worthing@yourfranchise.co.uk",
            "website": "http://www.yourfranchise.co.uk/worthing",
            "post_code_allocation": "BN1,BN2,BN3"
        }
    }
}

Offices API

Refers to stores, branches, restaurants, outlets etc

Get Office - Gets an office specified by the {office_id} parameter

GEThttps://api.franchisemailer.co.uk/v1/offices/{office_id}

Response Parameters:
ParameterDescription
idThe unique ID of the office
nameThe name of the office
propertyThe property name / number
streetThe street name
areaThe area the office is located
townThe town the office is located in
countyThe county the office is located in
post_codeThe office post code
telephoneThe office telephone number
faxThe office fax number
emailThe office email address
websiteThe office local website address / local landing page
post_code_allocationA comma separated list of post code areas/districts allocated to the office

PHP Example Code:
$office_id = '1';
api_call('GET','/offices/'.$office_id);

JSON Example Response:
{
    "status": "success",
    "data": {
        "office": {
            "id": "1",
            "name": "Worthing",
            "property": "118",
            "street": "Long Street",
            "area": "Tarring",
            "town": "Worthing",
            "county": "West Sussex",
            "post_code": "BN14 8AD",
            "telephone": "01903 123 456",
            "fax": "01903 123 456",
            "email": "worthing@yourfranchise.co.uk",
            "website": "http://www.yourfranchise.co.uk/worthing",
            "post_code_allocation": "BN1,BN2,BN3"
        }
    }
}

Offices API

Refers to stores, branches, restaurants, outlets etc

Update Office - Updates an office specified by the {office_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/offices/{office_id}

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
nameThe name of the office--
propertyThe property name / number--
streetThe street name--
areaThe area the office is located--
townThe town the office is located in--
countyThe county the office is located in--
post_codeThe office post code--
telephoneThe office telephone number--
faxThe office fax number--
emailThe office email address--
websiteThe office local website address / local landing page--
post_code_allocationA comma separated list of post code areas/districts allocated to the office--

Response Parameters:
ParameterDescription
idThe unique ID of the office
nameThe name of the office
propertyThe property name / number
streetThe street name
areaThe area the office is located
townThe town the office is located in
countyThe county the office is located in
post_codeThe office post code
telephoneThe office telephone number
faxThe office fax number
emailThe office email address
websiteThe office local website address / local landing page
post_code_allocationA comma separated list of post code areas/districts allocated to the office

Offices API

Refers to stores, branches, restaurants, outlets etc

Update Office - Updates an office specified by the {office_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/offices/{office_id}

PHP Example Code:
$office_id = '1';
$params = array(
    "name" => "Worthing",
    "property" => "118",
    "street" => "Long Street",
    "area" => "Tarring",
    "town" => "Worthing",
    "county" => "West Sussex",
    "post_code" => "BN14 8AD",
    "telephone" => "01903 123 456",
    "fax" => "01903 123 456",
    "email" => "worthing@yourfranchise.co.uk",
    "website" => "http://www.yourfranchise.co.uk/worthing",
    "post_code_allocation" => "BN1,BN2,BN3"
);
api_call('PUT','/offices/'.$office_id, $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "office": {
            "id": "1",
            "name": "Worthing",
            "property": "118",
            "street": "Long Street",
            "area": "Tarring",
            "town": "Worthing",
            "county": "West Sussex",
            "post_code": "BN14 8AD",
            "telephone": "01903 123 456",
            "fax": "01903 123 456",
            "email": "worthing@yourfranchise.co.uk",
            "website": "http://www.yourfranchise.co.uk/worthing",
            "post_code_allocation": "BN1,BN2,BN3"
        }
    }
}

Offices API

Refers to stores, branches, restaurants, outlets etc

Delete Office - Deletes an office specified by the {office_id} parameter

DELETEhttps://api.franchisemailer.co.uk/v1/offices/{office_id}

PHP Example Code:
$office_id = '1';
api_call('DELETE','/offices/'.$office_id);

JSON Example Response:
{
    "status": "success",
    "data": null
}

Users API

For the management of system users only, for general contacts use the contacts API

List Users - Returns a list of all users

GEThttps://api.franchisemailer.co.uk/v1/users

Response Parameters:
ParameterDescription
idThe unique ID of the user
usernameThe users username
first_nameThe users first name
last_nameThe users last name
emailThe users email address
telephoneThe users telephone number
job_titleThe users job title
activeThe users account status
officesA comma separated list of office ID's that the user can access and send from
last_loginThe data and time the user last logged in (ISO-8601)
last_password_changeThe date the users password was last changed (ISO-8601)

PHP Example Code:
api_call('GET','/users');

JSON Example Response:
{
    "status": "success",
    "data": {
        "users": [
            {
                "id": "1",
                "username": "joe.bloggs",
                "first_name": "Joe",
                "last_name": "Bloggs",
                "email": "job.bloggs@yourfranchise.co.uk",
                "telephone": "01903 123 456",
                "job_title": "Marketing Director",
                "active": "true",
                "offices": "1,3,4",
                "last_login": "2013-01-31T13:52:45+00:00",
                "last_password_change": "2013-01-31T13:52:45+00:00"
            }
        ]
    }
}

Users API

For the management of system users only, for general contacts use the contacts API

Create User - Creates a new user

POSThttps://api.franchisemailer.co.uk/v1/users

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
usernameA unique usernamerequired -
passwordThe users password (plain text)required -
first_nameThe users first namerequired -
last_nameThe users last namerequired -
emailThe users email addressrequired -
telephoneThe users telephone number--
job_titleThe users job title--
activeThe users account statusrequired true or falsefalse
officesA comma separated list of office ID'srequired Only digits and commas accepted-

Response Parameters:
ParameterDescription
idThe unique ID of the user
usernameA unique username
first_nameThe users first name
last_nameThe users last name
emailThe users email address
telephoneThe users telephone number
job_titleThe users job title
activeThe users account status
officesA comma separated list of office ID's that the user can access and send from
last_loginThe data and time the user last logged in (ISO-8601)
last_password_changeThe date the users password was last changed (ISO-8601)

Users API

For the management of system users only, for general contacts use the contacts API

Create User - Creates a new user

POSThttps://api.franchisemailer.co.uk/v1/users

PHP Example Code:
$params = array(
    "username" => "joe.bloggs",
    "password" => "Qwertyu1",
    "first_name" => "Joe",
    "last_name" => "Bloggs",
    "email" => "job.bloggs@yourfranchise.co.uk",
    "telephone" => "01903 123 456",
    "job_title" => "Marketing Director",
    "active" => "true",
    "offices" => "1,3,4"
);
api_call('POST','/users', $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "user": {
            "id": "1",
            "username": "joe.bloggs",
            "first_name": "Joe",
            "last_name": "Bloggs",
            "email": "job.bloggs@yourfranchise.co.uk",
            "telephone": "01903 123 456",
            "job_title": "Marketing Director",
            "active": "true",
            "offices": "1,3,4",
            "last_login": "",
            "last_password_change": ""
        }
    }
}

Users API

For the management of system users only, for general contacts use the contacts API

Get User - Gets a user specified by the {user_id} parameter

GEThttps://api.franchisemailer.co.uk/v1/users/{user_id}

Response Parameters:
ParameterDescription
idThe unique ID of the user
usernameThe users username
first_nameThe users first name
last_nameThe users last name
emailThe users email address
telephoneThe users telephone number
job_titleThe users job title
activeThe users account status
officesA comma separated list of office ID's that the user can access and send from
last_loginThe data and time the user last logged in (ISO-8601)
last_password_changeThe date the users password was last changed (ISO-8601)

PHP Example Code:
$user_id = '1';
api_call('GET','/users/'.$user_id);

JSON Example Response:
{
    "status": "success",
    "data": {
        "user": {
            "id": "1",
            "username": "joe.bloggs",
            "first_name": "Joe",
            "last_name": "Bloggs",
            "email": "job.bloggs@yourfranchise.co.uk",
            "telephone": "01903 123 456",
            "job_title": "Marketing Director",
            "active": "true",
            "offices": "1,3,4",
            "last_login": "2013-01-31T13:52:45+00:00",
            "last_password_change": "2013-01-31T13:52:45+00:00"
        }
    }
}

Users API

For the management of system users only, for general contacts use the contacts API

Update User - Updates a user specified by the {user_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/users/{user_id}

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
usernameA unique username--
passwordThe users password (plain text)--
first_nameThe users first name--
last_nameThe users last name--
emailThe users email address--
telephoneThe users telephone number--
job_titleThe users job title--
activeThe users account statustrue or false-
officesA comma separated list of office ID'sOnly digits and commas accepted-

Response Parameters:
ParameterDescription
idThe unique ID of the user
usernameA unique username
first_nameThe users first name
last_nameThe users last name
emailThe users email address
telephoneThe users telephone number
job_titleThe users job title
activeThe users account status
officesA comma separated list of office ID's that the user can access and send from
last_loginThe data and time the user last logged in (ISO-8601)
last_password_changeThe date the users password was last changed (ISO-8601)

Users API

For the management of system users only, for general contacts use the contacts API

Update User - Updates a user specified by the {user_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/users/{user_id}

PHP Example Code:
$user_id = '1';
$params = array(
    "username" => "joe.bloggs",
    "password" => "Qwertyu1",
    "first_name" => "Joe",
    "last_name" => "Bloggs",
    "email" => "job.bloggs@yourfranchise.co.uk",
    "telephone" => "01903 123 456",
    "job_title" => "Marketing Director",
    "active" => "true",
    "offices" => "1,3,4"
);
api_call('PUT','/users/'.$user_id, $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "user": {
            "id": "1",
            "username": "joe.bloggs",
            "first_name": "Joe",
            "last_name": "Bloggs",
            "email": "job.bloggs@yourfranchise.co.uk",
            "telephone": "01903 123 456",
            "job_title": "Marketing Director",
            "active": "true",
            "offices": "1,3,4",
            "last_login": "2013-01-31T13:52:45+00:00",
            "last_password_change": "2013-01-31T13:52:45+00:00"
        }
    }
}

Users API

For the management of system users only, for general contacts use the contacts API

Delete User - Deletes a user specified by the {user_id} parameter

DELETEhttps://api.franchisemailer.co.uk/v1/users/{user_id}

PHP Example Code:
$user_id = '1';
api_call('DELETE','/users/'.$user_id);

JSON Example Response:
{
    "status": "success",
    "data": null
}

Contacts API

List Contacts - Returns a list of all contacts

GEThttps://api.franchisemailer.co.uk/v1/contacts?office={office_id}&group={group_id}&limit=500&offset=0

Response Parameters:
ParameterDescription
idThe unique ID of the contact
titleThe contacts title
first_nameThe contacts first name
middle_nameThe contacts middle name
last_nameThe contacts last name
addresseeThe preferred way to address the contact
date_of_birthThe contacts date of birth (ISO-8601)
genderThe contacts gender
telephoneThe contacts telephone number
mobileThe contacts mobile number
faxThe contacts fax number
emailThe contacts email address
websiteThe contacts website address
companyThe contacts company name
job_titleThe contacts job title
propertyThe contacts property name / number
streetThe contacts street name
areaThe area the contact is located
townThe town the contact is located in
countyThe county the contact is located in
post_codeThe contacts post code
countryThe contacts country code (ISO-3166-1 alpha-2)
statusThe contacts status
officeThe office ID the contact belongs to
groupsA comma separated list of contact group ID's that the contact is assigned to
common_groupsA comma separated list of common contact group ID's that the contact is assigned to
custom_fieldsThe contacts custom fields (id, value)

Contacts API

List Contacts - Returns a list of all contacts

GEThttps://api.franchisemailer.co.uk/v1/contacts?office={office_id}&group={group_id}&limit=500&offset=0

PHP Example Code:
$office_id = '1';
$group_id = '1';
api_call('GET','/contacts?office='.$office_id.'&group='.$group_id.'&limit=500&offset=0');

JSON Example Response:
{
    "status": "success",
    "meta": {
        "limit": 500,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "data": {
        "contacts": [
            {
                "id": "1",
                "title": "Mr",
                "first_name": "Joe",
                "middle_name": "Michael",
                "last_name": "Bloggs",
                "addressee": "Mr Joe Bloggs",
                "date_of_birth": "31/01/1980",
                "gender": "Male",
                "telephone": "01903 123 456",
                "mobile": "07123456789",
                "fax": "01903 123 456",
                "email": "job.bloggs@example.com",
                "website": "http://www.example.com",
                "company": "JB Trading",
                "job_title": "Sales Director",
                "property": "118",
                "street": "Long Street",
                "area": "Tarring",
                "town": "Worthing",
                "county": "West Sussex",
                "post_code": "BN14 8AD",
                "country": "GB",
                "status": "Permitted",
                "office": "1",
                "groups": "1,3,4",
                "common_groups": "1,3,4",
                "custom_fields": {
                    "1": "£30,000"
                }
            }
        ]
    }
}

Contacts API

Create Contact - Creates a new contact

POSThttps://api.franchisemailer.co.uk/v1/contacts

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
titleThe contacts title--
first_nameThe contacts first name--
middle_nameThe contacts middle name--
last_nameThe contacts last name--
addresseeThe preferred way to address the contact--
date_of_birthThe contacts date of birthISO-8601-
genderThe contacts genderMale or Female-
telephoneThe contacts telephone number--
mobileThe contacts mobile number--
faxThe contacts fax number--
emailThe contacts email addressrequired -
websiteThe contacts website address--
companyThe contacts company name--
job_titleThe contacts job title--
propertyThe contacts property name / number--
streetThe contacts street name--
areaThe area the contact is located--
townThe town the contact is located in--
countyThe county the contact is located in--
post_codeThe contacts post code--
countryThe contacts country codeISO-3166-1 alpha-2/3-
statusThe contacts statusrequired Permitted, Dormant or ExcludedPermitted
officeThe office ID the contact belongs torequired 0 can be used to auto allocate as long as offices have been allocated post code areas/districts-
groupsA comma separated list of contact group ID'srequired Or use the common group parameter instead-
common_groupsA comma separated list of common contact group ID'sWill be ignored if group parameter is set and not empty-
custom_fieldsThe contacts custom fields (id, value)--

Contacts API

Create Contact - Creates a new contact

POSThttps://api.franchisemailer.co.uk/v1/contacts

Response Parameters:
ParameterDescription
idThe unique ID of the contact
titleThe contacts title
first_nameThe contacts first name
middle_nameThe contacts middle name
last_nameThe contacts last name
addresseeThe preferred way to address the contact
date_of_birthThe contacts date of birth (ISO-8601)
genderThe contacts gender
telephoneThe contacts telephone number
mobileThe contacts mobile number
faxThe contacts fax number
emailThe contacts email address
websiteThe contacts website address
companyThe contacts company name
job_titleThe contacts job title
propertyThe contacts property name / number
streetThe contacts street name
areaThe area the contact is located
townThe town the contact is located in
countyThe county the contact is located in
post_codeThe contacts post code
countryThe contacts country code (ISO-3166-1 alpha-2)
statusThe contacts status
officeThe office ID the contact belongs to
groupsA comma separated list of contact group ID's that the contact is assigned to
common_groupsA comma separated list of common contact group ID's that the contact is assigned to
custom_fieldsThe contacts custom fields (id, value)

Contacts API

Create Contact - Creates a new contact

POSThttps://api.franchisemailer.co.uk/v1/contacts

PHP Example Code:
$params = array(
    "title" => "Mr",
    "first_name" => "Joe",
    "middle_name" => "Michael",
    "last_name" => "Bloggs",
    "addressee" => "Mr Joe Bloggs",
    "date_of_birth" => "2013-01-31",
    "gender" => "Male",
    "telephone" => "01903 123 456",
    "mobile" => "07123456789",
    "fax" => "01903 123 456",
    "email" => "job.bloggs@example.com",
    "website" => "http://www.example.com",
    "company" => "JB Trading",
    "job_title" => "Sales Director",
    "property" => "118",
    "street" => "Long Street",
    "area" => "Tarring",
    "town" => "Worthing",
    "county" => "West Sussex",
    "post_code" => "BN14 8AD",
    "country" => "GB",
    "status" => "Permitted",
    "office" => "1",
    "groups" => "1,3,4",
    "common_groups" => "1,3,4",
    "custom_fields" => array(
        1 => "£30,000"
    )
);
api_call('POST','/contacts', $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "contact": {
            "id": "1",
            "title": "Mr",
            "first_name": "Joe",
            "middle_name": "Michael",
            "last_name": "Bloggs",
            "addressee": "Mr Joe Bloggs",
            "date_of_birth": "2013-01-31",
            "gender": "Male",
            "telephone": "01903 123 456",
            "mobile": "07123456789",
            "fax": "01903 123 456",
            "email": "job.bloggs@example.com",
            "website": "http://www.example.com",
            "company": "JB Trading",
            "job_title": "Sales Director",
            "property": "118",
            "street": "Long Street",
            "area": "Tarring",
            "town": "Worthing",
            "county": "West Sussex",
            "post_code": "BN14 8AD",
            "country": "GB",
            "status": "Permitted",
            "office": "1",
            "groups": "1,3,4",
            "common_groups": "1,3,4",
            "custom_fields": {
                "1": "£30,000"
            }
        }
    }
}

Contacts API

Get Contact - Gets a contact specified by the {contact_id} parameter

GEThttps://api.franchisemailer.co.uk/v1/contacts/{contact_id}

Response Parameters:
ParameterDescription
idThe unique ID of the contact
titleThe contacts title
first_nameThe contacts first name
middle_nameThe contacts middle name
last_nameThe contacts last name
addresseeThe preferred way to address the contact
date_of_birthThe contacts date of birth (ISO-8601)
genderThe contacts gender
telephoneThe contacts telephone number
mobileThe contacts mobile number
faxThe contacts fax number
emailThe contacts email address
websiteThe contacts website address
companyThe contacts company name
job_titleThe contacts job title
propertyThe contacts property name / number
streetThe contacts street name
areaThe area the contact is located
townThe town the contact is located in
countyThe county the contact is located in
post_codeThe contacts post code
countryThe contacts country code (ISO-3166-1 alpha-2)
statusThe contacts status
officeThe office ID the contact belongs to
groupsA comma separated list of contact group ID's that the contact is assigned to
common_groupsA comma separated list of common contact group ID's that the contact is assigned to
custom_fieldsThe contacts custom fields (id, value)

Contacts API

Get Contact - Gets a contact specified by the {contact_id} parameter

GEThttps://api.franchisemailer.co.uk/v1/contacts/{contact_id}

PHP Example Code:
$contact_id = '1';
api_call('GET','/contacts/'.$contact_id);

JSON Example Response:
{
    "status": "success",
    "data": {
        "contact": {
            "id": "1",
            "title": "Mr",
            "first_name": "Joe",
            "middle_name": "Michael",
            "last_name": "Bloggs",
            "addressee": "Mr Joe Bloggs",
            "date_of_birth": "2013-01-31",
            "gender": "Male",
            "telephone": "01903 123 456",
            "mobile": "07123456789",
            "fax": "01903 123 456",
            "email": "job.bloggs@example.com",
            "website": "http://www.example.com",
            "company": "JB Trading",
            "job_title": "Sales Director",
            "property": "118",
            "street": "Long Street",
            "area": "Tarring",
            "town": "Worthing",
            "county": "West Sussex",
            "post_code": "BN14 8AD",
            "country": "GB",
            "status": "Permitted",
            "office": "1",
            "groups": "1,3,4",
            "common_groups": "1,3,4",
            "custom_fields": {
                "1": "£30,000"
            }
        }
    }
}

Contacts API

Update Contact - Updates a contact specified by the {contact_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/contacts/{contact_id}

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
titleThe contacts title--
first_nameThe contacts first name--
middle_nameThe contacts middle name--
last_nameThe contacts last name--
addresseeThe preferred way to address the contact--
date_of_birthThe contacts date of birthISO-8601-
genderThe contacts gender--
telephoneThe contacts telephone number--
mobileThe contacts mobile number--
faxThe contacts fax number--
emailThe contacts email address--
websiteThe contacts website address--
companyThe contacts company name--
job_titleThe contacts job title--
propertyThe contacts property name / number--
streetThe contacts street name--
areaThe area the contact is located--
townThe town the contact is located in--
countyThe county the contact is located in--
post_codeThe contacts post code--
countryThe contacts country codeISO-3166-1 alpha-2/3-
statusThe contacts statusPermitted, Dormant or Excluded-
officeThe office ID the contact belongs to--
groupsA comma separated list of contact group ID's--
common_groupsA comma separated list of common contact group ID'sWill be ignored if group parameter is set and not empty-
custom_fieldsThe contacts custom fields (id, value)--

Contacts API

Update Contact - Updates a contact specified by the {contact_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/contacts/{contact_id}

Response Parameters:
ParameterDescription
idThe unique ID of the contact
titleThe contacts title
first_nameThe contacts first name
middle_nameThe contacts middle name
last_nameThe contacts last name
addresseeThe preferred way to address the contact
date_of_birthThe contacts date of birth (ISO-8601)
genderThe contacts gender
telephoneThe contacts telephone number
mobileThe contacts mobile number
faxThe contacts fax number
emailThe contacts email address
websiteThe contacts website address
companyThe contacts company name
job_titleThe contacts job title
propertyThe contacts property name / number
streetThe contacts street name
areaThe area the contact is located
townThe town the contact is located in
countyThe county the contact is located in
post_codeThe contacts post code
countryThe contacts country code (ISO-3166-1 alpha-2)
statusThe contacts status
officeThe office ID the contact belongs to
groupsA comma separated list of contact group ID's that the contact is assigned to
common_groupsA comma separated list of common contact group ID's that the contact is assigned to
custom_fieldsThe contacts custom fields (id, value)

Contacts API

Update Contact - Updates a contact specified by the {contact_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/contacts/{contact_id}

PHP Example Code:
$contact_id = '1';
$params = array(
    "title" => "Mr",
    "first_name" => "Joe",
    "middle_name" => "Michael",
    "last_name" => "Bloggs",
    "addressee" => "Mr Joe Bloggs",
    "date_of_birth" => "2013-01-31",
    "gender" => "Male",
    "telephone" => "01903 123 456",
    "mobile" => "07123456789",
    "fax" => "01903 123 456",
    "email" => "job.bloggs@example.com",
    "website" => "http://www.example.com",
    "company" => "JB Trading",
    "job_title" => "Sales Director",
    "property" => "118",
    "street" => "Long Street",
    "area" => "Tarring",
    "town" => "Worthing",
    "county" => "West Sussex",
    "post_code" => "BN14 8AD",
    "country" => "GB",
    "status" => "Permitted",
    "office" => "1",
    "groups" => "1,3,4",
    "common_groups" => "1,3,4",
    "custom_fields" => array(
        1 => "£30,000"
    )
);
api_call('PUT','/contacts/'.$contact_id, $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "contact": {
            "id": "1",
            "title": "Mr",
            "first_name": "Joe",
            "middle_name": "Michael",
            "last_name": "Bloggs",
            "addressee": "Mr Joe Bloggs",
            "date_of_birth": "2013-01-31",
            "gender": "Male",
            "telephone": "01903 123 456",
            "mobile": "07123456789",
            "fax": "01903 123 456",
            "email": "job.bloggs@example.com",
            "website": "http://www.example.com",
            "company": "JB Trading",
            "job_title": "Sales Director",
            "property": "118",
            "street": "Long Street",
            "area": "Tarring",
            "town": "Worthing",
            "county": "West Sussex",
            "post_code": "BN14 8AD",
            "country": "GB",
            "status": "Permitted",
            "office": "1",
            "groups": "1,3,4",
            "common_groups": "1,3,4",
            "custom_fields": {
                "1": "£30,000"
            }
        }
    }
}

Contacts API

Delete Contact - Deletes a contact specified by the {contact_id} parameter

DELETEhttps://api.franchisemailer.co.uk/v1/contacts/{contact_id}

PHP Example Code:
$contact_id = '1';
api_call('DELETE','/contacts/'.$contact_id);

JSON Example Response:
{
    "status": "success",
    "data": null
}

Contact Groups API

List Contact Groups - Returns a list of all contact groups

GEThttps://api.franchisemailer.co.uk/v1/contactgroups?office={office_id}

Response Parameters:
ParameterDescription
idThe unique ID of the group
common_idThe common group ID
nameThe name of the group
officeThe office ID the group belongs to
totalThe total number of contacts contained in the group
permittedThe total number of permitted contacts contained in the group
dormantThe total number of dormant contacts contained in the group
excludedThe total number of excluded contacts contained in the group
invalidThe total number of invalid contacts contained in the group

PHP Example Code:
$office_id = '1';
api_call('GET','/contactgroups?office='.$office_id);

JSON Example Response:
{
    "status": "success",
    "data": {
        "contact_groups": [
            {
                "id": "1",
                "common_id": "1",
                "name": "Prospects",
                "office": "1",
                "total": "233",
                "permitted": "200",
                "dormant": "14",
                "excluded": "7",
                "invalid": "12"
            }
        ]
    }
}

Contact Groups API

Create Contact Group - Creates a new contact group for either a single office, for each specified office or for all offices

POSThttps://api.franchisemailer.co.uk/v1/contactgroups

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
nameThe name of the grouprequired Max length 40 chars-
officesSingle office ID or a comma separated list of office ID's that a group will be created for, 0 will create groups for all officesrequired 0

Response Parameters:
ParameterDescription
idThe unique ID of the group
common_idThe common group ID
nameThe name of the group
officeThe office ID the group belongs to

PHP Example Code:
$params = array(
    "name" => "Prospects",
    "offices" => "1,3,4"
);
api_call('POST', '/contactgroups', $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "contact_groups": [
            {
                "id": "1",
                "common_id": "1",
                "name": "Prospects",
                "office": "1"
            },
            {
                "id": "2",
                "common_id": "1",
                "name": "Prospects",
                "office": "3"
            },
            {
                "id": "3",
                "common_id": "1",
                "name": "Prospects",
                "office": "4"
            }
        ]
    }
}

Contact Groups API

Get Contact Group - Gets a contact group specified by the {group_id} parameter

GEThttps://api.franchisemailer.co.uk/v1/contactgroups/{group_id}

Response Parameters:
ParameterDescription
idThe unique ID of the group
common_idThe common group ID
nameThe name of the group
officeThe office ID the group belongs to
totalThe total number of contacts contained in the group
permittedThe total number of permitted contacts contained in the group
dormantThe total number of dormant contacts contained in the group
excludedThe total number of excluded contacts contained in the group
invalidThe total number of invalid contacts contained in the group

PHP Example Code:
$group_id = '1';
api_call('GET','/contactgroups/'.$group_id);

JSON Example Response:
{
    "status": "success",
    "data": {
        "contact_group": {
            "id": "1",
            "common_id": "1",
            "name": "Prospects",
            "office": "1",
            "total": "233",
            "permitted": "200",
            "dormant": "14",
            "excluded": "7",
            "invalid": "12"
        }
    }
}

Contact Groups API

Update Contact Group - Updates a contact group specified by the {group_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/contactgroups/{group_id}

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
nameThe name of the groupMax length 40 chars-

Response Parameters:
ParameterDescription
idThe unique ID of the group
common_idThe common group ID
nameThe name of the group
officeThe office ID the group belongs to
totalThe total number of contacts contained in the group
permittedThe total number of permitted contacts contained in the group
dormantThe total number of dormant contacts contained in the group
excludedThe total number of excluded contacts contained in the group
invalidThe total number of invalid contacts contained in the group

PHP Example Code:
$group_id = '1';
$params = array(
    "name" => "Prospects"
);
api_call('PUT','/contactgroups/'.$group_id, $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "contact_group": {
            "id": "1",
            "common_id": "1",
            "name": "Prospects",
            "office": "1",
            "total": "233",
            "permitted": "200",
            "dormant": "14",
            "excluded": "7",
            "invalid": "12"
        }
    }
}

Contact Groups API

Delete Contact Group - Deletes a contact group specified by the {group_id} parameter

DELETEhttps://api.franchisemailer.co.uk/v1/contactgroups/{group_id}

PHP Example Code:
$group_id = '1';
api_call('DELETE','/contactgroups/'.$group_id);

JSON Example Response:
{
    "status": "success",
    "data": null
}

Custom Fields API

List Custom Fields - Returns a list of all custom fields

GEThttps://api.franchisemailer.co.uk/v1/customfields

Response Parameters:
ParameterDescription
idThe unique ID of the custom field
nameThe name of the custom field
descriptionA short description of the custom field

PHP Example Code:
api_call('GET','/customfields');

JSON Example Response:
{
    "status": "success",
    "data": {
        "custom_fields": [
            {
                "id": "1",
                "name": "Yearly Spend",
                "description": "The amount the contact spends per year"
            }
        ]
    }
}

Custom Fields API

Create Custom Field - Creates a new custom field

POSThttps://api.franchisemailer.co.uk/v1/customfields

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
nameThe name of the custom fieldrequired Max length 20 chars-
descriptionA short description of the custom fieldrequired -

Response Parameters:
ParameterDescription
idThe unique ID of the custom field
nameThe name of the custom field
descriptionA short description of the custom field

PHP Example Code:
$params = array(
    "name" => "Yearly Spend",
    "description" => "The amount the contact spends per year"
);
api_call('POST','/customfields', $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "custom_field": {
            "id": "1",
            "name": "Yearly Spend",
            "description": "The amount the contact spends per year"
        }
    }
}

Custom Fields API

Get Custom Field - Gets a custom field specified by the {field_id} parameter

GEThttps://api.franchisemailer.co.uk/v1/customfields/{field_id}

Response Parameters:
ParameterDescription
idThe unique ID of the custom field
nameThe name of the custom field
descriptionA short description of the custom field

PHP Example Code:
$field_id = '1';
api_call('GET','/customfields/'.$field_id);

JSON Example Response:
{
    "status": "success",
    "data": {
        "custom_field": {
            "id": "1",
            "name": "Yearly Spend",
            "description": "The amount the contact spends per year"
        }
    }
}

Custom Fields API

Update Custom Field - Updates a custom field specified by the {field_id} parameter

PUThttps://api.franchisemailer.co.uk/v1/customfields/{field_id}

Accepted Request Parameters:
ParameterDescriptionValidationDefault Value
nameThe name of the custom field--
descriptionA short description of the custom field--

Response Parameters:
ParameterDescription
idThe unique ID of the custom field
nameThe name of the custom field
descriptionA short description of the custom field

PHP Example Code:
$field_id = '1';
$params = array(
    "name" => "Yearly Spend",
    "description" => "The amount the contact spends per year"
);
api_call('PUT','/customfields/'.$field_id, $params);

JSON Example Response:
{
    "status": "success",
    "data": {
        "custom_field": {
            "id": "1",
            "name": "Yearly Spend",
            "description": "The amount the contact spends per year"
        }
    }
}

Custom Fields API

Delete Custom Field - Deletes a custom field specified by the {field_id} parameter

DELETEhttps://api.franchisemailer.co.uk/v1/customfields/{field_id}

PHP Example Code:
$field_id = '1';
api_call('DELETE','/customfields/'.$field_id);

JSON Example Response:
{
    "status": "success",
    "data": null
}

Single Sign-On API

Start Session - Returns a URL that can be used to automatically start a session specified by the {user_id} parameter

GEThttps://api.franchisemailer.co.uk/v1/sso/{user_id}

Response Parameters:
ParameterDescription
session_urlURL to start session with temporary token that expires on 1st use or 20 seconds after token generation

PHP Example Code:
$user_id = '1';
api_call('GET','/sso/'.$user_id);

JSON Example Response:
{
    "status": "success",
    "data": {
        "sso": {
            "session_url": "https://www.franchisemailer.co.uk/?t=0ab34ca97d9946591bf89817789cb5de"
        }
    }
}

Single Sign-On API

End Session - Ends a users session specified by the {user_id} parameter

DELETEhttps://api.franchisemailer.co.uk/v1/sso/{user_id}

PHP Example Code:
$user_id = '1';
api_call('DELETE','/sso/'.$user_id);

JSON Example Response:
{
    "status": "success",
    "data": null
}

HTTP Status Codes & Error Messages

When debugging queries that are not returning what you expect it can be useful to check the HTTP status code being returned and the error message contained within the JSON Response.

Common HTTP Status Codes:
200 - OK
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
405 - Method Not Allowed
406 - Not Acceptable
500 - Internal Error

JSON Example Response:
{
    "messages": {
        "error": {
            "message": "Email Address Required"
        }
    }
}

Require Help?

For assistance, to report a bug or request a feature please email support@minexos.com
What our clients say
"We are very impressed so far with how easy it has been to sign up and use. The guys behind it have been great and talked me through how to get the most from the stats as well, so thank you Stuart!"


Sign up and get more...

Special offers, industry news, hints & tips and much more
Subscribe