REST API

Table of Contents#

1. System Overview
2. Authentication
3. Quick Start: Chatbot Integration
4. Conversations API
5. Contacts API
6. Calendar & Booking API
7. Opportunities, Tasks & Pipelines API
8. Campaigns API
9. Webhooks (Real-Time Events)
10. Workflow Triggers
11. Pagination
12. Error Examples
13. Rate Limits & Best Practices
14. Versioning & Stability
15. Future Roadmap

1. System Overview#

Architecture#

┌──────────────────────┐
│  Your System         │
│  (Chatbot / CRM /    │
│   Automation Tool)   │
└──────────┬───────────┘
           │
           │  Authorization: Bearer sk_live_...
           │
┌──────────▼───────────┐
│  REST API            │
│  /api/v1/*           │
│                      │
│  Contacts, Messages, │
│  Calendars, Deals,   │
│  Tasks, Webhooks     │
└──────────┬───────────┘
           │
┌──────────▼───────────┐     ┌─────────────────────┐
│  Seedly CRM Backend  │────▶│  Messaging Providers │
│                      │     │                      │
│  Business logic,     │     │  SMS, Email, Gmail,  │
│  automation engine,  │     │  Messenger, Instagram│
│  event dispatch      │     │                      │
└──────────┬───────────┘     └─────────────────────┘
           │
           │  Outbound Webhooks (HTTPS POST)
           │
┌──────────▼───────────┐
│  Your Webhook Server │
│  (receives events)   │
└──────────────────────┘

Key Concepts#

• Sub-Account: Each customer or brand operates within a sub-account. All API calls are scoped to a single sub-account via the API key.
• Channels: Conversations span multiple channels - sms, email, messenger, instagram, gmail, live_chat, social_dm.
• Contacts: The central entity. Every conversation, appointment, and opportunity is linked to a contact.
• Workflows: Automation sequences triggered by events. External systems can trigger workflows and receive event notifications.

Base URL#

https://{YOUR_DEPLOYMENT_URL}

Your deployment URL is found in the Seedly CRM dashboard under Settings.

Response Format#

All REST API responses use a consistent JSON envelope:

Success:

{
  "data": { ... },
  "meta": { "total": 100, "hasMore": true, "cursor": "..." }
}

Error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "firstName and lastName are required"
  }
}

2. Authentication#

API Keys#

The REST API uses API key authentication. Each key is scoped to a single sub-account and has configurable permissions.

Header format:

Authorization: Bearer sk_live_...

Your customer (the sub-account admin) creates the API key in their Seedly CRM dashboard and shares it with you.

CORS warning: API key endpoints are server-to-server only. Do not embed API keys in client-side JavaScript.

Obtaining an API Key#

1. Navigate to Settings > Integrations in the Seedly CRM dashboard
2. Click the API Keys card
3. Click Create Key, enter a name, and select the permission scopes you need
4. Copy the key immediately - it is shown once and cannot be retrieved later

Available Scopes#

Recommended scopes for a chatbot integration: contacts:read, contacts:write, conversations:read, conversations:write, calendars:read.

Agency-scoped keys use the same scopes. The key operates on whichever sub-account is specified via the X-Sub-Account-Id header.

Key Lifecycle#

• Active - Key is valid and accepting requests
• Expired - Key has passed its optional expiration date (returns 401 KEY_EXPIRED)
• Revoked - Key was manually revoked (returns 401 KEY_REVOKED)

Keys can be revoked at any time from the settings UI. Revocation is immediate.

Agency-Scoped API Keys#

Agency-scoped API keys work across all sub-accounts under an agency, rather than being tied to a single sub-account. They use the prefixes sk_agency_live_ (production) or sk_agency_test_ (sandbox).

Because an agency-scoped key can access any sub-account, every request must include the X-Sub-Account-Id header to specify which sub-account the call should operate on:

Authorization: Bearer sk_agency_live_...
X-Sub-Account-Id: sub_abc123

Omitting the header returns a 400 error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "X-Sub-Account-Id header is required for agency-scoped API keys"
  }
}

Discovering Sub-Account IDs#

Use the discovery endpoint to list all sub-accounts available to the agency key:

GET /api/v1/sub-accounts
Authorization: Bearer sk_agency_live_...

Response:

{
  "data": [
    { "id": "sub_abc123", "name": "Acme Corp" },
    { "id": "sub_def456", "name": "Widget Co" }
  ]
}

Note: This endpoint requires an agency-scoped key. Sub-account-scoped keys (sk_live_) cannot call it.

Typical Integration Flow#

1. Agency owner creates an agency-scoped API key in Settings > Integrations > API Keys and selects "Agency-wide" scope.
2. Discover sub-accounts by calling GET /api/v1/sub-accounts to retrieve the list of sub-account IDs.
3. Include X-Sub-Account-Id on all subsequent calls to target the desired sub-account.

# Step 2 - Discover sub-accounts
GET /api/v1/sub-accounts
Authorization: Bearer sk_agency_live_...
 
# Step 3 - List contacts for a specific sub-account
GET /api/v1/contacts
Authorization: Bearer sk_agency_live_...
X-Sub-Account-Id: sub_abc123

Backward compatibility: Sub-account-scoped keys (sk_live_, sk_test_) continue to work exactly as before. They do not require the X-Sub-Account-Id header - the sub-account is implicit in the key itself.

Public Endpoints (No Key Required)#

Some endpoints are public and do not require an API key:

3. Quick Start: Chatbot Integration#

This walkthrough shows how to build a chatbot integration that receives messages, processes them, and sends replies.

Flow#

1. Receive webhook  ──▶  2. Look up contact  ──▶  3. Get conversation context
       │                                                      │
       │                                                      ▼
6. Track delivery   ◀──  5. Send reply        ◀──  4. Process with AI/logic

Step-by-Step#

Step 1 - Receive message.received webhook event

Configure a webhook subscription (see Webhooks) to listen for message.received. When a message arrives, your server receives:

{
  "event": "message.received",
  "timestamp": "2026-03-27T14:30:00.000Z",
  "data": {
    "subAccountId": "sa_001",
    "contactId": "contact_abc123",
    "messageId": "msg_abc123",
    "conversationId": "conv_xyz789",
    "channel": "email",
    "bodyText": "Hi, I'd like to book an appointment",
    "fromAddress": "[email protected]",
    "direction": "inbound",
    "tags": ["website-lead"]
  }
}

Step 2 - Look up the contact

GET /api/v1/[email protected]
Authorization: Bearer sk_live_...

This returns an array with the matching contact (or an empty array if not found).

Step 3 - Get conversation messages for context

GET /api/v1/conversations/{conversationId}/messages?limit=20
Authorization: Bearer sk_live_...

Retrieve recent messages to provide conversation history to your AI or processing logic.

Step 4 - Process with your AI/logic

Pass the conversation history and the new message to your chatbot engine, LLM, or business logic layer.

Step 5 - Send reply

POST /api/v1/conversations/{conversationId}/messages
Authorization: Bearer sk_live_...
Content-Type: application/json
 
{
  "bodyText": "I'd be happy to help you book an appointment! What day works best?",
  "channel": "email",
  "toAddress": "[email protected]",
  "subject": "Re: Appointment Request"
}

Step 6 - Track delivery

Listen for message.sent, message.delivered, and message.failed webhook events to confirm your reply was delivered successfully.

4. Conversations API#

Data Model#

Conversation:

Message:

Endpoints#

Create Conversation#

POST /api/v1/conversations

Scope: conversations:write

Request body:

{
  "contactId": "contact_id_here",
  "channel": "email",
  "subject": "Welcome to our service"
}

Response:

• 201 Created - New conversation created. Response includes "created": true.
• 200 OK - An existing open conversation was found for this contact and channel. Response includes "created": false.

{
  "data": {
    "id": "conv_xyz789",
    "contactId": "contact_id_here",
    "channel": "email",
    "status": "open",
    "created": true
  }
}

List Conversations#

GET /api/v1/conversations

Scope: conversations:read

Query parameters:

• status - open, closed, snoozed
• channel - Filter by channel type
• contactId - Filter by contact ID to find all conversations for a specific contact
• assignedTo - Filter by team member ID
• limit - Max results (default 50, max 100)

Response: Array of conversations with embedded contact summary.

Get Conversation#

GET /api/v1/conversations/{id}

Scope: conversations:read

List Messages#

GET /api/v1/conversations/{id}/messages

Scope: conversations:read

Query parameters:

• limit - Max results (default 50, max 100)
• cursor - Pagination cursor from previous response

Response:

{
  "data": [
    /* messages, newest first */
  ],
  "meta": { "hasMore": true, "cursor": "..." }
}

