Contacts end point allows you to create, read, update and delete contacts on your lists. A contact consists of required email and various standard and custom fields.
GET https://api.expresspigeon.com/contacts
Returns a single contact by email address.
Request parameters
| email |
Yes |
Email of contact to be selected. |
Example Request
1
2
| curl -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/contacts?email=bob@example.net'
|
1
2
3
4
5
6
7
| import org.javalite.http.Http;
import static org.javalite.common.JsonHelper.toMap;
String response = Http.get("https://api.expresspigeon.com/contacts?email=bob@example.net")
.header("X-auth-key", AUTH_KEY)
.text();
Map<String, Object> result = toMap(response);
|
1
2
3
4
5
6
7
8
9
| $options = array(
'http' => array(
'method' => 'GET',
'header' => "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
)
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/contacts?email=bob@example.net', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
response = ExpressPigeon::API.contacts.find_by_email 'john@example.com'
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.contacts.find_by_email("bob@example.net")
|
Example Response
1
2
3
4
5
6
7
8
9
10
11
| {
"custom_fields": {
"my custom field": "custom value"
},
"first_name": "Bob",
"email": "bob@example.net",
"created_at": "2012-10-29T14:17:58.000+0000",
"updated_at": "2013-01-24T08:20:52.000+0000",
"status": "ENGAGED",
"lists": [{"id": 1}, {"id": 2}}]
}
|
POST https://api.expresspigeon.com/contacts
JSON document represents a list of contacts to be created or updated. The email field is required. When updating a contact, list_id is optional, since the contact is uniquely identified by email across all lists.
Request parameters
| contacts |
Yes |
JSON list represents contacts to be inserted or updated. The email field is required. |
| list_id |
No |
List id to add contacts to. |
Standart contact fields
| email |
Yes |
254 |
| first_name |
No |
50 |
| last_name |
No |
50 |
| city |
No |
128 |
| phone |
No |
30 |
| company |
No |
128 |
| title |
No |
30 |
| address1 |
No |
255 |
| address2 |
No |
255 |
| state |
No |
48 |
| zip |
No |
24 |
| country |
No |
128 |
| date_of_birth |
No |
255 |
Note: The date_of_birth field can accept any format. However, in order to use it in segmentation and automation rules, a required format: MM/dd/yyyy.
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json" \
-d '{
"list_id": 11,
"contacts": [{
"email": "john@doe.net",
"first_name": "John",
"last_name": "Doe"
},
{
"email": "jane@doe.net",
"first_name": "Jane",
"last_name": "Doe",
"custom_fields": { "relative": "john@doe.net" }
}]
}' \
'https://api.expresspigeon.com/contacts'
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| import org.javalite.http.Http;
import static org.javalite.common.Collections.map;
import static org.javalite.common.Collections.list;
import static org.javalite.common.JsonHelper.toJsonString;
import static org.javalite.common.JsonHelper.toMap;
String content = toJsonString(
map("list_id", 11,
"contacts", list(
map("email", "john@doe.net",
"first_name", "John",
"last_name", "Doe"),
map("email", "jane@doe.net",
"first_name", "Jane",
"last_name", "Doe",
"custom_fields", map("relative", "john@doe.net"))
)));
String response = Http.post("https://api.expresspigeon.com/contacts", content)
.header("X-auth-key", AUTH_KEY)
.header("Content-type", "application/json")
.text();
Map<String, Object> result = toMap(response);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| $data = array(
'list_id' => '11',
'contacts' => array(array('email' => 'john@doe.net', 'first_name' => 'John', 'last_name' => 'Doe'),
array('email' => 'jane@doe.net', 'first_name' => 'Jane', 'last_name' => 'Doe', 'custom_fields' => array('relative' => 'john@doe.net'))
));
$options = array(
'http' => array(
'method' => 'POST',
'content' => json_encode($data),
'header' => "Content-Type: application/json\r\n" .
"X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
)
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/contacts', false, $context);
$response = json_decode($result);
|
1
2
3
4
5
| require 'expresspigeon-ruby'
resp = ExpressPigeon::API.contacts.upsert list_id,
email: "john@example.com", :first_name => 'John', :last_name => 'Doe',
:custom_fields => {:eye_color => "blue", }
|
1
2
3
4
5
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.contacts.upsert(11, [{"email": "john@doe.net", "first_name": "John", "last_name": "Doe"},
{"email": "jane@doe.net", "first_name": "Jane", "last_name": "Doe", "custom_fields": {"relative": "john@doe.net"}}])
|
Example Response
1
2
3
4
5
6
| {
"status" : "success",
"code" : 200,
"message" : "contacts created/updated successfully",
"contacts": [ "bob@example.net" ]
}
|
List of created/updated contact emails is returned for your convenience. If there is an issue with a contact (contact is suppressed, bad formatting. etc.), no changes are made to entire set of contacts and the call returns a parameter failed_contact_num which indicates the position of problem contact in the submitted document.
DELETE https://api.expresspigeon.com/contacts
NOTE: this call requires the HTTP DELETE method
Request parameters
| email |
Yes |
Contact email to be deleted |
| list_id |
No |
List id to remove contact from, if not provided, contact will be deleted from system |
Example Request
1
2
| curl -X DELETE -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
'https://api.expresspigeon.com/contacts?email=bob@example.net'
|
1
2
3
4
5
6
7
| import org.javalite.http.Http;
import static org.javalite.common.JsonHelper.toMap;
String response = Http.delete("https://api.expresspigeon.com/contacts?email=bob@example.net")
.header("X-auth-key", AUTH_KEY)
.text();
Map<String, Object> result = toMap(response);
|
1
2
3
4
5
6
7
8
9
| $options = array(
'http' => array(
'method' => 'DELETE',
'header' => "X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
)
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/contacts?email=bob@example.net', false, $context);
$response = json_decode($result);
|
1
2
3
| require 'expresspigeon-ruby'
response = ExpressPigeon::API.contacts.delete 'mary@example.com', list_id
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.contacts.delete("bob@example.net")
|
Example Response
1
2
3
4
5
| {
"status" : "success",
"code" : 200,
"message" : "contact=bob@example.net deleted successfully"
}
|
POST https://api.expresspigeon.com/contacts/move
JSON document represents a list of contacts to be moved between source and target lists. All fields are required.
Request parameters
| source_list |
Yes |
Source list id |
| target_list |
Yes |
Target list id |
| contacts |
Yes |
Contacts to be moved |
Example Request
1
2
3
4
5
6
7
8
| curl -X POST -H "X-auth-key: 00000000-0000-0000-0000-000000000000" \
-H "Content-type: application/json" \
-d '{
"source_list": 1,
"target_list": 2,
"contacts": [ "bob@example.net", "toby@example.net" ]
}' \
'https://api.expresspigeon.com/contacts/move'
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| import org.javalite.http.Http;
import static org.javalite.common.Collections.map;
import static org.javalite.common.Collections.list;
import static org.javalite.common.JsonHelper.toJsonString;
import static org.javalite.common.JsonHelper.toMap;
String content = toJsonString(map("source_list", 1,
"target_list", 2,
"contacts", list("bob@example.net", "toby@example.net")));
String response = Http.post("https://api.expresspigeon.com/contacts/move", content)
.header("X-auth-key", AUTH_KEY)
.header("Content-type", "application/json")
.text();
Map<String, Object> result = toMap(response);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| $data = array(
'source_list' => 1,
'target_list' => 2,
'contacts' => array('bob@example.net', 'toby@example.net')
);
$options = array(
'http' => array(
'method' => 'POST',
'content' => json_encode($data),
'header' => "Content-Type: application/json\r\n" .
"X-auth-key: 00000000-0000-0000-0000-000000000000\r\n"
)
);
$context = stream_context_create($options);
$result = file_get_contents('https://api.expresspigeon.com/contacts/move', false, $context);
$response = json_decode($result);
|
1
| Ruby example coming soon
|
1
2
3
4
| from expresspigeon import ExpressPigeon
api = ExpressPigeon()
response = api.contacts.move(1, 2, ["bob@example.net", "toby@example.net"])
|
Example Response
1
2
3
4
5
| {
"status" : "success",
"code" : 200,
"message" : "contacts moved from list=1 to list=2"
}
|