Seedly CRM

https://seedlycrm.com/docs
Admin
Seedly CRM is a complete client management platform built for agencies that consolidates...
Tokens:48,764
Snippets:785
Trust Score:5.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Agency Integration Flow Example

Source: https://seedlycrm.com/docs/help/api

Example sequence for discovering sub-accounts and performing a request for a specific sub-account.

```http
# 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
```

--------------------------------

### List Messages Response

Source: https://seedlycrm.com/docs/help/api

Example JSON response structure for listing messages.

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

--------------------------------

### Custom Field Definitions Response

Source: https://seedlycrm.com/docs/help/api

Example response showing the structure of custom field definitions.

```json
{
  "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
    }
  ]
}
```

--------------------------------

### GET /api/v1/contacts (Pagination)

Source: https://seedlycrm.com/docs/help/api

Demonstrates cursor-based pagination for retrieving contact lists.

```APIDOC
## GET /api/v1/contacts

### Description
Retrieves a paginated list of contacts using cursor-based pagination to ensure stability.

### Method
GET

### Endpoint
/api/v1/contacts

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of records to return per page.
- **cursor** (string) - Optional - The opaque cursor string returned from the previous request.

### Response
#### Success Response (200)
- **data** (array) - The list of contacts.
- **meta** (object) - Contains pagination metadata including 'total', 'hasMore', and 'cursor'.
```

--------------------------------

### Run the Update Helper

Source: https://seedlycrm.com/docs/help/updating

Execute the guided update script from the project root directory. Ensure the 'run' keyword is included to avoid triggering standard dependency updates.

```bash
npx pnpm run update
```

--------------------------------

### Create Conversation Response

Source: https://seedlycrm.com/docs/help/api

Example JSON response indicating a successful conversation creation.

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

--------------------------------

### Create Conversation Request Body

Source: https://seedlycrm.com/docs/help/api

Example JSON payload for creating a conversation.

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

--------------------------------

### GET /api/v1/webhooks

Source: https://seedlycrm.com/docs/help/api

Retrieves a list of all webhook subscriptions.

```APIDOC
## GET /api/v1/webhooks

### Description
Retrieves a list of all webhook subscriptions.

### Method
GET

### Endpoint
/api/v1/webhooks

### Parameters
- **Scope** - webhooks:manage
```

--------------------------------

### Create Contact Request Body

Source: https://seedlycrm.com/docs/help/api

Example JSON payload for creating a new contact.

```json
{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "company": "Acme Corp",
  "lifecycleStage": "lead",
  "tags": ["website-lead"],
  "source": "api"
}
```

--------------------------------

### Webhook Event Payload Format

Source: https://seedlycrm.com/docs/help/api

Example structure of the JSON payload sent to your webhook endpoint.

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

--------------------------------

### Send Message Request Body

Source: https://seedlycrm.com/docs/help/api

Example JSON payload for sending a message, supporting merge fields.

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

--------------------------------

### API Error Response Examples

Source: https://seedlycrm.com/docs/help/api

Standard JSON error structures returned by the API for various failure scenarios.

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

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

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

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

--------------------------------

### Get Custom Field Definitions Endpoint

Source: https://seedlycrm.com/docs/help/api

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

```http
GET /api/v1/contacts/fields
```

--------------------------------

### GET /api/v1/calendars

Source: https://seedlycrm.com/docs/help/api

Returns all active calendars for the sub-account.

```APIDOC
## GET /api/v1/calendars

### Description
Returns all active calendars for the sub-account.

### Method
GET

### Endpoint
/api/v1/calendars

### Response
#### Success Response (200)
- **data** (array) - List of calendar objects

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

--------------------------------

### Preview and Apply SeedlyCRM Updates

Source: https://seedlycrm.com/docs/help/updating

Commands to preview update changes using a dry run and to apply the update to the project.

```bash
npx pnpm run update -- --dry-run --from path/to/new-version
```

```bash
npx pnpm run update -- --from path/to/new-version
```

--------------------------------

### GET /api/v1/calendars/appointments

Source: https://seedlycrm.com/docs/help/api

Lists appointments based on provided filters.

```APIDOC
## GET /api/v1/calendars/appointments

### Description
Lists appointments based on provided filters.

### Method
GET

### Endpoint
/api/v1/calendars/appointments

### Parameters
#### Query Parameters
- **calendarId** (string) - Optional - Filter by calendar
- **startDate** (integer) - Optional - Start of date range (Unix timestamp, milliseconds)
- **endDate** (integer) - Optional - End of date range (Unix timestamp, milliseconds)
- **status** (string) - Optional - Filter by status (scheduled, confirmed, completed, cancelled, no_show)
- **limit** (integer) - Optional - Max results (default 50, max 200)
```

--------------------------------

### Exporting Convex data via CLI

Source: https://seedlycrm.com/docs/help/backups

Use this command to create a portable snapshot of your data and file storage for off-platform backup.

```bash
npx convex export --path seedly-backup.zip --include-file-storage
```

--------------------------------

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

Source: https://seedlycrm.com/docs/help/api

Retrieves details for a specific conversation.

```APIDOC
## GET /api/v1/conversations/{id}

