Execute Sequence

Trigger a sequence for one or more contacts (KEY ENDPOINT)

POST /api/v1/sequences/:id/execute

cURL

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": "[e-mail]",
        "firstName": "Alice",
        "lastName": "Johnson",
        "phone": "[phone]"
      },
      {
        "email": "[e-mail]",
        "firstName": "Bob",
        "lastName": "Williams",
        "phone": "[phone]"
      }
    ],
    "locationId": "660e8400-e29b-41d4-a716-446655440000",
    "employeeId": "770e8400-e29b-41d4-a716-446655440000"
  }'

200 Success

{
  "data": {
    "sequenceId": "880e8400-e29b-41d4-a716-446655440000",
    "sequenceName": "Post-Purchase Satisfaction Survey",
    "contactsProcessed": 2,
    "sendingsCreated": 2,
    "results": [
      {
        "email": "[e-mail]",
        "contactId": "990e8400-e29b-41d4-a716-446655440000",
        "status": "queued"
      },
      {
        "email": "[e-mail]",
        "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)

Show Contact Object

email · string · required

Contact email address

firstName · string

Contact first name

lastName · string

Contact last name

phone · string

Contact phone number (required if sequence includes SMS steps)

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

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": "[e-mail]",
        "firstName": "Alice",
        "lastName": "Johnson",
        "phone": "[phone]"
      },
      {
        "email": "[e-mail]",
        "firstName": "Bob",
        "lastName": "Williams",
        "phone": "[phone]"
      }
    ],
    "locationId": "660e8400-e29b-41d4-a716-446655440000",
    "employeeId": "770e8400-e29b-41d4-a716-446655440000"
  }'

200 Success

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

Use Cases

Post-Purchase Surveys

Trigger CSAT or NPS surveys automatically after customers complete a purchase.

executeSequence(satisfactionSequenceId, {
  contacts: [{ email: customer.email, firstName: customer.name }]
});

Service Appointment Follow-up

Send review requests after service appointments (dental, salon, etc.).

executeSequence(reviewSequenceId, {
  contacts: [{ email: appointment.customerEmail }],
  employeeId: appointment.providerId
});

Onboarding Sequences

Welcome new customers with a multi-step onboarding sequence.

executeSequence(onboardingSequenceId, {
  contacts: newSignups.map(user => ({
    email: user.email,
    firstName: user.firstName
  }))
});

Bulk Campaign

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 });
}