Send Message#

POST /api/v1/conversations/{id}/messages

Scope: conversations:write

Request body:

{
  "bodyText": "Hello {{firstName}}, your appointment is confirmed.",
  "channel": "sms",
  "toAddress": "+15551234567",
  "subject": "Appointment Confirmation",
  "bodyHtml": "<p>Hello...</p>"
}

Channel routing: The system automatically sends through the configured provider for the channel (e.g., SMS goes via the configured SMS provider, email via the configured email provider).

Merge fields: {{firstName}}, {{lastName}}, {{email}}, {{phone}}, {{company}}, {{fullName}}, and {{custom_values.key}} are resolved at send time.

DND enforcement: If the contact has opted out of a channel, the send will be silently skipped.

Update Conversation#

PATCH /api/v1/conversations/{id}

Scope: conversations:write

Request body:

{
  "status": "closed",
  "assignedTo": "user_id_here"
}

Both fields are optional. Set assignedTo to null to unassign.

Live Chat (Public, No Key Required)#

5. Contacts API#

Data Model#

Endpoints#

List Contacts#

GET /api/v1/contacts

Scope: contacts:read

Query parameters:

• search - Full-text search (name, email, company)
• email - Exact email match. Returns array with single contact or empty array. More efficient than search for programmatic lookups.
• limit - Max results (default 50, max 100)
• cursor - Pagination cursor
• lifecycleStage - Filter by stage
• source - Filter by lead source
• tags - Comma-separated tag filter (e.g., tags=vip,enterprise)
• assignedTo - Filter by team member ID
• hasPhone - true to only return contacts with phone numbers