### Description
Fetch details for a specific conversation by its ID.

### Method
GET

### Endpoint
/api/v1/conversations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The conversation ID
```

--------------------------------

### Get Contact Endpoint

Source: https://seedlycrm.com/docs/help/api

Retrieves a single contact by its unique identifier.

```http
GET /api/v1/contacts/{id}
```

--------------------------------

### Restore backup using Convex CLI

Source: https://seedlycrm.com/docs/help/backups

Use this command to import a backup zip file into a deployment. Ensure this is performed in a non-production environment for testing purposes.

```bash
npx convex import --path seedly-backup.zip
```

--------------------------------

### task.created

Source: https://seedlycrm.com/docs/help/webhooks

Fires when a new task is created.

```APIDOC
## task.created

### Description
Fires when a new task is created.

### Payload Example
{
  "event": "task.created",
  "timestamp": "2026-03-27T14:52:00.000Z",
  "data": {
    "subAccountId": "sa_001",
    "contactId": "abc123",
    "taskId": "task001",
    "title": "Follow up with Jane",
    "status": "todo",
    "priority": "high",
    "dueDate": 1743595200000,
    "assignedTo": "user001"
  }
}
```

--------------------------------

### GET /api/v1/conversations

Source: https://seedlycrm.com/docs/help/api

Retrieves a list of conversations based on optional filters.

```APIDOC
## GET /api/v1/conversations

### Description
List conversations with optional filtering by status, channel, contact, or assignee.

### Method
GET

### Endpoint
/api/v1/conversations

### Parameters
#### Query Parameters
- **status** (string) - Optional - open, closed, snoozed
- **channel** (string) - Optional - Filter by channel type
- **contactId** (string) - Optional - Filter by contact ID
- **assignedTo** (string) - Optional - Filter by team member ID
- **limit** (number) - Optional - Max results (default 50, max 200)
```

--------------------------------

### Implement Cursor-Based Pagination

Source: https://seedlycrm.com/docs/help/api

Fetch paginated results by passing the cursor from the previous response's meta object. Continue requests until hasMore is false.

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

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

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

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

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

--------------------------------

### GET /api/v1/contacts/{id}

Source: https://seedlycrm.com/docs/help/api

Retrieve details for a specific contact by their unique identifier.

```APIDOC
## GET /api/v1/contacts/{id}

### Description
Retrieve details for a specific contact by their unique identifier.

### Method
GET

### Endpoint
/api/v1/contacts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the contact
```

--------------------------------

### POST /api/v1/webhooks

Source: https://seedlycrm.com/docs/help/api

Creates a new webhook subscription.

```APIDOC
## POST /api/v1/webhooks

### Description
Creates a new webhook subscription. Returns the subscription details including a signing secret.

### Method
POST

### Endpoint
/api/v1/webhooks

### Request Body
- **url** (string) - Required - The URL to receive webhook events
- **events** (array) - Required - List of event names to subscribe to
- **description** (string) - Optional - Description of the integration
```

--------------------------------

### appointment.booked

Source: https://seedlycrm.com/docs/help/webhooks

Fires when a new appointment is booked.

```APIDOC
## appointment.booked

### Description
Fires when a new appointment is booked.

### Payload
- **event** (string) - The event name: "appointment.booked"
- **timestamp** (string) - ISO 8601 timestamp of the event
- **data** (object) - Event details
  - **subAccountId** (string) - ID of the sub-account
  - **contactId** (string) - Unique ID of the contact
  - **appointmentId** (string) - Unique ID of the appointment
  - **calendarId** (string) - Unique ID of the calendar
  - **appointmentTypeId** (string) - Unique ID of the appointment type
  - **appointmentTitle** (string) - Title of the appointment
  - **startTime** (number) - Start time in milliseconds
  - **endTime** (number) - End time in milliseconds
  - **status** (string) - Status of the appointment

### Example
{
  "event": "appointment.booked",
  "timestamp": "2026-03-27T14:38:00.000Z",
  "data": {
    "subAccountId": "sa_001",
    "contactId": "abc123",
    "appointmentId": "appt001",
    "calendarId": "cal001",
    "appointmentTypeId": "type001",
    "appointmentTitle": "30-Min Consultation",
    "startTime": 1743508800000,
    "endTime": 1743510600000,
    "status": "scheduled"
  }
}
```

--------------------------------

### Create Contact Endpoint

Source: https://seedlycrm.com/docs/help/api

Creates a new contact record.

```http
POST /api/v1/contacts
```

--------------------------------

### GET /api/v1/calendars/availability

Source: https://seedlycrm.com/docs/help/api

Checks availability for a specific appointment type on a given date.

```APIDOC
## GET /api/v1/calendars/availability

