Skip to main content

​
Create an API Key

  1. Log in to your demeterrr dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Name your key (e.g., “Test Key”)
  5. Select scopes: contacts:read, contacts:write
  6. 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"

​
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

Create a scheduled job that periodically syncs new customers from your CRM to demeterrr using POST /api/v1/contacts.
When a customer completes a purchase in your system, execute a satisfaction survey sequence using POST /api/v1/sequences/:id/execute.
Fetch your latest reviews with GET /api/v1/reviews and display them on your website or in marketing materials.
Pull all survey responses with GET /api/v1/responses and import them into your analytics platform.

​
Troubleshooting

  • 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
  • Your API key doesn’t have the required scope
  • Create a new key with appropriate scopes or update the existing key
  • 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