Welcome

The process of applying updates to data can be difficult, time-consuming and error-prone. The Corpdata RESTful Update API is now available to help simplify and automate the process.

This document will help you work with the Update API. It details the features and on the right, shows sample code in 3 commonly used languages.

Update API

The Corpdata REST Update API is designed to streamline the process of updating data stored in your systems which was supplied by Corpdata. This helps you satisfy the GDPR principle of 'data accuracy'.

This documentation will help you make use of the Update API. Please contact us if the documentation is not adequately clear.

Basic Usage

Request Format
https://api.corpdata.co.uk/{requesttype}/{licensenumber}/{endpoint}?{parameters}
Response Format
{"status": 200, "response": ""}

The Update API can now be used to automate the collection and updating of data licensed from Corpdata. In-line with modern security standards, the API uses TLS encryption to protect the data in transit, and all requests must be made using SSL/TLS/HTTPS connections.

The default response format of the Update API is JSON, you may request XML if preferred. All responses include warning and error messages where appropriate.

The Update API uses token based authentication for all requests.


URI Schema:

Part Examples Info
Request Typeauth, dataCurrently supported request types
LicenseNumber000000Corpdata License Number
Endpointinfo, updates, etcPlease see endpoints section for full list
Parametersformat, dmc, limit, etcPlease see parameters section for full list

Error Handling

Errors are returned as responses from the Update API. The response will include a message explaining the reason for the error.

Standard HTTP Status Codes are used, below is a list of more common responses:


Code Status
200OK
401Unauthorized
404Not Found'
405Method Not Allowed
429Too Many Requests
500Internal Server Error
503Service Unavailable

Rate Limiting

To ensure fair access to the Update API for all customers, requests to the API are rate limited.

Please see the Fair Usage section below for detailed information about usage limits.

Request Types

There are 2 basic request types:

Request Type Explained
Auth RequestAuthenticate against the API to retrieve an 'Access Token'
Licensed Data RequestRequest info/data of a licensed data set

Authentication

Auth Request:
https://api.corpdata.co.uk/auth?clientID={update-email}&clientPass={job Password}
Auth Response:
{ 
	"response": { 
	  "accessToken": "5559d81acdbdffe921af1b6dd0750b824402f1c8c66668a3972471c77cf462f6",
	  "tokenExpiry": "20\/11\/2018 12:42", 
	  "tokenGranted": "20\/11\/2018 11:42" 
	}, 
	"status": 200 
	}

To access the Update API, you first need an 'Access Token'

Authentication requests must be made to https://api.corpdata.co.uk/auth supplying the following information:

Key Value Where do I find this?
clientID{update-email}Email Address currently setup with Corpdata to receive GDPR Updates
clientPass{Job Password}This is available on your Corpdata Order Form

Please refer to the code samples for usage examples.

Access Tokens are valid for 1 hour which is suitable for most normal operations. However, if your operations may last longer, be sure to check for authentication errors.

You must request a new access token if your existing access token has expired.

Only 1 access token per organisation is permitted at a time.

Access tokens grant access to all data sets with a currently active license that are licensed to the same organisation.

Authentication requests are the only request which do not require an 'access token'.


*Please contact your Corpdata Account Manager for more help with these values

Licensed Data Request

Data Request:
https://api.corpdata.co.uk/data/

Licensed Data Requests take the following form:

https://api.corpdata.co.uk/data/{licensenumber}/{endpoint}?{parameter}&{parameter}

Requests to all Licensed Data Request endpoints must be signed with the access token as either a GET or a POST variable.

Endpoints

Request:
https://api.corpdata.co.uk/data/{licensenumber}/{endpoint}?token={accessToken}

There are 3 licensed data request 'endpoints' which tell the Update API what you want to do, these are:

Endpoint Explained
infoTop level information of the Licensed Data Set
originalProvides the original Licensed Data Set
updateProvides the latest state of the data requested

Info

Request:
https://api.corpdata.co.uk/data/{licensenumber}/info?token={accessToken}

The info endpoint returns top level information about the licensed data set. This includes information such as License Type, Expiry Date and Licensee.

The response will also include a comma separated list of 'columns' or 'fields' that form part of the licensed data set.

