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.
| Parameter | Details | Description |
|---|---|---|
| group_id | query int optional | ID of the group to filter the recipients. |
| offset | query int optional | Offset for pagination. |
| limit | query int optional | Limit for pagination. |
curl "https://api-eu1.stannp.com/v1/recipients/list" \
-u {API_KEY}:
[
{
"id": "1943",
"account_id": "5",
"title": "Mr",
"firstname": "John",
"lastname": "Example",
"company": "Example Co",
"address1": "123 Example street",
"city": "Example Town",
"country": "GB",
"postcode": "EX12 3AB"
},
{
"id": "1944",
"account_id": "5",
"title": "Mrs",
"firstname": "Jane",
"lastname": "Example",
"company": "Example Co",
"address1": "123 Example street",
"city": "Example Town",
"country": "GB",
"postcode": "EX12 3AB"
}
]Obtain the recipient object for the recipient ID specified.
| Parameter | Details | Description |
|---|---|---|
| id | path int required | ID of the recipient to fetch. |
curl "https://api-eu1.stannp.com/v1/recipients/get/:id" \
-u {API_KEY}:
{
"id": "1943",
"account_id": "5",
"title": "Mr",
"firstname": "John",
"lastname": "Example",
"company": "Example Co",
"address1": "123 Example street",
"city": "Example Town",
"country": "GB",
"postcode": "EX12 3AB"
}Use the API to create a new recipient.
| Parameter | Details | Description |
|---|---|---|
| firstname | body str required | Recipient's first name. |
| lastname | body str required | Recipient's last name. |
| address1 | body str required | Address line 1. |
| address2 | body str optional | Address line 2. |
| address3 | body str optional | Address line 3. |
| city | body str required | Address city. |
| postcode | body str required | Address postal code. |
| country | body str required | ISO 3166-1 Alpha 2 Country Code (GB,US,FR...). |
body str optional | The recipient's email address. | |
| phone_number | body str optional | The recipient's phone number. |
| ref_id | body str optional | 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 | body int required | The group ID you wish to add the data to. |
| on_duplicate | body str optional | What to do if a duplicate is found (update/ignore/duplicate). |
| test_level | body str optional | 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 adding new recipient records. |
curl "https://api-eu1.stannp.com/v1/recipients/create" \
-u {API_KEY}: \
-d "firstname=Steve" \
-d "lastname=Parish" \
-d "address1=Unit 12 Taw Trade Park" \
-d "address2=Suite 100" \
-d "address3=Building A" \
-d "city=Barnstaple" \
-d "postcode=EX31 1JZ" \
-d "country=GB" \
-d "email=steve.parish@example.com" \
-d "phone_number=+441234567890" \
-d "ref_id=SP12345" \
-d "group_id=123" \
-d "on_duplicate=update" \
-d "test_level=fullname"
{
"id": "1941",
"valid": true
}Use the API to permanently delete a recipient from your account.
| Parameter | Details | Description |
|---|---|---|
| id | body int required | ID of the recipient to delete. |
curl "https://api-eu1.stannp.com/v1/recipients/delete" \
-u {API_KEY}: \
-d "id=12345"
{
"success": true
}Use the API to permanently delete all recipients in your account.
| Parameter | Details | Description |
|---|---|---|
| delete_all | body bool required | Set to true to confirm. **WARNING:** This will completely delete all recipients in your account. This cannot be reversed. |
curl "https://api-eu1.stannp.com/v1/recipients/deleteAll" \
-u {API_KEY}: \
-d "delete_all=true"
{
"success": true
}Use the API to import a data file into your account.
| Parameter | Details | Description |
|---|---|---|
| file | body file required | A CSV or XLS file as binary format, a base64 encoded string of a CSV file, or a URL to a file. |
| group_id | body int required | ID of the group you wish to import data into. |
| duplicates | body str 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 | body bool 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 | body str 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. |
curl "https://api-eu1.stannp.com/v1/recipients/import" \
-u {API_KEY}: \
-d "file=/home/user/Desktop/data.csv" \
-d "group_id=123" \
-d "duplicates=update" \
-d "no_headings=false" \
-d "mappings=title,firstname,lastname,company,address1,address2,city,postcode,country,custom,custom,skip"
{
"success": true
}