Response:

{
  "data": [
    /* contacts */
  ],
  "meta": { "total": 150, "hasMore": true, "cursor": "..." }
}

Get Contact#

GET /api/v1/contacts/{id}

Scope: contacts:read

Get Custom Field Definitions#

GET /api/v1/contacts/fields

Scope: contacts:read

Returns the list of custom field definitions configured for the sub-account.

Response:

{
  "data": [
    {
      "name": "preferred_language",
      "label": "Preferred Language",
      "type": "select",
      "options": ["English", "Spanish", "French"],
      "isRequired": false
    },
    {
      "name": "company_size",
      "label": "Company Size",
      "type": "number",
      "options": null,
      "isRequired": true
    }
  ]
}

Each field definition includes:

Create Contact#

POST /api/v1/contacts

Scope: contacts:write

Request body:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "+15551234567",
  "company": "Acme Corp",
  "lifecycleStage": "lead",
  "tags": ["website-lead"],
  "source": "api"
}

Side effects:

• Fires contact.created webhook event
• Triggers matching workflow automations
• Validates custom field schemas if provided

Response: 201 Created with the full contact object.

Update Contact#

PATCH /api/v1/contacts/{id}

Scope: contacts:write

Include only the fields you want to change.

{
  "lifecycleStage": "customer",
  "tags": ["vip", "enterprise"]
}

Side effects:

• Fires contact.updated webhook event
• If tags added: fires contact.tag_added event per new tag
• If lifecycleStage changed: fires contact.lifecycle_changed event

Delete Contact#

DELETE /api/v1/contacts/{id}

Scope: contacts:write

Soft-deletes the contact. Data is retained before permanent deletion.

Cascading effects:

• Related conversations are soft-deleted
• Upcoming appointments are cancelled
• Running workflow automations for this contact are cancelled

6. Calendar & Booking API#

Data Model#

Appointment:

Endpoints#

List Calendars#

GET /api/v1/calendars

Scope: calendars:read

Returns all active calendars for the sub-account.

Response:

{
  "data": [
    {
      "id": "cal_abc123",
      "name": "Main Calendar",
      "type": "personal",
      "timezone": "America/New_York"
    }
  ]
}

List Appointment Types#

GET /api/v1/calendars/types

Scope: calendars:read

Query parameters:

• calendarId - Optionally filter by a specific calendar

Response:

{
  "data": [
    {
      "id": "apt_type_001",
      "calendarId": "cal_abc123",
      "name": "30-Minute Consultation",
      "duration": 30,
      "slug": "30-min-consultation"
    }
  ]
}

List Appointments#

GET /api/v1/calendars/appointments

Scope: calendars:read

Query parameters:

• calendarId - Filter by calendar
• startDate - Start of date range (Unix timestamp, milliseconds)
• endDate - End of date range (Unix timestamp, milliseconds)
• status - scheduled, confirmed, completed, cancelled, no_show
• limit - Max results (default 50, max 100)

Check Availability#

GET /api/v1/calendars/availability?appointmentTypeId={id}&date=2026-04-01

Scope: calendars:read

Query parameters:

• appointmentTypeId - Required
• date - Date in YYYY-MM-DD format

Response:

{
  "data": [
    { "start": "2026-04-01T09:00:00-04:00", "end": "2026-04-01T09:30:00-04:00" },
    {
      "start": "2026-04-01T09:30:00-04:00",
      "end": "2026-04-01T10:00:00-04:00",
      "seatsRemaining": 3
    }
  ]
}

Availability accounts for: day-of-week schedules, date overrides (blocked days), existing bookings, buffer times, minimum notice, maximum advance, and seat limits.

Book Appointment#

POST /api/v1/calendars/appointments

Scope: calendars:write

Request body:

{
  "appointmentTypeId": "...",
  "startTime": 1743508800000,
  "endTime": 1743510600000,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "+15551234567",
  "notes": "First consultation"
}

Behavior:

• Creates or finds a contact by email
• Validates slot availability and conflicts
• Assigns based on calendar type (personal, round-robin, collective, class)
• Fires appointment.booked webhook event
• Sends confirmation email if configured

Cancel Appointment#

DELETE /api/v1/calendars/appointments/{id}

Scope: calendars:write

Query parameters:

• reason - Optional cancellation reason (e.g., ?reason=Customer%20requested)

Response: 200 OK

{
  "data": {
    "id": "appt_abc123",
    "cancelled": true
  }
}

Public Booking (No Key Required)#

The same availability check and booking flow is also available without an API key via the public booking page widget.

7. Opportunities, Tasks & Pipelines API#

Opportunities and tasks are full read and write resources, not webhook events only. You can create, read, update, and delete them the same way you do contacts. Pipelines are read-only, and exist so you can resolve the pipelineId and stageId an opportunity needs.

Data Model#

Opportunity:

Task:

Two timestamp formats, split by purpose. Record timestamps (createdAt, updatedAt) are ISO 8601 everywhere in the API, these resources included. The scheduling fields on opportunities and tasks (dueDate, completedAt, expectedCloseDate, closedAt) are epoch milliseconds, and the dueBefore / dueAfter filters take epoch milliseconds to match. Read the field type rather than assuming one format.