Response:
{
"response": {
  "ID": "123456",
  "Name": "2019 Email Campaign",
  "licenseType": "Fixed Term (GDPR)",
  "licenseStatus": "In License",
  "expiryDate": "10\/01\/2019",
  "lastUpdate": "26\/12\/2019",
  "Licensee": "Company ABC Ltd",
  "shippedFields": "SALUTATION, TITLE, FORENAME...",
  "Company": {
	"company": "Company ABC Ltd",
	"building": "Corpdata House",
	"street": "6 Den Crescent",
	"town": "Teignmouth",
	"county": "Devon",
	"postcode": "TQ14 8BQ",
	"tel": "01626777400"
  },
  "Contact": {
	"name": "Mr Joe Bloggs",
	"job": "IT Manager",
	"email": "Joe.Bloggs@corpdata.co.uk"
  }
},
"status": 200
}

Original

Request:
https://api.corpdata.co.uk/data/{licensenumber}/original?token={accessToken}
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "Mr J Bloggs",
	"TITLE": "Mr",
	"FORENAME": "Joe",
	"INITS": "J",
	"SURNAME": "Bloggs",
	"JOB": "IT Manager",
	"DMCEMAIL": "Joe.Bloggs@corpdata.co.uk",
	"PREF_EMAIL": "Y",
	"PREF_POST": "Y",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2017",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "Computing",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

The original endpoint provides the original licensed data set. This represents the starting state. This endpoint can also be used to collect the licensed data sets from the API rather than via download.

The records returned will include all fields licensed, such as Company Name, Postcode, etc. The original licensed data set also includes the mandatory fields shown below:

Field Info
CONTACTREF A Unique Identifier for our Contacts. This value will never change for a contact, and is advisable to import into your data
PROPOSAL Your Corpdata Account Manager may have run multiple data proposal which made up your Licensed Data Set. The proposal number is specified here
FILEFROM A Corpdata specific field, in which we specify from what file the data record originated, ie: Corpdata Premium, Site Only, etc

Update

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={accessToken}
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "Mr J Bloggs",
	"TITLE": "Mr",
	"FORENAME": "Joe",
	"INITS": "J",
	"SURNAME": "Bloggs",
	"JOB": "IT Manager",
	"DMCEMAIL": "Joe.Bloggs@corpdata.co.uk",
	"PREF_EMAIL": "Y",
	"PREF_POST": "Y",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "Computing",
	"CHANGED_FLAG": "COMPANY,POSTCODE",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

The update endpoint provides the latest state of the data requested and applies to any data licensed under a GDPR style license. Updated information will only be supplied by the Update API for records provided as part of the original licensed data set.

The data structure of the update record is identical to that in the original licensed data set, but has one additional field shown below:

Field Default Example Info
CHANGED_FLAG N COMPANY,POSTCODE Contains a comma separated list of Column names that have changed for each record or N if nothing has changed

Parameters

Request Format
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&paramKey=paramVal

Several parameters may be passed with Licensed Data Requests as POST or GET variables.

They may be used alone or together.

These parameters can be used to filter, limit or format the response.

Please ensure you supply the Access Token as a parameter to every Licensed Data Request.

Response Format

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&format=xml
Response:

The format parameter instructs the Update API about the response format you require.

The default response format is JSON, but you may also request responses to be formatted as XML - see the code examples to the right for usage.

Further information about JSON and XML can be found online. Below is an example of the presentation of a single data element in both formats:

Format Info
JSON { Key : Value }
XML <Key>Value</Key>

The format parameter may be used with all endpoints.

Changes Only

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&changesonly=true
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "Mr J Bloggs",
	"TITLE": "Mr",
	"FORENAME": "Joe",
	"INITS": "J",
	"SURNAME": "Bloggs",
	"JOB": "IT Manager",
	"DMCEMAIL": "Joe.Bloggs@corpdata.co.uk",
	"PREF_EMAIL": "Y",
	"PREF_POST": "Y",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "Computing",
	"CHANGED_FLAG": "COMPANY,POSTCODE",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

The default format for updates is an entire file, in the same format, with all the same columns, in the same sequence, although containing the latest state of the data.

This is particularly suited to customers using the licensed data set in a spreadsheet, such as Excel. It enables the original data to be overwritten with the new data while leaving additional columns created by the client to remain associated with the correct record.

This does not suit every use case. Customers using CRM systems with single record updating capabilities may find the changesonly parameter useful since the Update API will supply a data set containing only records where the data has been updated since the previous 'update' or 'original' if this is the first update.

The changesonly data set includes deletions (see deletions parameter).

The changesonly parameter may only be used with the update endpoint of Licensed Data Requests.