### Description
Checks availability for a specific appointment type on a given date.

### Method
GET

### Endpoint
/api/v1/calendars/availability

### Parameters
#### Query Parameters
- **appointmentTypeId** (string) - Required - The ID of the appointment type
- **date** (string) - Required - Date in YYYY-MM-DD format

### Response
#### Success Response (200)
- **data** (array) - List of available time slots

#### Response Example
{
  "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
    }
  ]
}
```

--------------------------------

### opportunity.created

Source: https://seedlycrm.com/docs/help/webhooks

Fires when a new opportunity is created in a pipeline.

```APIDOC
## opportunity.created

### Description
Fires when a new opportunity is created in a pipeline.

### Response Example
{
  "event": "opportunity.created",
  "timestamp": "2026-03-27T14:39:00.000Z",
  "data": {
    "subAccountId": "sa_001",
    "contactId": "abc123",
    "opportunityId": "opp001",
    "pipelineId": "pipe001",
    "stageId": "stage001",
    "title": "Website Redesign",
    "value": 5000
  }
}
```

--------------------------------

### GET /api/v1/contacts/fields

Source: https://seedlycrm.com/docs/help/api

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

```APIDOC
## GET /api/v1/contacts/fields

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

### Method
GET

### Endpoint
/api/v1/contacts/fields

### Response
#### Success Response (200)
- **data** (array) - List of custom field definitions
```

--------------------------------

### GET /api/v1/contacts/{id}

Source: https://seedlycrm.com/docs/help/api

Retrieves a single contact record by its unique identifier.

```APIDOC
## GET /api/v1/contacts/{id}

### Description
Retrieves the full details of a specific contact.

### Method
GET

### Endpoint
/api/v1/contacts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique identifier of the contact
```

--------------------------------

### List Webhook Subscriptions

Source: https://seedlycrm.com/docs/help/api

Retrieve all configured webhook subscriptions.

```http
GET /api/v1/webhooks
```

--------------------------------

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

Source: https://seedlycrm.com/docs/help/api

Lists messages within a specific conversation.

```APIDOC
## GET /api/v1/conversations/{id}/messages

### Description
Fetch a list of messages for a given conversation.

### Method
GET

### Endpoint
/api/v1/conversations/{id}/messages

### Parameters
#### Path Parameters
- **id** (string) - Required - The conversation ID
#### Query Parameters
- **limit** (number) - Optional - Max results (default 50, max 100)
- **cursor** (string) - Optional - Pagination cursor
```

--------------------------------

### Get Conversation Endpoint

Source: https://seedlycrm.com/docs/help/api

Endpoint for retrieving details of a specific conversation by ID.

```http
GET /api/v1/conversations/{id}
```

--------------------------------

### contact.created

Source: https://seedlycrm.com/docs/help/webhooks

Fires when a new contact is created.

```APIDOC
## contact.created

### Description
Fires when a new contact is created.

### Payload Example
{
  "event": "contact.created",
  "timestamp": "2026-03-27T14:30:00.000Z",
  "data": {
    "subAccountId": "sa_001",
    "contactId": "abc123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "company": "Acme Corp",
    "source": "api",
    "tags": ["website-lead"],
    "lifecycleStage": "lead"
  }
}
```

--------------------------------

### Update Conversation Request Body

Source: https://seedlycrm.com/docs/help/api

Example JSON payload for updating conversation fields.

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

--------------------------------

### POST /api/v1/calendars/appointments

Source: https://seedlycrm.com/docs/help/api

Books a new appointment.

```APIDOC
## POST /api/v1/calendars/appointments

### Description
Books a new appointment.

### Method
POST

### Endpoint
/api/v1/calendars/appointments

### Parameters
#### Request Body
- **appointmentTypeId** (string) - Required - Type of appointment to book
- **startTime** (integer) - Required - Start time (Unix timestamp, milliseconds)
- **endTime** (integer) - Required - End time (Unix timestamp, milliseconds)
- **firstName** (string) - Required - Booker's first name
- **lastName** (string) - Required - Booker's last name
- **email** (string) - Required - Booker's email
- **phone** (string) - Optional - Booker's phone
- **notes** (string) - Optional - Additional notes

### Request Example
{
  "appointmentTypeId": "...",
  "startTime": 1743508800000,
  "endTime": 1743510600000,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "notes": "First consultation"
}
```

--------------------------------

### task.completed

Source: https://seedlycrm.com/docs/help/webhooks

Fires when a task is marked completed.

```APIDOC
## task.completed

