List recipients
Use the API to obtain a list of recipient objects.Include
group_id
to only return recipients in the specified group.
You can use the
offset
and limit
parameters for pagination.
https://api-eu1.stannp.com/v1/recipients/list/:group_id
Request
$ curl https://api-eu1.stannp.com/v1/recipients/list/123 \ -u {API_KEY}:
define("API_KEY", "YOUR API KEY"); $opts = array( 'http' => array( 'method' => 'GET', 'header' => 'Content-type: application/x-www-form-urlencoded' ) ); $context = stream_context_create($opts); $result = file_get_contents("https://api-eu1.stannp.com/v1/recipients/list/123?api_key=" . API_KEY, false, $context); $response = json_decode($result, true); print_r($response);
import requests response = requests.get('https://api-eu1.stannp.com/v1/recipients/list/123?api_key={API_KEY}') print(response.text)
var client = new RestClient("https://api-eu1.stannp.com/v1/recipients/list/123?api_key={API_KEY}"); var request = new RestRequest(Method.GET); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content);Return
{ "success":true, "data":[ { "id":"1943", "account_id":"5", "email":"", "phone_number":"", "title":"Mr", "firstname":"John", "lastname":"Example", "company":"Example Co", "job_title":null, "address1":"123", "address2":"Example street", "address3":null, "city":"Example Town", "county":"", "country":"GB", "postcode":"EX12 3AB", "dps":"1A", "checksum":"3", "ref_id":null, "blacklist":"0", "paffed_by":"auto" }, { "id":"1944", "account_id":"5", "email":"", "phone_number":"", "title":"Mrs", "firstname":"Jane", "lastname":"Example", "company":"Example Co", "job_title":null, "address1":"123", "address2":"Example street", "address3":null, "city":"Example Town", "county":null, "country":"GB", "postcode":"EX12 3AB", "dps":"1A", "checksum":"3", "ref_id":null, "blacklist":"0", "paffed_by":"auto" } ] }
Get a single recipient
Obtain the recipient object for the recipient id
specified.
https://api-eu1.stannp.com/v1/recipients/get/:id
Request
$ curl https://api-eu1.stannp.com/v1/recipients/get/1234 \ -u {API_KEY}:
define("API_KEY", "YOUR API KEY"); $opts = array( 'http' => array( 'method' => 'GET', 'header' => 'Content-type: application/x-www-form-urlencoded' ) ); $context = stream_context_create($opts); $result = file_get_contents("https://api-eu1.stannp.com/v1/recipients/get/1234?api_key=" . API_KEY, false, $context); $response = json_decode($result, true); print_r($response);
import requests response = requests.get('https://api-eu1.stannp.com/v1/recipients/get/1234?api_key={API_KEY}') print(response.text)
var client = new RestClient("https://api-eu1.stannp.com/v1/recipients/get/1234?api_key={API_KEY}"); var request = new RestRequest(Method.GET); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content);Return
{ "success":true, "data":{ "id":"1943", "account_id":"5", "email":"", "phone_number":"", "title":"Mr", "firstname":"John", "lastname":"Example", "company":"Example Co", "job_title":null, "address1":"123", "address2":"Example street", "address3":null, "city":"Example Town", "county":null, "country":"GB", "postcode":"EX12 3AB", "dps":"1A", "checksum":"3", "ref_id":null, "blacklist":"0", "paffed_by":"auto" } }
Create a new recipient
Use the API to create a new recipient.https://api-eu1.stannp.com/v1/recipients/new
Parameters
firstname | string | Recipients first name. |
lastname | string | Recipients last name. |
address1 | string | Address line 1. |
address2 | string | Address line 2. |
address3 | string | Address line 3. |
city | string | Address city. |
postcode | string | Address postal code. |
country | string | ISO 3166-1 Alpha 2 Country Code (GB,US,FR...). |
string | The recipients email address. | |
phone_number | string | The recipients phone number. |
ref_id | string | This is an alternative id. You can use an id from a different service so you can always match a recipient across multiple services. |
group_id | int | The group ID you wish to add the data to. |
on_duplicate | string | What to do if a duplicate is found (update/ignore/duplicate). |
test_level | string | This is how we test to see if this recipient is a duplicate record. You can choose from the following. Defaults to 'fullname'.
'email' - This will match a duplicate based on the email address. 'fullname' - This will match a duplicate based on the full name and address. 'initial' - This will match a duplicate based on the initial of the first plus last name and address. 'ref_id' - This will match a duplicate on any alternative ID you have stored. |
? | ? | If you have added custom fields to your recipients you can also add them as parameters when added new recipient records. |
Request
$ curl https://api-eu1.stannp.com/v1/recipients/new \ -u {API_KEY}: \ -d "group_id=1" \ -d "on_duplicate=update" \ -d "firstname=Steve" \ -d "lastname=Parish" \ -d "address1=Unit 12 Taw Trade Park" \ -d "address2=Braunton Road" \ -d "city=Barnstaple" \ -d "postcode=EX31 1JZ" \ -d "country=GB" \ -d "voucher=GT4523"
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://api-eu1.stannp.com/v1/recipients/new?api_key={API_KEY}', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array( 'group_id' => "1", 'on_duplicate' => "update", 'firstname' => "Steve", 'lastname' => "Parish", 'address1' => "Unit 12 Taw Trade Park", 'address2' => "Braunton Road", 'city' => "Barnstaple", 'postcode' => "EX31 1JZ", 'country' => "GB", 'voucher' => "GT4523" ), )); $response = curl_exec($curl); curl_close($curl); print_r($response);
import requests data = { 'group_id': '1', 'on_duplicate': 'update', 'firstname': 'Steve', 'lastname': 'Parish', 'address1': 'Unit 12 Taw Trade Park', 'address2': 'Braunton Road', 'city': 'Barnstaple', 'postcode': 'EX31 1JZ', 'country': 'GB', 'voucher': 'GT4523' } response = requests.post('https://api-eu1.stannp.com/v1/recipients/new?api_key={API_KEY}', data=data) print(response.text)
var client = new RestClient("https://api-eu1.stannp.com/v1/recipients/new?api_key={API_KEY}"); var request = new RestRequest(Method.POST); request.AddParameter("group_id", "1"); request.AddParameter("on_duplicate", "update"); request.AddParameter("firstname", "Steve"); request.AddParameter("lastname", "Parish"); request.AddParameter("address1", "Unit 12 Taw Trade Park"); request.AddParameter("address2", "Braunton Road"); request.AddParameter("city", "Barnstaple"); request.AddParameter("postcode", "EX31 1JZ"); request.AddParameter("country", "GB"); request.AddParameter("voucher", "GT4523"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content)Return
{ "success":true, "data":{ "id":"1941", "valid":true } }
Delete a recipient
Use the API to permanently delete a recipient from your account.https://api-eu1.stannp.com/v1/recipients/delete
Parameters
id | int | The id of the recipient to delete. |
Request
$ curl https://api-eu1.stannp.com/v1/recipients/delete \ -u {API_KEY}: \ -d "id=12345"
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://api-eu1.stannp.com/v1/recipients/delete?api_key={API_KEY}', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array( 'id' => "12345" ), )); $response = curl_exec($curl); curl_close($curl); print_r($response);
import requests data = { 'id': '12345' } response = requests.post('https://api-eu1.stannp.com/v1/recipients/delete?api_key={API_KEY}', data=data) print(response.text)
var client = new RestClient("https://api-eu1.stannp.com/v1/recipients/delete?api_key={API_KEY}"); var request = new RestRequest(Method.POST); request.AddParameter("id", "12345"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content)Response
{ "success":true }
Delete all recipients from whole account
Use the API to permanently delete all recipients in your account.https://api-eu1.stannp.com/v1/recipients/deleteAll
Parameters
delete_all | bool |
Set to true to confirm. WARNING: This will completely delete all recipients in your account. This can not be reversed. |
Request
$ curl https://api-eu1.stannp.com/v1/recipients/deleteAll \ -u {API_KEY}: \ -d "delete_all=1"
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://api-eu1.stannp.com/v1/recipients/deleteAll?api_key={API_KEY}', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array( 'delete_all' => "1" ), )); $response = curl_exec($curl); curl_close($curl); print_r($response);
import requests data = { 'delete_all': '1' } response = requests.post('https://api-eu1.stannp.com/v1/recipients/deleteAll?api_key={API_KEY}', data=data) print(response.text)
var client = new RestClient("https://api-eu1.stannp.com/v1/recipients/deleteAll?api_key={API_KEY}"); var request = new RestRequest(Method.POST); request.AddParameter("delete_all", "1"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content)Response
{ "success":true, "data":{} }
Import a data file
Use the API to import a data file in to your account.https://api-eu1.stannp.com/v1/recipients/import
Parameters
file | mandatory | A CSV or XLS file as binary format, a base64 encoded string of a CSV file or a URL to a file. |
group_id | mandatory | Id of the group you wish to import data into. |
duplicates | optional | What to do if a duplicate is found (update/ignore/duplicate). update = [default] Updates the duplicated record with newest data. ignore = do not add the new duplicated record. duplicate = Add all duplicate records. |
no_headings | optional | True or false. If your CSV file hasn't got a row of heading names at the top you can set this value to true. If you do not have a heading row then you must supply the headings by using the following mappings parameter. |
mappings | optional |
If your CSV file has a heading row with names that differ to our names
then you can pass a comma separated string here to remap the headings.
eg: title, firstname, lastname, company, address1, address2, city, postcode, country,
custom, custom, skip.
"custom" means we will create a new field name matching your heading name. "skip" will ignore the column so it is not imported. If you do not use this parameter then your heading names must match ours exactly. title, firstname, lastname, company, job_title, address1, address2, address3, city, postcode, country. |
Request
$ curl https://api-eu1.stannp.com/v1/recipients/import \ -u {API_KEY}: \ -d "group_id=123" \ -F "file=/home/user/Desktop/data.csv"
$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://api-eu1.stannp.com/v1/recipients/import?api_key={API_KEY}', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array( 'group_id' => "123", 'file' => new CURLFILE('/home/user/Desktop/data.csv') ), )); $response = curl_exec($curl); curl_close($curl); print_r($response);
import requests data = { 'group_id': '123' } files = { file: open('/home/user/Desktop/data.csv','rb') } response = requests.post('https://api-eu1.stannp.com/v1/recipients/import?api_key={API_KEY}', data=data, files=files) print(response.text)
var client = new RestClient("https://api-eu1.stannp.com/v1/recipients/import?api_key={API_KEY}"); var request = new RestRequest(Method.POST); request.AddParameter("group_id", "123"); request.AddFile("file", "/home/user/Desktop/data.csv"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content)Response
{ "success": true, "data": true }