Deletions Only

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&deletionsonly={value}
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "",
	"TITLE": "",
	"FORENAME": "",
	"INITS": "",
	"SURNAME": "",
	"JOB": "",
	"DMCEMAIL": "",
	"PREF_EMAIL": "N",
	"PREF_POST": "N",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "",
	"CHANGED_FLAG": "SALUTATION,TITLE,FORENAME,INITS,SURNAME,JOB,DMCEMAIL,PREF_EMAIL,PREF_POST,PREF_PHONE,DMC",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

Site or Contact data may be removed for several reasons, including 'objecting to direct marketing', or the record having 'gone-away'. These records are represented in 'updates' as records with blank data elements (fields) at the appropriate level.

For contact level removals, the contact specific fields will be empty, for site level removals, all the data elements will be empty, except for the mandatory fields identified above in the 'Original section'.

The deletionsonly data set only contains records which have been deleted.

See below for example values:

Parameter Key Accepted Values
deletionsonly site/contact

Preferences

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&phone=1
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "",
	"TITLE": "",
	"FORENAME": "",
	"INITS": "",
	"SURNAME": "",
	"JOB": "",
	"DMCEMAIL": "",
	"PREF_EMAIL": "N",
	"PREF_POST": "N",
	"PREF_PHONE": "Y",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "",
	"CHANGED_FLAG": "SALUTATION,TITLE,FORENAME,INITS,SURNAME,JOB,DMCEMAIL,PREF_EMAIL,PREF_POST,PREF_PHONE,DMC",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

Part of the Corpdata Research Process is to establish by which media prospects are happy to receive direct marketing. The preferences include expressions made through the Preference Service Lists. These 'preferences' are an important part of respecting data subjects rights.

Therefore, we have provided 3 preference parameters which can be used to filter the response:

Parameter Key Accepted Values Example Explained
mail 0/1/Y/N mail=Y Receive only records in the licensed data set where the prospect is happy to receive direct marketing by mail
phone 0/1/Y/N phone=Y Receive only records in the licensed data set where the prospect is happy to receive direct marketing by phone
email 0/1/Y/N email=N Receive only records in the licensed data set where the prospect is not happy to receive direct marketing by email

ContactID

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&contactid=01_000000123456_000000123456789
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "Mr J Bloggs",
	"TITLE": "Mr",
	"FORENAME": "Joe",
	"INITS": "J",
	"SURNAME": "Bloggs",
	"JOB": "IT Manager",
	"DMCEMAIL": "Joe.Bloggs@corpdata.co.uk",
	"PREF_EMAIL": "Y",
	"PREF_POST": "Y",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "Computing",
	"CHANGED_FLAG": "COMPANY,POSTCODE",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

To return updated information about a signle contact in the licensed data set, you can supply the ContactID as a parameter.

Type Endpoint
contactID /update/01_000000123456_000000123456789

SiteID

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&siteid=01_000000123456
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "Mr J Bloggs",
	"TITLE": "Mr",
	"FORENAME": "Joe",
	"INITS": "J",
	"SURNAME": "Bloggs",
	"JOB": "IT Manager",
	"DMCEMAIL": "Joe.Bloggs@corpdata.co.uk",
	"PREF_EMAIL": "Y",
	"PREF_POST": "Y",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "Computing",
	"CHANGED_FLAG": "COMPANY,POSTCODE",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

To return updated information about all contacts at a single site in the licensed data set, you can supply the SiteID as a parameter.

Type Endpoint
siteID /update/01_000000703573

Columns

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&columns=company,postcode
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"COMPANY": "Corpdata Ltd",
	"POSTCODE": "TQ14 8BQ",
	"CONTACTREF": "01_000000123456_000000123456789",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

You can select the columns you wish to receive by supplying the columns parameter with a comma separated list of column names required.

You may only request columns which were included in the original licensed data set.

The following 3 columns of information will always be supplied:

Field Info
CONTACTREF Corpdata Contact ID
PROPOSAL Licensed Data Set Proposal Number
FILEFROM Corpdata File Source

DMC

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&dmc=senior
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "Mr J Bloggs",
	"TITLE": "Mr",
	"FORENAME": "Joe",
	"INITS": "J",
	"SURNAME": "Bloggs",
	"JOB": "IT Manager",
	"DMCEMAIL": "Joe.Bloggs@corpdata.co.uk",
	"PREF_EMAIL": "Y",
	"PREF_POST": "Y",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "Senior",
	"CHANGED_FLAG": "COMPANY,POSTCODE",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