Cancellation surfaces via task.updated, not a new event. PATCH /api/v1/tasks/{id} accepts status: "cancelled", and deleting a linked contact cancels the contact's open tasks (the older behavior of marking them completed changed with 5.7.0). Both paths fire a task.updated webhook with the cancelled status and changedFields: ["status"]; there is no dedicated task.cancelled event.

Opportunity Endpoints#

Stage moves and status changes have their own endpoints so that a pipeline move fires the correct automation.

They do not emit the same event, and it is worth knowing which is which before you build a listener:

• PUT .../stage emits opportunity.stage_changed, and only when the stage actually changes. Setting an opportunity to the stage it is already in emits nothing.
• PUT .../status emits opportunity.updated.
• opportunity.won and opportunity.lost are not emitted by this endpoint. They exist in the event catalog, but the REST status change routes won and lost into pipeline automation rather than the outbound webhook dispatcher. Listen for opportunity.updated and read the status field instead.

Move an Opportunity to a New Stage#

PUT /api/v1/opportunities/{id}/stage

Scope: opportunities:write

Request:

{ "stageId": "stg_abc123" }

Task Endpoints#

List filters: status, assignedTo, contactId, dealId, dueBefore, dueAfter. The two date filters take epoch milliseconds and match strictly before and strictly after.

Pipeline Endpoints#

Read pipelines first to get the pipelineId and stageId values you need when creating or moving an opportunity.

What Is Not Exposed Yet#

Invoices are not available as REST endpoints. You can subscribe to the invoice.paid webhook event to react to a payment, but there is no /api/v1/invoices resource to read or create invoices. If invoice endpoints matter to your integration, say so and it can be weighed for the roadmap. Because you own the source, you can also add them yourself. See Adding Your Own Endpoints below.

Adding Your Own Endpoints#

The API is not a closed surface. Every endpoint above is registered in one file, convex/http.ts, and uses the same small set of helpers from convex/apiHelpers.ts. Adding a public endpoint of your own follows the existing pattern:

1. Register the route. Add an http.route({ path, method, handler }) entry. Use pathPrefix when the route addresses a record by id or has a nested sub-resource.
2. Authenticate. Call the shared API key authenticator at the top of the handler. It resolves the key, the agency, and the sub-account, and it handles agency-scoped keys and the X-Sub-Account-Id header for you.
3. Check a scope. Require a scope before doing any work. You can reuse an existing scope or add your own to the valid scope list, after which it becomes selectable when creating a key.
4. Rate limit and log. The same helpers that bucket and log every built-in endpoint are available to yours, so your endpoint shows up in API usage reporting alongside the rest.
5. Return the standard envelope. Use the shared success and error helpers so your endpoint returns the same { data, meta } and { error } shapes documented above.

Your endpoints live alongside the built-in ones and survive updates as ordinary source changes. Keep them in their own file where practical, so a future update to http.ts is a clean merge.

8. Campaigns API#

Campaigns lets you push a finished HTML email into the CRM and send it (or schedule it) without opening the block-canvas builder. It is a write-only surface today — there is no GET /api/v1/campaigns endpoint and no campaigns:read scope. If you need to react when a campaign fires, subscribe to the campaign webhook events documented under Webhooks.

The flow is deliberately two steps: create first (safe to retry, mails no one), then send or schedule (a real fire, not safe to retry). An accidental duplicate POST /api/v1/campaigns costs you one extra draft; an accidental duplicate send would cost you a real inbox delivery.

Data Model#

Campaign (create request):

Campaign (response):

HTML-authored campaigns open in the CRM as read-only. A campaign created via the API renders as a preview in the app, not the drag-and-drop block canvas — the HTML is yours, and opening it in the block editor would rewrite it. Operators can still test-send, review recipients, and hit send from the UI.

The layout is resolved by name, not id. If two saved templates in the sub-account share a name, the most recently updated one wins. A layout with no {{content}} placeholder (or more than one) is rejected as layout_invalid at create time.