### Description
Fires when a task is marked completed.

### Payload Example
{
  "event": "task.completed",
  "timestamp": "2026-03-27T14:54:00.000Z",
  "data": {
    "subAccountId": "sa_001",
    "contactId": "abc123",
    "taskId": "task001",
    "title": "Follow up with Jane",
    "status": "completed",
    "priority": "high",
    "completedAt": 1743596400000
  }
}
```

--------------------------------

### GET /api/v1/conversations

Source: https://seedlycrm.com/docs/help/api

List conversations. Supports an optional contactId query parameter for filtering.

```APIDOC
## GET /api/v1/conversations

### Description
List conversations. Supports an optional contactId query parameter for filtering.

### Method
GET

### Endpoint
/api/v1/conversations

### Parameters
#### Query Parameters
- **contactId** (string) - Optional - Filter conversations by contact ID
```

--------------------------------

### GET /api/v1/calendars/types

Source: https://seedlycrm.com/docs/help/api

Lists all available appointment types, with an optional filter by calendar ID.

```APIDOC
## GET /api/v1/calendars/types

### Description
Lists all available appointment types.

### Method
GET

### Endpoint
/api/v1/calendars/types

### Parameters
#### Query Parameters
- **calendarId** (string) - Optional - Filter by a specific calendar

### Response
#### Success Response (200)
- **data** (array) - List of appointment types

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

--------------------------------

### Create Webhook Subscription

Source: https://seedlycrm.com/docs/help/api

Register a new webhook endpoint to receive specific events.

```http
POST /api/v1/webhooks
```

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

--------------------------------

### Book Appointment

Source: https://seedlycrm.com/docs/help/api

Creates a new appointment. Requires the calendars:write scope.

```http
POST /api/v1/calendars/appointments
```

```json
{
  "appointmentTypeId": "...",
  "startTime": 1743508800000,
  "endTime": 1743510600000,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "notes": "First consultation"
}
```

--------------------------------

### GET /api/v1/contacts

Source: https://seedlycrm.com/docs/help/api

Retrieves a list of contacts based on optional filters and pagination parameters.

```APIDOC
## GET /api/v1/contacts

### Description
Retrieves a list of contacts. Supports filtering by search terms, email, lifecycle stage, source, tags, assigned team member, and phone presence.

### Method
GET

### Endpoint
/api/v1/contacts

### Parameters
#### Query Parameters
- **search** (string) - Optional - Full-text search (name, email, company)
- **email** (string) - Optional - Exact email match
- **limit** (number) - Optional - Max results (default 50, max 100)
- **cursor** (string) - Optional - Pagination cursor
- **lifecycleStage** (string) - Optional - Filter by stage
- **source** (string) - Optional - Filter by lead source
- **tags** (string) - Optional - Comma-separated tag filter
- **assignedTo** (string) - Optional - Filter by team member ID
- **hasPhone** (boolean) - Optional - true to only return contacts with phone numbers

### Response
#### Success Response (200)
- **data** (array) - List of contact objects
- **meta** (object) - Pagination metadata
```

--------------------------------

### POST /webhooks/event/{slug}

Source: https://seedlycrm.com/docs/help/api

Injects custom events into running workflows that are waiting at 'goal' nodes.

```APIDOC
## POST /webhooks/event/{slug}

### Description
Injects a custom event into a running workflow that is currently waiting at a 'goal' node.

### Method
POST

### Endpoint
https://{YOUR_DEPLOYMENT_URL}/webhooks/event/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier for the workflow.

#### Request Body
- **eventType** (string) - Required - The type of event being injected.
- **contactId** (string) - Optional - The contact ID associated with the event.
- **data** (object) - Optional - Data payload for the event.
```

--------------------------------

### Update Contact Request Body

Source: https://seedlycrm.com/docs/help/api

Example JSON payload for updating specific fields of a contact.

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

--------------------------------

### appointment.confirmed

Source: https://seedlycrm.com/docs/help/webhooks

Fires when an appointment is confirmed.

```APIDOC
## appointment.confirmed

### Description
Fires when an appointment is confirmed.

### Payload
- **event** (string) - The event name: appointment.confirmed
- **timestamp** (string) - ISO 8601 timestamp of the event
- **data** (object) - Contains subAccountId, contactId, appointmentId, and status
```

--------------------------------

### appointment.completed

Source: https://seedlycrm.com/docs/help/webhooks

Fires when an appointment is marked completed.

```APIDOC
## appointment.completed

### Description
Fires when an appointment is marked completed.

### Payload
- **event** (string) - The event name: appointment.completed
- **timestamp** (string) - ISO 8601 timestamp of the event
- **data** (object) - Contains subAccountId, contactId, appointmentId, and status
```
Tokens:
Raw