REST API Documentation

Getting Started

Get started in minutes, follow the simple steps below:

• Within the API section under My Account click Generate API Key
• Record the generated Access Key and the Secret Key
• Add your IP address to the IP whitelist

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:

• Create the string representation of the current date and time in HTTP format.
  Example: Mon, 16 Sep 2013 13:00:00 +0000
• Calculate the hexadecimal HMAC SHA1 hash of that string using your Secret key as the hash key.
  Example: 9ee2b3fea06ad04ee1035b13454ca93887f461de
• Set the values for the request headers using your API access key, the current date and time, and the HMAC hash that you calculated.
  This example was created using a Secret key of 7790b9c0a39bf5cffde1da8851f25b5e7fb21a95:
  accesskey: b6b581087d3a65b71f119e4db6efa6b7
  requestdate: Mon, 16 Sep 2013 13:00:00 +0000
  hmac: 061f0b045caf4ca57b681a1ddcf3d1cfc1d8ae87

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

Offices API

Refers to stores, branches, restaurants, outlets etc

List Offices - Returns a list of all offices


Response Parameters:

Parameter	Description
id	The unique ID of the office
name	The name of the office
property	The property name / number
street	The street name
area	The area the office is located
town	The town the office is located in
county	The county the office is located in
post_code	The office post code
telephone	The office telephone number
fax	The office fax number
email	The office email address
website	The office local website address / local landing page
post_code_allocation	A comma separated list of post code areas/districts allocated to the office

Create Office - Creates a new office


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
name	The name of the office	required	-
property	The property name / number	-	-
street	The street name	-	-
area	The area the office is located	-	-
town	The town the office is located in	-	-
county	The county the office is located in	-	-
post_code	The office post code	-	-
telephone	The office telephone number	-	-
fax	The office fax number	-	-
email	The office email address	-	-
website	The office local website address / local landing page	-	-
post_code_allocation	A comma separated list of post code areas/districts allocated to the office	-	-

Response Parameters:

Parameter	Description
id	The unique ID of the office
name	The name of the office
property	The property name / number
street	The street name
area	The area the office is located
town	The town the office is located in
county	The county the office is located in
post_code	The office post code
telephone	The office telephone number
fax	The office fax number
email	The office email address
website	The office local website address / local landing page
post_code_allocation	A comma separated list of post code areas/districts allocated to the office

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


Response Parameters:

Parameter	Description
id	The unique ID of the office
name	The name of the office
property	The property name / number
street	The street name
area	The area the office is located
town	The town the office is located in
county	The county the office is located in
post_code	The office post code
telephone	The office telephone number
fax	The office fax number
email	The office email address
website	The office local website address / local landing page
post_code_allocation	A comma separated list of post code areas/districts allocated to the office

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


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
name	The name of the office	-	-
property	The property name / number	-	-
street	The street name	-	-
area	The area the office is located	-	-
town	The town the office is located in	-	-
county	The county the office is located in	-	-
post_code	The office post code	-	-
telephone	The office telephone number	-	-
fax	The office fax number	-	-
email	The office email address	-	-
website	The office local website address / local landing page	-	-
post_code_allocation	A comma separated list of post code areas/districts allocated to the office	-	-

Response Parameters:

Parameter	Description
id	The unique ID of the office
name	The name of the office
property	The property name / number
street	The street name
area	The area the office is located
town	The town the office is located in
county	The county the office is located in
post_code	The office post code
telephone	The office telephone number
fax	The office fax number
email	The office email address
website	The office local website address / local landing page
post_code_allocation	A comma separated list of post code areas/districts allocated to the office

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

Users API

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

List Users - Returns a list of all users


Response Parameters:

Parameter	Description
id	The unique ID of the user
username	The users username
first_name	The users first name
last_name	The users last name
email	The users email address
telephone	The users telephone number
job_title	The users job title
active	The users account status
offices	A comma separated list of office ID's that the user can access and send from
last_login	The data and time the user last logged in (ISO-8601)
last_password_change	The date the users password was last changed (ISO-8601)

Create User - Creates a new user


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
username	A unique username	required	-
password	The users password (plain text)	required	-
first_name	The users first name	required	-
last_name	The users last name	required	-
email	The users email address	required	-
telephone	The users telephone number	-	-
job_title	The users job title	-	-
active	The users account status	required true or false	false
offices	A comma separated list of office ID's	required Only digits and commas accepted	-

Response Parameters:

Parameter	Description
id	The unique ID of the user
username	A unique username
first_name	The users first name
last_name	The users last name
email	The users email address
telephone	The users telephone number
job_title	The users job title
active	The users account status
offices	A comma separated list of office ID's that the user can access and send from
last_login	The data and time the user last logged in (ISO-8601)
last_password_change	The date the users password was last changed (ISO-8601)

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


Response Parameters:

Parameter	Description
id	The unique ID of the user
username	The users username
first_name	The users first name
last_name	The users last name
email	The users email address
telephone	The users telephone number
job_title	The users job title
active	The users account status
offices	A comma separated list of office ID's that the user can access and send from
last_login	The data and time the user last logged in (ISO-8601)
last_password_change	The date the users password was last changed (ISO-8601)

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


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
username	A unique username	-	-
password	The users password (plain text)	-	-
first_name	The users first name	-	-
last_name	The users last name	-	-
email	The users email address	-	-
telephone	The users telephone number	-	-
job_title	The users job title	-	-
active	The users account status	true or false	-
offices	A comma separated list of office ID's	Only digits and commas accepted	-

Response Parameters:

Parameter	Description
id	The unique ID of the user
username	A unique username
first_name	The users first name
last_name	The users last name
email	The users email address
telephone	The users telephone number
job_title	The users job title
active	The users account status
offices	A comma separated list of office ID's that the user can access and send from
last_login	The data and time the user last logged in (ISO-8601)
last_password_change	The date the users password was last changed (ISO-8601)

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

Contacts API

List Contacts - Returns a list of all contacts


Response Parameters:

Parameter	Description
id	The unique ID of the contact
title	The contacts title
first_name	The contacts first name
middle_name	The contacts middle name
last_name	The contacts last name
addressee	The preferred way to address the contact
date_of_birth	The contacts date of birth (ISO-8601)
gender	The contacts gender
telephone	The contacts telephone number
mobile	The contacts mobile number
fax	The contacts fax number
email	The contacts email address
website	The contacts website address
company	The contacts company name
job_title	The contacts job title
property	The contacts property name / number
street	The contacts street name
area	The area the contact is located
town	The town the contact is located in
county	The county the contact is located in
post_code	The contacts post code
country	The contacts country code (ISO-3166-1 alpha-2)
status	The contacts status
office	The office ID the contact belongs to
groups	A comma separated list of contact group ID's that the contact is assigned to
common_groups	A comma separated list of common contact group ID's that the contact is assigned to
custom_fields	The contacts custom fields (id, value)

Create Contact - Creates a new contact


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
title	The contacts title	-	-
first_name	The contacts first name	-	-
middle_name	The contacts middle name	-	-
last_name	The contacts last name	-	-
addressee	The preferred way to address the contact	-	-
date_of_birth	The contacts date of birth	ISO-8601	-
gender	The contacts gender	Male or Female	-
telephone	The contacts telephone number	-	-
mobile	The contacts mobile number	-	-
fax	The contacts fax number	-	-
email	The contacts email address	required	-
website	The contacts website address	-	-
company	The contacts company name	-	-
job_title	The contacts job title	-	-
property	The contacts property name / number	-	-
street	The contacts street name	-	-
area	The area the contact is located	-	-
town	The town the contact is located in	-	-
county	The county the contact is located in	-	-
post_code	The contacts post code	-	-
country	The contacts country code	ISO-3166-1 alpha-2/3	-
status	The contacts status	required Pending, Permitted, Dormant or Excluded	Permitted
office	The office ID the contact belongs to	required 0 can be used to auto allocate as long as offices have been allocated post code areas/districts	-
groups	A comma separated list of contact group ID's	required Or use the common group parameter instead	-
common_groups	A comma separated list of common contact group ID's	Will be ignored if group parameter is set and not empty	-
custom_fields	The contacts custom fields (id, value)	-	-

Response Parameters:

Parameter	Description
id	The unique ID of the contact
title	The contacts title
first_name	The contacts first name
middle_name	The contacts middle name
last_name	The contacts last name
addressee	The preferred way to address the contact
date_of_birth	The contacts date of birth (ISO-8601)
gender	The contacts gender
telephone	The contacts telephone number
mobile	The contacts mobile number
fax	The contacts fax number
email	The contacts email address
website	The contacts website address
company	The contacts company name
job_title	The contacts job title
property	The contacts property name / number
street	The contacts street name
area	The area the contact is located
town	The town the contact is located in
county	The county the contact is located in
post_code	The contacts post code
country	The contacts country code (ISO-3166-1 alpha-2)
status	The contacts status
office	The office ID the contact belongs to
groups	A comma separated list of contact group ID's that the contact is assigned to
common_groups	A comma separated list of common contact group ID's that the contact is assigned to
custom_fields	The contacts custom fields (id, value)

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


Response Parameters:

Parameter	Description
id	The unique ID of the contact
title	The contacts title
first_name	The contacts first name
middle_name	The contacts middle name
last_name	The contacts last name
addressee	The preferred way to address the contact
date_of_birth	The contacts date of birth (ISO-8601)
gender	The contacts gender
telephone	The contacts telephone number
mobile	The contacts mobile number
fax	The contacts fax number
email	The contacts email address
website	The contacts website address
company	The contacts company name
job_title	The contacts job title
property	The contacts property name / number
street	The contacts street name
area	The area the contact is located
town	The town the contact is located in
county	The county the contact is located in
post_code	The contacts post code
country	The contacts country code (ISO-3166-1 alpha-2)
status	The contacts status
office	The office ID the contact belongs to
groups	A comma separated list of contact group ID's that the contact is assigned to
common_groups	A comma separated list of common contact group ID's that the contact is assigned to
custom_fields	The contacts custom fields (id, value)

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


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
title	The contacts title	-	-
first_name	The contacts first name	-	-
middle_name	The contacts middle name	-	-
last_name	The contacts last name	-	-
addressee	The preferred way to address the contact	-	-
date_of_birth	The contacts date of birth	ISO-8601	-
gender	The contacts gender	-	-
telephone	The contacts telephone number	-	-
mobile	The contacts mobile number	-	-
fax	The contacts fax number	-	-
email	The contacts email address	-	-
website	The contacts website address	-	-
company	The contacts company name	-	-
job_title	The contacts job title	-	-
property	The contacts property name / number	-	-
street	The contacts street name	-	-
area	The area the contact is located	-	-
town	The town the contact is located in	-	-
county	The county the contact is located in	-	-
post_code	The contacts post code	-	-
country	The contacts country code	ISO-3166-1 alpha-2/3	-
status	The contacts status	Pending, Permitted, Dormant or Excluded	-
office	The office ID the contact belongs to	-	-
groups	A comma separated list of contact group ID's	-	-
common_groups	A comma separated list of common contact group ID's	Will be ignored if group parameter is set and not empty	-
custom_fields	The contacts custom fields (id, value)	-	-

Response Parameters:

Parameter	Description
id	The unique ID of the contact
title	The contacts title
first_name	The contacts first name
middle_name	The contacts middle name
last_name	The contacts last name
addressee	The preferred way to address the contact
date_of_birth	The contacts date of birth (ISO-8601)
gender	The contacts gender
telephone	The contacts telephone number
mobile	The contacts mobile number
fax	The contacts fax number
email	The contacts email address
website	The contacts website address
company	The contacts company name
job_title	The contacts job title
property	The contacts property name / number
street	The contacts street name
area	The area the contact is located
town	The town the contact is located in
county	The county the contact is located in
post_code	The contacts post code
country	The contacts country code (ISO-3166-1 alpha-2)
status	The contacts status
office	The office ID the contact belongs to
groups	A comma separated list of contact group ID's that the contact is assigned to
common_groups	A comma separated list of common contact group ID's that the contact is assigned to
custom_fields	The contacts custom fields (id, value)

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

Contact Groups API

List Contact Groups - Returns a list of all contact groups


Response Parameters:

Parameter	Description
id	The unique ID of the group
common_id	The common group ID
name	The name of the group
office	The office ID the group belongs to
total	The total number of contacts contained in the group
permitted	The total number of permitted contacts contained in the group
dormant	The total number of dormant contacts contained in the group
excluded	The total number of excluded contacts contained in the group
invalid	The total number of invalid contacts contained in the group

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


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
name	The name of the group	required Max length 40 chars	-
offices	Single office ID or a comma separated list of office ID's that a group will be created for, 0 will create groups for all offices	required	0

Response Parameters:

Parameter	Description
id	The unique ID of the group
common_id	The common group ID
name	The name of the group
office	The office ID the group belongs to

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


Response Parameters:

Parameter	Description
id	The unique ID of the group
common_id	The common group ID
name	The name of the group
office	The office ID the group belongs to
total	The total number of contacts contained in the group
permitted	The total number of permitted contacts contained in the group
dormant	The total number of dormant contacts contained in the group
excluded	The total number of excluded contacts contained in the group
invalid	The total number of invalid contacts contained in the group

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


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
name	The name of the group	Max length 40 chars	-

Response Parameters:

Parameter	Description
id	The unique ID of the group
common_id	The common group ID
name	The name of the group
office	The office ID the group belongs to
total	The total number of contacts contained in the group
permitted	The total number of permitted contacts contained in the group
dormant	The total number of dormant contacts contained in the group
excluded	The total number of excluded contacts contained in the group
invalid	The total number of invalid contacts contained in the group

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

Custom Fields API

List Custom Fields - Returns a list of all custom fields


Response Parameters:

Parameter	Description
id	The unique ID of the custom field
name	The name of the custom field
description	A short description of the custom field

Create Custom Field - Creates a new custom field


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
name	The name of the custom field	required Max length 20 chars	-
description	A short description of the custom field	required	-

Response Parameters:

Parameter	Description
id	The unique ID of the custom field
name	The name of the custom field
description	A short description of the custom field

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


Response Parameters:

Parameter	Description
id	The unique ID of the custom field
name	The name of the custom field
description	A short description of the custom field

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


Accepted Request Parameters:

Parameter	Description	Validation	Default Value
name	The name of the custom field	-	-
description	A short description of the custom field	-	-

Response Parameters:

Parameter	Description
id	The unique ID of the custom field
name	The name of the custom field
description	A short description of the custom field

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

Single Sign-On API

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


Response Parameters:

Parameter	Description
session_url	URL to start session with temporary token that expires on 1st use or 20 seconds after token generation

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

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.

Require Help?

For assistance, to report a bug or request a feature please email support@minexos.com