Email only. The send and schedule endpoints refuse anything other than an email campaign — SMS broadcasts require a role capability the API cannot evaluate, and creating an SMS campaign this way is not supported.

Endpoints#

Create a Draft Campaign#

POST /api/v1/campaigns

Scope: campaigns:write

Request:

{
  "name": "November newsletter",
  "subject": "What's new this month",
  "preheader": "Product updates, upcoming events, and a special offer inside.",
  "contentHtml": "<h1>Hi {{contact.firstName}}!</h1><p>Here's what shipped this month...</p>",
  "layout": "Default newsletter layout",
  "listId": "el_abc123"
}

Response:

{
  "data": {
    "id": "cmp_xyz789",
    "status": "draft"
  }
}

Errors specific to this endpoint:

• layout_not_found: no template named "..." — nothing in this sub-account's saved email templates matches the layout name.
• layout_invalid: template "..." has no bodyHtml — the layout row exists but has an empty body.
• layout_invalid: layout must contain exactly one {{content}} placeholder — the layout is missing the merge slot the API needs to inject contentHtml, or it has more than one.
• list_required: ... — no listId was provided AND the layout has no default list to fall back on.
• feature_unavailable: campaigns is not enabled on this plan — the sub-account's plan does not include the campaigns module.

Send a Draft Immediately#

POST /api/v1/campaigns/{id}/send

Scope: campaigns:write

Request: no body.

Response:

{
  "data": {
    "id": "cmp_xyz789",
    "status": "sending"
  }
}

The audience is resolved BEFORE the campaign flips to sending, so an empty list is surfaced right here as a 400 rather than moving the campaign to sending and reverting it moments later.

Errors specific to this endpoint:

• invalid_status: ... — the campaign is not in a status you can send from (already sending, already sent, cancelled, and so on).
• channel_unsupported: the API can only send email campaigns (this one is sms) — SMS broadcasts are gated by a role capability the API cannot check.
• list_required: ... — the campaign has no list attached, OR the list was archived / moved out of this sub-account after create.
• empty_audience: ... — the resolved audience is zero recipients (for example, every contact on the list is opted out or suppressed).

Schedule a Draft#

POST /api/v1/campaigns/{id}/schedule

Scope: campaigns:write

Request:

{ "scheduledAt": 1735689600000 }

scheduledAt is epoch milliseconds, not seconds. A 10-digit seconds value is rejected — otherwise it would parse as a date in 1970 and the campaign would be treated as overdue and sent immediately.

Response:

{
  "data": {
    "id": "cmp_xyz789",
    "status": "scheduled"
  }
}

The same invalid_status / channel_unsupported / list_required errors apply as with send.

What Is Not Exposed Yet#

There is no GET /api/v1/campaigns today, and campaigns:read is deliberately NOT a grantable scope — a scope that authorises nothing would be a promise the API cannot keep. When a read endpoint lands, campaigns:read will land in the same change. If reading a campaign back matters for your integration, subscribe to the campaign webhook events documented in the next section, or say so and it can be weighed for the roadmap.

9. Webhooks (Real-Time Events)#

Overview#

Seedly CRM pushes real-time event notifications to your server via HTTPS POST. Events are cryptographically signed, retried on failure, and logged for debugging.

Managing Subscriptions#

Webhook subscriptions can be managed via the REST API or the settings UI.

List Subscriptions#

GET /api/v1/webhooks

Scope: webhooks:manage

Create Subscription#

POST /api/v1/webhooks

Scope: webhooks:manage

Request body:

{
  "url": "https://your-server.com/webhooks/seedly",
  "events": [
    "contact.created",
    "message.received",
    "message.sent",
    "message.delivered",
    "message.failed",
    "appointment.booked"
  ],
  "description": "Chatbot integration"
}

Response: Returns the subscription with a signing secret. Store this securely - it is shown once.

Update Subscription#

PATCH /api/v1/webhooks/{id}

Scope: webhooks:manage

Delete Subscription#

