BackCoachful

API Documentation

Integrate Coachful with your tools using our REST API. Powers the official Coachful apps on Zapier and OttoKit, and available for custom integrations.

Authentication

All API requests require an API key. Generate one from your coach dashboard under Automations → Connections.

Include your API key in the X-API-Key header:

curl -H "X-API-Key: cfk_your_api_key_here" \
  https://app.coachful.co/api/zapier/auth/test

Base URL: https://app.coachful.co
Rate Limits: 100 reads/min, 30 writes/min per API key

Test Authentication

GET
/api/zapier/auth/test

Verify your API key and get organization info

Returns:

{
  "organizationName": "My Coaching",
  "coachName": "Jane Smith",
  "organizationId": "..."
}

Triggers (Webhooks)

Subscribe to events via REST Hooks. When events occur in your organization, we POST the event data to your webhook URL.

POST
/api/zapier/hooks

Subscribe to an event. Body: { hookUrl, event }

DELETE
/api/zapier/hooks/:hookId

Unsubscribe from an event

Available Events

lead.capturedA new lead is captured
funnel.completedSomeone completes a funnel
intake.form.submittedA form or worksheet is submitted, with every answer and uploaded file
intake.call.bookedA discovery or intake call is booked
coaching.session.scheduledA 1:1 session is booked or confirmed
coaching.session.cancelledA session is cancelled
client.goal.achievedA client achieves a goal
payment.receivedA payment is received
payment.refundedA payment is refunded
email.unsubscribedA contact unsubscribes from your emails
coaching.note.createdA note is added through the API
automation.firedAn automation runs its Send webhook step

Example: intake.form.submitted

Every answer arrives in form order with its question id, question text, type, a readable value (choice labels, numbers, text) and plain text. Uploaded files include their public URL and file name, and are also listed together under files. Questions hidden by skip logic are left out. Text answers longer than 10,000 characters are shortened and marked truncated: true.

{
  "id": "evt_...",
  "event": "intake.form.submitted",
  "timestamp": "2026-02-24T10:15:00.000Z",
  "organizationId": "...",
  "data": {
    "responseId": "resp_abc123",
    "formId": "form_xyz789",
    "formName": "Discovery Call Intake",
    "formType": "form",
    "userId": "user_def456",
    "prospectName": "John Doe",
    "prospectEmail": "john@example.com",
    "prospectPhone": "+1234567890",
    "answers": [
      { "questionId": "q_goal", "question": "What is your main goal?",
        "type": "long_text", "value": "Lose 20 lbs before my wedding",
        "text": "Lose 20 lbs before my wedding" },
      { "questionId": "q_focus", "question": "Which areas do you want help with?",
        "type": "multi_choice", "value": ["Nutrition", "Sleep"], "text": "Nutrition, Sleep" },
      { "questionId": "q_ready", "question": "How ready are you to start?",
        "type": "scale", "value": 8, "text": "8", "min": 1, "max": 10 },
      { "questionId": "q_bloodwork", "question": "Upload your latest blood work",
        "type": "file_upload",
        "value": ["https://coachful.b-cdn.net/.../bloodwork.pdf"],
        "text": "https://coachful.b-cdn.net/.../bloodwork.pdf",
        "files": [{ "url": "https://coachful.b-cdn.net/.../bloodwork.pdf",
          "name": "bloodwork.pdf", "contentType": "application/pdf", "sizeBytes": 482113 }] }
    ],
    "answersByQuestionId": { "q_goal": "Lose 20 lbs before my wedding", "q_focus": "Nutrition, Sleep", ... },
    "files": [{ "questionId": "q_bloodwork", "question": "Upload your latest blood work",
      "url": "https://coachful.b-cdn.net/.../bloodwork.pdf", "name": "bloodwork.pdf",
      "contentType": "application/pdf", "sizeBytes": 482113 }],
    "totalScore": 12,
    "maxPossibleScore": 20,
    "submittedAt": "2026-02-24T10:15:00.000Z"
  }
}

Session events (intake.call.booked, coaching.session.scheduled, coaching.session.cancelled) send sessionId, title, startDateTime, endDateTime, timezone, status, eventType, meetingProvider, meetingUrl, clientId, clientName, clientEmail and the host; cancellations add cancelledAt, cancelledBy and cancellationReason.

Polling Fallback

GET
/api/zapier/triggers/:event

Poll for recent events (returns last 50)

GET
/api/zapier/triggers/:event/sample

Get sample data for an event

Actions

Perform actions in your Coachful organization. All actions require a POST request with a JSON body.

POST
/api/zapier/actions/create-task

Create a task for a client. Body: { clientEmail, title, date?, listType? }

POST
/api/zapier/actions/create-habit

Create a habit for a client. Body: { clientEmail, text, frequency? }

POST
/api/zapier/actions/send-message

Send a chat message. Body: { message, clientEmail?, channel?, programId?, cohortId? }

POST
/api/zapier/actions/create-post

Create a feed post. Body: { content }

POST
/api/zapier/actions/create-invoice

Create an invoice. Body: { clientEmail, amount, description, currency? }

POST
/api/zapier/actions/enroll-in-program

Enroll a client in a program. Body: { clientEmail, programId, cohortId?, startDate? }

POST
/api/zapier/actions/grant-resource

Grant resource access. Body: { clientEmail, resourceType, resourceId }

Searches

Look up data in your organization. Used for dynamic dropdowns in Zapier and for finding IDs.

GET
/api/zapier/searches/find-client?email=...

Find a client by email, or list all clients

GET
/api/zapier/searches/list-programs

List all programs in your organization

GET
/api/zapier/searches/list-cohorts?programId=...

List cohorts, optionally filtered by program

GET
/api/zapier/searches/list-resources?resourceType=...

List resources by type (course, article, download, video, link, questionnaire)

GET
/api/zapier/searches/list-channels

List org chat channels

GET
/api/zapier/searches/list-checkin-flows

List check-in flow templates

Send Message Targeting

The Send Message action supports multiple targeting modes. Provide exactly one:

  • clientEmail — Send a direct message to a client
  • channel — Post to an org channel (announcements, social, wins, or custom name)
  • programId — Post to a program's community channel
  • programId + cohortId — Post to a cohort's squad channel

Error Handling

All errors return a JSON object with an error field.

400Bad Request — Missing or invalid parameters
401Unauthorized — Invalid or missing API key
403Forbidden — Resource not in your organization
404Not Found — Resource does not exist
429Rate Limited — Too many requests
500Server Error — Something went wrong

Support

Questions about the API? Contact us at hello@coachful.co