There may have been several decision making contacts (DMC's) at each site included in your original licensed data set.

You may use the dmc filter to limit the returned data to only those decision makers you require.

The decision makers available are shown below:

DMC Value Description
senSenior
finFinance
mktMarketing
itComputing
salSales
purPurchasing
telTelecoms
hrPersonnel
netNetwork
fltFleet
hsHealth & Safety
fcFacilities
ecmE-Commerce
ccCall Centre
csCustomer Services

Limit/Offset

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&limit=1
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "Mr J Bloggs",
	"TITLE": "Mr",
	"FORENAME": "Joe",
	"INITS": "J",
	"SURNAME": "Bloggs",
	"JOB": "IT Manager",
	"DMCEMAIL": "",
	"PREF_EMAIL": "Y",
	"PREF_POST": "Y",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "Computing",
	"CHANGED_FLAG": "N",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

The limit parameter can be used to return a subset of the licensed data set.

It's notation is similar to MySQL limit notation.

Limits and Offsets can be combined

Parameters:

Parameter Example Info
limit3Would limit the response to 3 records
  ↳ offset10Would offset the response by 10 records - ie starting at the 11th record
limit10, 3Combines the Limit and Offset parameters to limit the response by 3 records, starting at the 11th record
Please Note: if an Offset is specified, a Limit MUST be included!

Proposal/Dataset

Request:
https://api.corpdata.co.uk/data/{licensenumber}/update?token={AccessToken}&proposal=9
Response:
{
"response": {
  "01_000000123456_000000123456789": {
	"SALUTATION": "Mr J Bloggs",
	"TITLE": "Mr",
	"FORENAME": "Joe",
	"INITS": "J",
	"SURNAME": "Bloggs",
	"JOB": "IT Manager",
	"DMCEMAIL": "",
	"PREF_EMAIL": "Y",
	"PREF_POST": "Y",
	"PREF_PHONE": "N",
	"COMPANY": "Corpdata Ltd",
	"BUILDING": "Corpdata House",
	"STREET": "6 Den Crescent",
	"SUBURB": "",
	"TOWN": "Teignmouth",
	"COUNTY": "Devon",
	"POSTCODE": "TQ14 8BQ",
	"TEL": "01626777400",
	"TELPREF": "Number screened against TPS \/ CTPS lists on 09\/11\/2018, screening valid until 07\/12\/2018",
	"SITE_EMAIL": "info@corpdata.co.uk",
	"WEBSITE": "www.corpdata.co.uk",
	"EMPNATN": 0,
	"TURNOVER": "0.00",
	"NATNBAND": "A - Will Not Disclose",
	"TO_BAND": "A - Will Not Disclose",
	"CO_TYPE": "Limited",
	"HEADOFFICE": "Single Site",
	"SITECOUNT": 1,
	"CODE": "20",
	"INDUSTRY": "Marketing",
	"ACTIVITY": "Mailing List Provider",
	"CONTACTREF": "01_000000123456_000000123456789",
	"DMC": "Computing",
	"CHANGED_FLAG": "N",
	"PROPOSAL": "9",
	"FILEFROM": "Corpdata Premium"
  }
},
"status": 200
}

To further filter results, we have enabled a proposal and dataset parameters.

The Proposal parameter specifies the various data proposals that make up your Licensed Data Set

As an example, your Corpdata Account Manager may have split your data into proposals related to Postcode area.

The dataset parameter can be used to distinguish from what dataset a certain record has originated

We currently supply data from 2 different datasets:

Dataset Description
1GDPR Compliant Data - contains Contact Data
2Site Only Data

The accepted parameters and values are:

Parameter Accepted Values
proposalNumber
dataset1/2

Terms of Use

Limitations

The Corpdata Update API is provided on a 'best efforts' basis. It is currently at Version 1. This service may experience downtime, and code using the API should handle this gracefully.

The availability and responsiveness of the Corpdata Update API is not guaranteed, and Corpdata accept no responsibility for losses or damages howsoever caused by usage of the Corpdata Update API, such as delay or failure of response.

Corpdata reserves the right to withdraw access to the Update API at any time and without notice. Use of the Update API is at your own risk and not warrantied in any way.

Fair Usage

To ensure fair access to all customers, the rate at which requests can be made to the Update API is limited, this table shows the limits.

Request Type Response Type Limit Period
Requests with the contactid or siteid parameterOne or more Licensed Data Records60 Licensed Data RecordsPer Minute
Requests without the contactid or siteid parameter (including auth)Many Licensed Data Records5 RequestsPer 10 Minutes

Your Agreement

By using the Corpdata RESTful Update API you accept the limitations and fair usage limits as detailed above.