DELETE /api/v1/webhooks/{id}

Scope: webhooks:manage

Regenerate Signing Secret#

POST /api/v1/webhooks/{id}/regenerate-secret

Scope: webhooks:manage

Regenerates the signing secret for a webhook subscription. The old secret is immediately invalidated.

Response:

{
  "data": {
    "secret": "whsec_new_plaintext_secret_here"
  }
}

Store the new secret securely - it is shown once. Update your webhook verification code with the new secret immediately.

Available Events#

Payload Format#

{
  "event": "contact.created",
  "timestamp": "2026-03-27T14:30:00.000Z",
  "data": {
    "subAccountId": "sa_001",
    "contactId": "abc123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "tags": ["website-lead"]
  }
}

Common fields in data:

• subAccountId - Always present. Identifies which sub-account the event belongs to.
• contactId - Present when the event is associated with a specific contact.
• tags - Present when the associated contact has tags.

See Webhook Payloads for complete payload examples for all 26 events.

Request Headers#

Verifying Signatures#

Always verify the X-Webhook-Signature header using timing-safe comparison.

Node.js example:

const crypto = require('crypto');
 
function verifySignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
 
  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

Retry Policy#

If your endpoint does not return a success response, the delivery is retried automatically several times with an increasing back-off between attempts. After the retries are exhausted, the delivery is marked as failed. Delivery logs are retained and can be reviewed in the dashboard.

Your server must respond with a 2xx status within a reasonable time window to be considered successful.

Security Notes#

• Webhook URLs pointing to private or reserved IP ranges are blocked (SSRF protection)
• Always verify signatures before processing events
• Use the X-Webhook-Delivery header for idempotency - your server may receive duplicate deliveries

10. Workflow Triggers#

Overview#

Workflows are automation sequences that execute when events occur. External systems can trigger workflows via HTTP and inject custom events into running executions.

Workflow triggers use the /webhooks/workflow/{slug} endpoint with optional HMAC signature, not API key authentication.

Trigger a Workflow#

Each workflow with an "Inbound Webhook" trigger type has a unique URL:

POST https://{YOUR_DEPLOYMENT_URL}/webhooks/workflow/{slug}

Request body:

{
  "contactId": "optional_contact_id",
  "email": "[email protected]",
  "customData": "any data your workflow needs"
}

Optional header: X-Webhook-Signature: sha256={hex} - HMAC-SHA256 of the body using the workflow's signing secret. If the workflow has a secret configured, the signature is required.

Response:

{ "ok": true, "triggered": 1 }

Inject Events into Running Workflows#

Running workflows can wait for custom events at "goal" nodes. Inject events with:

POST https://{YOUR_DEPLOYMENT_URL}/webhooks/event/{slug}

Request body:

{
  "eventType": "payment_completed",
  "contactId": "optional_contact_id",
  "data": { "amount": 99.99 }
}

Rate Limits#

Both workflow endpoints are rate-limited on a per-endpoint basis.

11. Pagination#

The API uses cursor-based pagination. Cursors are opaque strings - do not parse or construct them.

Walkthrough#

First request - no cursor:

GET /api/v1/contacts?limit=50
Authorization: Bearer sk_live_...

Response:

{
  "data": [
    /* first 50 contacts */
  ],
  "meta": {
    "total": 150,
    "hasMore": true,
    "cursor": "eyJpZCI6ImNvbnRhY3RfMDUwIn0"
  }
}

Read the cursor from meta.cursor and pass it in the next request:

GET /api/v1/contacts?limit=50&cursor=eyJpZCI6ImNvbnRhY3RfMDUwIn0
Authorization: Bearer sk_live_...

Response:

{
  "data": [
    /* next 50 contacts */
  ],
  "meta": {
    "total": 150,
    "hasMore": true,
    "cursor": "eyJpZCI6ImNvbnRhY3RfMTAwIn0"
  }
}

Continue until hasMore is false:

