REST APIContacts
Contacts Endpoints
Create, update, delete, and manage contacts in your audiences.
POST
/api/contactsCreate Contact
Create a new contact in an audience.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Contact email address |
audienceId | string | Yes | ID of the audience to add contact to |
firstName | string | No | Contact's first name |
lastName | string | No | Contact's last name |
phone | string | No | Phone number |
status | string | No | subscribed, unsubscribed, pending, bounced |
tags | string[] | No | Array of tags |
customFields | object | No | Custom field values |
Example Request
curlTerminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl -X POST https://api.metigan.com/api/contacts \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"email": "john@example.com",
"audienceId": "aud_abc123",
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890",
"status": "subscribed",
"tags": ["customer", "newsletter"],
"customFields": {
"company": "Acme Inc",
"role": "Developer"
}
}'Response
201 CreatedJSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"success": true,
"data": {
"id": "con_xyz789",
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890",
"status": "subscribed",
"audienceId": "aud_abc123",
"tags": ["customer", "newsletter"],
"customFields": {
"company": "Acme Inc",
"role": "Developer"
},
"createdAt": "2024-01-19T10:30:00Z",
"updatedAt": "2024-01-19T10:30:00Z"
}
}GET
/api/contactsList Contacts
Retrieve a paginated list of contacts with optional filters.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
audienceId | string | Filter by audience ID |
status | string | Filter by status |
tag | string | Filter by tag |
search | string | Search by email or name |
page | number | Page number (default: 1) |
limit | number | Items per page (default: 50, max: 100) |
Example Request
curlTerminal
1
2
curl -X GET "https://api.metigan.com/api/contacts?audienceId=aud_abc123&status=subscribed&page=1&limit=50" \
-H "x-api-key: your_api_key"Response
200 OKJSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"success": true,
"contacts": [
{
"id": "con_xyz789",
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"status": "subscribed",
"audienceId": "aud_abc123",
"tags": ["customer"],
"createdAt": "2024-01-19T10:30:00Z"
}
],
"pagination": {
"total": 1234,
"page": 1,
"limit": 50,
"pages": 25
}
}GET
/api/contacts/:idGet Contact
Retrieve a single contact by ID.
Example Request
curlTerminal
1
2
curl -X GET https://api.metigan.com/api/contacts/con_xyz789 \
-H "x-api-key: your_api_key"Response
200 OKJSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"success": true,
"data": {
"id": "con_xyz789",
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe",
"phone": "+1234567890",
"status": "subscribed",
"audienceId": "aud_abc123",
"tags": ["customer", "newsletter"],
"customFields": {
"company": "Acme Inc"
},
"createdAt": "2024-01-19T10:30:00Z",
"updatedAt": "2024-01-19T10:30:00Z",
"lastActivityAt": "2024-01-19T12:00:00Z"
}
}GET
/api/contacts/email/:emailGet Contact by Email
Retrieve a contact by email address within an audience.
Example Request
curlTerminal
1
2
curl -X GET "https://api.metigan.com/api/contacts/email/john@example.com?audienceId=aud_abc123" \
-H "x-api-key: your_api_key"PATCH
/api/contacts/:idUpdate Contact
Update an existing contact's information.
Request Body
Only include fields you want to update.
| Field | Type | Description |
|---|---|---|
firstName | string | First name |
lastName | string | Last name |
phone | string | Phone number |
status | string | Contact status |
tags | string[] | Replace all tags |
customFields | object | Custom field values |
Example Request
curlTerminal
1
2
3
4
5
6
7
8
9
10
curl -X PATCH https://api.metigan.com/api/contacts/con_xyz789 \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Johnny",
"tags": ["customer", "vip", "newsletter"],
"customFields": {
"company": "New Company Inc"
}
}'Response
200 OKJSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"success": true,
"data": {
"id": "con_xyz789",
"email": "john@example.com",
"firstName": "Johnny",
"lastName": "Doe",
"status": "subscribed",
"tags": ["customer", "vip", "newsletter"],
"customFields": {
"company": "New Company Inc"
},
"updatedAt": "2024-01-19T14:00:00Z"
}
}DELETE
/api/contacts/:idDelete Contact
Permanently delete a contact.
Irreversible Action
This action cannot be undone. Consider changing the contact's status to "unsubscribed" instead.
Example Request
curlTerminal
1
2
curl -X DELETE https://api.metigan.com/api/contacts/con_xyz789 \
-H "x-api-key: your_api_key"Response
200 OKJSON
1
2
3
4
{
"success": true,
"message": "Contact deleted successfully"
}POST
/api/contacts/bulkBulk Import Contacts
Import multiple contacts at once. Duplicates are automatically handled.
Request Body
| Field | Type | Description |
|---|---|---|
audienceId | string | Target audience ID |
contacts | array | Array of contact objects (max 1000) |
skipDuplicates | boolean | Skip instead of updating duplicates |
Example Request
curlTerminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
curl -X POST https://api.metigan.com/api/contacts/bulk \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"audienceId": "aud_abc123",
"skipDuplicates": true,
"contacts": [
{
"email": "user1@example.com",
"firstName": "User",
"lastName": "One",
"tags": ["import"]
},
{
"email": "user2@example.com",
"firstName": "User",
"lastName": "Two",
"tags": ["import"]
}
]
}'Response
200 OKJSON
1
2
3
4
5
6
7
{
"success": true,
"imported": 2,
"failed": 0,
"skipped": 0,
"errors": []
}Contact Statuses
Available contact status values:
| Status | Description |
|---|---|
subscribed | Active subscriber, can receive emails |
pending | Awaiting confirmation (double opt-in) |
unsubscribed | Opted out, will not receive emails |
bounced | Email bounced, delivery failed |
complained | Marked email as spam |