Skip to main content
POST
/
api
/
v1
/
sequences
/
:id
/
execute
curl -X POST https://app.demeterrr.com/api/v1/sequences/880e8400-e29b-41d4-a716-446655440000/execute \
  -H "X-API-Key: dem_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "email": "customer1@example.com",
        "firstName": "Alice",
        "lastName": "Johnson",
        "phone": "+15551234567"
      },
      {
        "email": "customer2@example.com",
        "firstName": "Bob",
        "lastName": "Williams",
        "phone": "+15559876543"
      }
    ],
    "locationId": "660e8400-e29b-41d4-a716-446655440000",
    "employeeId": "770e8400-e29b-41d4-a716-446655440000"
  }'

{
  "data": {
    "sequenceId": "880e8400-e29b-41d4-a716-446655440000",
    "sequenceName": "Post-Purchase Satisfaction Survey",
    "contactsProcessed": 2,
    "sendingsCreated": 2,
    "results": [
      {
        "email": "customer1@example.com",
        "contactId": "990e8400-e29b-41d4-a716-446655440000",
        "status": "queued"
      },
      {
        "email": "customer2@example.com",
        "contactId": "aa0e8400-e29b-41d4-a716-446655440000",
        "status": "queued"
      }
    ]
  }
}
Most Important Endpoint: This is the primary integration point for triggering automated customer workflows.

​
Authentication

Requires sequences:execute scope.

​
Path Parameters

​
id
string
required
Sequence UUID

​
Request Body

​
contacts
array
required
Array of contact objects (min: 1, max: 100)
​
locationId
string
Location UUID to associate with all contacts
​
employeeId
string
Employee UUID to associate with all contacts (for attribution)

​
How It Works

  1. Contact Creation/Update: Contacts are created if they don’t exist, or updated if they do (matched by email)
  2. Sequence Validation: Sequence must be active status
  3. Sending Creation: Creates a sending record for each contact
  4. Background Execution: Triggers Inngest background job to execute the sequence steps
  5. Immediate Response: Returns immediately without waiting for execution to complete
Use this endpoint to trigger surveys after purchase, onboarding sequences for new customers, or review requests after service completion.
curl -X POST https://app.demeterrr.com/api/v1/sequences/880e8400-e29b-41d4-a716-446655440000/execute \
  -H "X-API-Key: dem_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "email": "customer1@example.com",
        "firstName": "Alice",
        "lastName": "Johnson",
        "phone": "+15551234567"
      },
      {
        "email": "customer2@example.com",
        "firstName": "Bob",
        "lastName": "Williams",
        "phone": "+15559876543"
      }
    ],
    "locationId": "660e8400-e29b-41d4-a716-446655440000",
    "employeeId": "770e8400-e29b-41d4-a716-446655440000"
  }'

{
  "data": {
    "sequenceId": "880e8400-e29b-41d4-a716-446655440000",
    "sequenceName": "Post-Purchase Satisfaction Survey",
    "contactsProcessed": 2,
    "sendingsCreated": 2,
    "results": [
      {
        "email": "customer1@example.com",
        "contactId": "990e8400-e29b-41d4-a716-446655440000",
        "status": "queued"
      },
      {
        "email": "customer2@example.com",
        "contactId": "aa0e8400-e29b-41d4-a716-446655440000",
        "status": "queued"
      }
    ]
  }
}

​
Use Cases

Trigger CSAT or NPS surveys automatically after customers complete a purchase.
executeSequence(satisfactionSequenceId, {
  contacts: [{ email: customer.email, firstName: customer.name }]
});
Send review requests after service appointments (dental, salon, etc.).
executeSequence(reviewSequenceId, {
  contacts: [{ email: appointment.customerEmail }],
  employeeId: appointment.providerId
});
Welcome new customers with a multi-step onboarding sequence.
executeSequence(onboardingSequenceId, {
  contacts: newSignups.map(user => ({
    email: user.email,
    firstName: user.firstName
  }))
});
Execute marketing campaigns for up to 100 contacts at once.
// Process in batches of 100
for (let i = 0; i < allContacts.length; i += 100) {
  const batch = allContacts.slice(i, i + 100);
  await executeSequence(campaignId, { contacts: batch });
}