Quickstart

Create an API Key

Log in to your demeterrr dashboard
Navigate to Settings → API Keys
Click Create API Key
Name your key (e.g., “Test Key”)
Select scopes: contacts:read, contacts:write
Copy the key immediately (starts with dem_)

Save your API key securely! It won’t be shown again.

Make Your First Request

Let’s create a contact and then retrieve it.

# Create a contact
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": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+15551234567",
    "preferredLanguage": "en"
  }'

# List all contacts
curl https://app.demeterrr.com/api/v1/contacts \
  -H "X-API-Key: dem_your_key_here"

const API_KEY = 'dem_your_key_here';
const BASE_URL = 'https://app.demeterrr.com/api/v1';

// Create a contact
const createContact = async () => {
  const response = await fetch(`${BASE_URL}/contacts`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'john.doe@example.com',
      firstName: 'John',
      lastName: 'Doe',
      phone: '+15551234567',
      preferredLanguage: 'en'
    })
  });

  const data = await response.json();
  console.log('Contact created:', data.data);
  return data.data.id;
};

// List all contacts
const listContacts = async () => {
  const response = await fetch(`${BASE_URL}/contacts`, {
    headers: { 'X-API-Key': API_KEY }
  });

  const data = await response.json();
  console.log(`Found ${data.meta.total} contacts`);
  console.log(data.data);
};

// Run the examples
createContact().then(contactId => {
  console.log('New contact ID:', contactId);
  listContacts();
});

import requests

API_KEY = 'dem_your_key_here'
BASE_URL = 'https://app.demeterrr.com/api/v1'

headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
}

# Create a contact
contact_data = {
    'email': 'john.doe@example.com',
    'firstName': 'John',
    'lastName': 'Doe',
    'phone': '+15551234567',
    'preferredLanguage': 'en'
}

response = requests.post(
    f'{BASE_URL}/contacts',
    headers=headers,
    json=contact_data
)

contact = response.json()['data']
print(f"Contact created: {contact['id']}")

# List all contacts
response = requests.get(f'{BASE_URL}/contacts', headers=headers)
data = response.json()
print(f"Found {data['meta']['total']} contacts")

<?php

$apiKey = 'dem_your_key_here';
$baseUrl = 'https://app.demeterrr.com/api/v1';

$headers = [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
];

// Create a contact
$contactData = json_encode([
    'email' => 'john.doe@example.com',
    'firstName' => 'John',
    'lastName' => 'Doe',
    'phone' => '+15551234567',
    'preferredLanguage' => 'en'
]);

$ch = curl_init($baseUrl . '/contacts');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $contactData);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$contact = json_decode($response, true)['data'];
echo "Contact created: {$contact['id']}\n";

// List all contacts
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/contacts');
curl_setopt($ch, CURLOPT_POST, false);
$response = curl_exec($ch);
$data = json_decode($response, true);
echo "Found {$data['meta']['total']} contacts\n";

curl_close($ch);

Expected Response

When creating a contact, you’ll receive:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+15551234567",
    "title": null,
    "preferredLanguage": "en",
    "locationId": null,
    "contactOrganizationId": null,
    "customFields": {},
    "tags": [],
    "unsubscribed": false,
    "createdAt": "2026-02-10T10:30:00.000Z",
    "updatedAt": "2026-02-10T10:30:00.000Z"
  }
}

Next Steps

Now that you’ve made your first API call, explore more capabilities:

Execute a Sequence

Trigger automated workflows for contacts

Retrieve Responses

Access survey response data

Manage Reviews

Read and respond to customer reviews

Set Up Webhooks

Get real-time notifications

Common Use Cases

Sync contacts from your CRM

Create a scheduled job that periodically syncs new customers from your CRM to demeterrr using POST /api/v1/contacts.

Trigger surveys after purchase

When a customer completes a purchase in your system, execute a satisfaction survey sequence using POST /api/v1/sequences/:id/execute.

Display reviews on your website

Fetch your latest reviews with GET /api/v1/reviews and display them on your website or in marketing materials.

Analyze customer feedback

Pull all survey responses with GET /api/v1/responses and import them into your analytics platform.

Troubleshooting

401 Unauthorized Error

Verify your API key starts with dem_
Check that the key is active in your dashboard
Ensure you’re using the X-API-Key header

403 Forbidden Error

Your API key doesn’t have the required scope
Create a new key with appropriate scopes or update the existing key

409 Conflict Error

A contact with this email already exists
Use GET /api/v1/contacts?email= to find the existing contact
Use PATCH /api/v1/contacts/:id to update instead

Need Help?

API Reference

Browse all available endpoints

Support

Contact our team

Get Started

Guides

Create an API Key

Make Your First Request

Expected Response

Next Steps

Execute a Sequence

Retrieve Responses

Manage Reviews

Set Up Webhooks

Common Use Cases

Troubleshooting

Need Help?

API Reference

Support

​Create an API Key

​Make Your First Request

​Expected Response

​Next Steps

Execute a Sequence

Retrieve Responses

Manage Reviews

Set Up Webhooks

​Common Use Cases

​Troubleshooting

​Need Help?

API Reference

Support

Create an API Key

Make Your First Request

Expected Response

Next Steps

Common Use Cases

Troubleshooting

Need Help?