{
  "data": [
    /* final 50 contacts */
  ],
  "meta": {
    "total": 150,
    "hasMore": false,
    "cursor": null
  }
}

Tips#

• Cursors are stable even when data changes between requests (unlike offset-based pagination).
• Do not store cursors long-term - they may expire. Use them immediately for sequential page fetching.
• The total field reflects the total count at the time of the query and may change between pages.
• meta.total is the size of the whole result set, not the number of records in the page you are holding. Use meta.hasMore to decide whether to fetch again, and total to show a count or size a progress bar.

12. Error Examples#

401 Unauthorized - Missing or invalid API key#

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key. Provide a valid key in the Authorization header: Bearer sk_live_..."
  }
}

400 Validation Error - Invalid request body#

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "firstName and lastName are required"
  }
}

403 Forbidden - Missing required scope#

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing required scope: contacts:write. Update key permissions in Settings > Integrations > API Keys."
  }
}

429 Rate Limited - Too many requests#

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after the period indicated in the Retry-After header."
  }
}

Response headers:

Retry-After: 12
X-RateLimit-Limit: ...
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743091200

13. Rate Limits & Best Practices#

Rate Limits#

Rate limits are applied per API key. Read operations have higher limits than write operations. Rate limit headers are included in every response so your integration can monitor usage and avoid exceeding limits:

X-RateLimit-Limit: ...
X-RateLimit-Remaining: ...
X-RateLimit-Reset: ...

When a limit is exceeded, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.

Workflow trigger and event injection endpoints are rate-limited on a per-endpoint basis. Public endpoints such as live chat and form submissions are rate-limited by IP address.

For high-volume integrations requiring higher rate limits, contact the Seedly CRM team.

Server-side only: All API key endpoints are designed for server-to-server use. Do not call the REST API from client-side JavaScript - API keys would be exposed.

Best Practices#

1. Verify webhook signatures - Always use timing-safe comparison. Never skip verification in production.

2. Use idempotency keys - Use X-Webhook-Delivery to deduplicate webhook events. Track message IDs to prevent duplicate sends.

3. Handle retries gracefully - Respond to webhooks promptly. Return 200 even for events you don't process. Do heavy work asynchronously.

4. Use cursor-based pagination - Use cursor from the meta object, not offset-based page numbers. Cursors are stable when data changes between requests.

5. Respect DND - The system enforces Do-Not-Disturb server-side, but checking DND status before sending prevents silent failures.

6. Use merge fields - Use {{firstName}}, {{email}}, etc. in message bodies. The system resolves them at send time using current contact data.

7. Channel constraints:

   • SMS: Phone numbers must be E.164 format (+1XXXXXXXXXX). Messages over 160 characters are segmented.
   • Email: Provide both bodyText and bodyHtml for maximum compatibility.
   • Messenger/Instagram: Subject to Meta's 24-hour messaging window policy.

Error Codes#

14. Versioning & Stability#

Current Version#

All endpoints are served under /api/v1/. The X-API-Version: v1 header is included in every response.

Backwards Compatibility#

We will not make breaking changes to v1 without a deprecation period:

• Not breaking (may happen at any time): New fields in responses, new optional query parameters, new endpoints, new webhook events, new error codes
• Breaking (requires deprecation): Removing response fields, changing field types, removing endpoints, changing endpoint behavior, renaming fields

Deprecation Process#

1. A Deprecation: true response header is added to affected endpoints (minimum 90 days before removal)
2. A changelog entry is published in the API Changelog
3. When v2 is introduced, v1 will remain supported for at least 12 months

Recommendations#

• Parse responses tolerantly - ignore unknown fields
• Do not depend on field ordering in JSON responses
• Check the API Changelog periodically for updates

15. Future Roadmap#

Full Endpoint Reference#

REST API (Requires API Key)#

Public Endpoints (No Key Required)#

This document is intended for engineering teams building integrations with Seedly CRM. For questions, contact the Seedly CRM team.