> ## Documentation Index
> Fetch the complete documentation index at: https://demeterrr.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first API call in 5 minutes

## Create an API Key

1. Log in to your [demeterrr dashboard](https://app.demeterrr.com)
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_`)

<Warning>
  Save your API key securely! It won't be shown again.
</Warning>

## Make Your First Request

Let's create a contact and then retrieve it.

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```javascript JavaScript theme={null}
  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();
  });
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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);
  ```
</CodeGroup>

## Expected Response

When creating a contact, you'll receive:

```json theme={null}
{
  "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:

<CardGroup cols={2}>
  <Card title="Execute a Sequence" icon="play" href="/api-reference/sequences/execute">
    Trigger automated workflows for contacts
  </Card>

  <Card title="Retrieve Responses" icon="chart-line" href="/api-reference/responses/list">
    Access survey response data
  </Card>

  <Card title="Manage Reviews" icon="star" href="/api-reference/reviews/list">
    Read and respond to customer reviews
  </Card>

  <Card title="Set Up Webhooks" icon="webhook" href="/guides/webhooks">
    Get real-time notifications
  </Card>
</CardGroup>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Sync contacts from your CRM">
    Create a scheduled job that periodically syncs new customers from your CRM to demeterrr using `POST /api/v1/contacts`.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="Display reviews on your website">
    Fetch your latest reviews with `GET /api/v1/reviews` and display them on your website or in marketing materials.
  </Accordion>

  <Accordion title="Analyze customer feedback">
    Pull all survey responses with `GET /api/v1/responses` and import them into your analytics platform.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="403 Forbidden Error">
    * Your API key doesn't have the required scope
    * Create a new key with appropriate scopes or update the existing key
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/contacts/list">
    Browse all available endpoints
  </Card>

  <Card title="Support" icon="envelope" href="mailto:support@demeterrr.com">
    Contact our team
  </Card>
</CardGroup>