curl -X POST https://app.demeterrr.com/api/v1/contacts \
-H "X-API-Key: dem_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"phone": "+15559876543",
"preferredLanguage": "en",
"tags": ["new-customer"]
}'
const response = await fetch('https://app.demeterrr.com/api/v1/contacts', {
method: 'POST',
headers: {
'X-API-Key': 'dem_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'jane.smith@example.com',
firstName: 'Jane',
lastName: 'Smith',
phone: '+15559876543',
preferredLanguage: 'en',
tags: ['new-customer']
})
});
const data = await response.json();
console.log('Contact created:', data.data.id);
import requests
response = requests.post(
'https://app.demeterrr.com/api/v1/contacts',
headers={
'X-API-Key': 'dem_your_key_here',
'Content-Type': 'application/json'
},
json={
'email': 'jane.smith@example.com',
'firstName': 'Jane',
'lastName': 'Smith',
'phone': '+15559876543',
'preferredLanguage': 'en',
'tags': ['new-customer']
}
)
contact = response.json()['data']
print(f"Contact created: {contact['id']}")
{
"data": {
"id": "770e8400-e29b-41d4-a716-446655440000",
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"phone": "+15559876543",
"title": null,
"preferredLanguage": "en",
"locationId": null,
"contactOrganizationId": null,
"customFields": {},
"tags": ["new-customer"],
"unsubscribed": false,
"createdAt": "2026-02-10T15:30:00.000Z",
"updatedAt": "2026-02-10T15:30:00.000Z"
}
}
{
"error": {
"code": "CONTACT_EXISTS",
"message": "A contact with this email already exists",
"details": {
"contactId": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"email": ["Invalid email address"],
"firstName": ["First name is required"]
}
}
}
Contacts
Create Contact
Create a new contact
POST
/
api
/
v1
/
contacts
curl -X POST https://app.demeterrr.com/api/v1/contacts \
-H "X-API-Key: dem_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"phone": "+15559876543",
"preferredLanguage": "en",
"tags": ["new-customer"]
}'
const response = await fetch('https://app.demeterrr.com/api/v1/contacts', {
method: 'POST',
headers: {
'X-API-Key': 'dem_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'jane.smith@example.com',
firstName: 'Jane',
lastName: 'Smith',
phone: '+15559876543',
preferredLanguage: 'en',
tags: ['new-customer']
})
});
const data = await response.json();
console.log('Contact created:', data.data.id);
import requests
response = requests.post(
'https://app.demeterrr.com/api/v1/contacts',
headers={
'X-API-Key': 'dem_your_key_here',
'Content-Type': 'application/json'
},
json={
'email': 'jane.smith@example.com',
'firstName': 'Jane',
'lastName': 'Smith',
'phone': '+15559876543',
'preferredLanguage': 'en',
'tags': ['new-customer']
}
)
contact = response.json()['data']
print(f"Contact created: {contact['id']}")
{
"data": {
"id": "770e8400-e29b-41d4-a716-446655440000",
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"phone": "+15559876543",
"title": null,
"preferredLanguage": "en",
"locationId": null,
"contactOrganizationId": null,
"customFields": {},
"tags": ["new-customer"],
"unsubscribed": false,
"createdAt": "2026-02-10T15:30:00.000Z",
"updatedAt": "2026-02-10T15:30:00.000Z"
}
}
{
"error": {
"code": "CONTACT_EXISTS",
"message": "A contact with this email already exists",
"details": {
"contactId": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"email": ["Invalid email address"],
"firstName": ["First name is required"]
}
}
}
Authentication
Requirescontacts:write scope.
Request Body
string
required
Contact’s email address (must be valid)
string
required
Contact’s first name
string
Contact’s last name
string
Phone number (E.164 format recommended, e.g., +15551234567)
string
Job title or salutation (e.g., “Mr.”, “Dr.”, “CEO”)
string
Preferred language:
en or frstring
UUID of associated location
string
UUID of associated organization
object
Custom field values as key-value pairs
array
Array of tag strings
Response
Returns the created contact object.curl -X POST https://app.demeterrr.com/api/v1/contacts \
-H "X-API-Key: dem_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"phone": "+15559876543",
"preferredLanguage": "en",
"tags": ["new-customer"]
}'
const response = await fetch('https://app.demeterrr.com/api/v1/contacts', {
method: 'POST',
headers: {
'X-API-Key': 'dem_your_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'jane.smith@example.com',
firstName: 'Jane',
lastName: 'Smith',
phone: '+15559876543',
preferredLanguage: 'en',
tags: ['new-customer']
})
});
const data = await response.json();
console.log('Contact created:', data.data.id);
import requests
response = requests.post(
'https://app.demeterrr.com/api/v1/contacts',
headers={
'X-API-Key': 'dem_your_key_here',
'Content-Type': 'application/json'
},
json={
'email': 'jane.smith@example.com',
'firstName': 'Jane',
'lastName': 'Smith',
'phone': '+15559876543',
'preferredLanguage': 'en',
'tags': ['new-customer']
}
)
contact = response.json()['data']
print(f"Contact created: {contact['id']}")
{
"data": {
"id": "770e8400-e29b-41d4-a716-446655440000",
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"phone": "+15559876543",
"title": null,
"preferredLanguage": "en",
"locationId": null,
"contactOrganizationId": null,
"customFields": {},
"tags": ["new-customer"],
"unsubscribed": false,
"createdAt": "2026-02-10T15:30:00.000Z",
"updatedAt": "2026-02-10T15:30:00.000Z"
}
}
{
"error": {
"code": "CONTACT_EXISTS",
"message": "A contact with this email already exists",
"details": {
"contactId": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": {
"email": ["Invalid email address"],
"firstName": ["First name is required"]
}
}
}
⌘I