LinkyCal API Documentation

<!-- Booking Widget -->
<script src="https://cdn.linkycal.com/widgets/booking.js"></script>
<script>
  LinkyCal.booking({
    projectSlug: "your-project",
    container: "#booking-widget"
  });
</script>

<!-- Form Widget -->
<script src="https://cdn.linkycal.com/widgets/form.js"></script>
<script>
  LinkyCal.form({
    projectSlug: "your-project",
    formSlug: "contact",
    container: "#form-widget"
  });
</script>

# Check available slots
curl "https://linkycal.com/api/v1/availability/your-project?date=2026-08-12&timezone=UTC&eventTypeSlug=consultation"

Visitor API · /api/v1/*

Canonical anonymous endpoints for availability, bookings, and page form submissions. These routes are safe for visitor-side code and are rate limited by IP.

Share-link API · /api/public/*

Public link resolution and form configuration used by LinkyCal share pages. The response-creation and step-submission variants are retained for compatibility; new direct integrations should prefer /api/v1/*.

Management API · /api/projects/:projectId/*

Server-side project administration with a project-scoped API key. Never expose this credential in a browser, widget, or public form.

curl -X POST "https://linkycal.com/api/v1/forms/acme/contact/responses" \
  -H "Content-Type: application/json"

{
  "response": {
    "id": "resp_a1b2c3d4",
    "formId": "form_x1y2z3",
    "currentStepIndex": 0,
    "status": "in_progress"
  },
  "form": {
    "id": "form_x1y2z3",
    "name": "Contact Form",
    "steps": [
      {
        "id": "step_1",
        "title": "Your Details",
        "fields": [
          { "id": "fld_1", "type": "text", "label": "Full Name", "required": true },
          { "id": "fld_2", "type": "email", "label": "Email", "required": true }
        ]
      }
    ]
  }
}

curl -X PATCH "https://linkycal.com/api/v1/forms/acme/contact/responses/resp_a1b2c3d4/steps/0" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      { "fieldId": "fld_1", "value": "Jane Smith" },
      { "fieldId": "fld_2", "value": "jane@example.com" }
    ]
  }'

{
  "response": {
    "id": "resp_a1b2c3d4",
    "status": "in_progress",
    "currentStepIndex": 1,
    "completedAt": null
  }
}

curl -X POST "https://linkycal.com/api/v1/forms/acme/contact/responses/resp_a1b2c3d4/uploads" \
  -F "fieldId=resume" \
  -F "file=@./resume.pdf"

curl -X PATCH "https://linkycal.com/api/v1/forms/acme/contact/responses/resp_a1b2c3d4/steps/0" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "fieldId": "resume",
        "value": "resume.pdf",
        "fileUrl": "form-responses/project/form/response/resume/upload-id.pdf"
      }
    ]
  }'

<form action="https://linkycal.com/api/public/forms/acme/contact/submit" method="post" enctype="multipart/form-data">
  <input type="text" name="full_name" required />
  <input type="email" name="email" required />
  <input type="file" name="resume" />
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>

curl "https://linkycal.com/api/widget/form/acme/contact/config"

{
  "form": {
    "id": "form_x1y2z3",
    "name": "Contact Form",
    "slug": "contact",
    "steps": [
      {
        "id": "step_1",
        "title": "Your Details",
        "fields": [
          { "id": "fld_1", "type": "text", "label": "Full Name", "required": true },
          { "id": "fld_2", "type": "email", "label": "Email", "required": true },
          { "id": "fld_3", "type": "phone", "label": "Phone", "required": false }
        ]
      }
    ]
  }
}

curl "https://linkycal.com/api/v1/availability/acme?date=2026-08-12&timezone=UTC&eventTypeSlug=consultation"

{
  "slots": [
    { "start": "2026-03-24T09:00:00Z", "end": "2026-03-24T09:30:00Z" },
    { "start": "2026-03-24T10:00:00Z", "end": "2026-03-24T10:30:00Z" }
  ],
  "date": "2026-03-24",
  "timezone": "UTC"
}

curl -X POST "https://linkycal.com/api/v1/bookings" \
  -H "Content-Type: application/json" \
  -d '{
    "projectSlug": "acme",
    "eventTypeSlug": "consultation",
    "startTime": "2026-03-24T09:00:00Z",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "notes": "Looking forward to our meeting",
    "timezone": "America/New_York"
  }'

{
  "booking": {
    "id": "bk_abc123",
    "eventTypeId": "et_xyz789",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "startTime": "2026-03-24T09:00:00Z",
    "endTime": "2026-03-24T09:30:00Z",
    "timezone": "America/New_York",
    "status": "confirmed",
    "notes": "Looking forward to our meeting",
    "createdAt": "2026-03-23T20:00:00Z"
  }
}

curl -X PATCH "https://linkycal.com/api/projects/proj_123/bookings/bk_abc123/cancel" \
  -H "Authorization: Bearer lc_live_your_api_key"

{
  "booking": {
    "id": "bk_abc123",
    "status": "cancelled",
    "cancelledAt": "2026-03-24T08:00:00Z"
  }
}

{
  "contacts": [
    {
      "id": "ct_m1n2o3",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+1-555-0123",
      "tags": [
        { "id": "tag_lead", "name": "Lead", "color": "#1B4332" }
      ],
      "lastActivityAt": "2026-07-22T08:30:00.000Z",
      "createdAt": "2026-03-20T10:00:00.000Z"
    }
  ],
  "total": 1
}

curl -X POST "https://linkycal.com/api/projects/proj_123/contacts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lc_live_your_api_key" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1-555-0123",
    "notes": "Met at conference"
  }'

{
  "contact": {
    "id": "ct_p4q5r6",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1-555-0123",
    "notes": "Met at conference",
    "createdAt": "2026-03-24T14:00:00Z"
  }
}

curl -X PUT "https://linkycal.com/api/projects/proj_123/contacts/ct_p4q5r6" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lc_live_your_api_key" \
  -d '{
    "name": "Jane Smith-Doe",
    "notes": "Updated: now a paying customer"
  }'

{
  "contact": {
    "id": "ct_p4q5r6",
    "name": "Jane Smith-Doe",
    "email": "jane@example.com",
    "phone": "+1-555-0123",
    "notes": "Updated: now a paying customer",
    "updatedAt": "2026-03-24T15:00:00Z"
  }
}

<div id="booking-widget"></div>
<script src="https://cdn.linkycal.com/widgets/booking.js"></script>
<script>
  LinkyCal.booking({
    projectSlug: "acme",
    container: "#booking-widget",
    eventTypeSlug: "consultation",
    theme: {
      primaryColor: "#1B4332"
    }
  });
</script>

<div id="form-widget"></div>
<script src="https://cdn.linkycal.com/widgets/form.js"></script>
<script>
  LinkyCal.form({
    projectSlug: "acme",
    formSlug: "contact",
    container: "#form-widget",
    theme: {
      primaryColor: "#1B4332"
    }
  });
</script>

https://linkycal.com/acme/contact?utm_source=newsletter&plan=pro

<div id="form-widget"></div>
<script src="https://cdn.linkycal.com/widgets/form.js"></script>
<script>
  LinkyCal.form({
    projectSlug: "acme",
    formSlug: "contact",
    container: "#form-widget",
    hidden: {
      user_id: "usr_123",
      plan: "pro"
    }
  });
</script>

https://linkycal.com/acme/contact?hide_banner=1&hide_title=1

LinkyCal.form({
  projectSlug: "acme",
  formSlug: "contact",
  container: "#form-widget",
  ui: { hideBanner: true, hideTitle: true }
});

LinkyCal.booking({
  projectSlug: "acme",
  container: "#booking-widget",
  theme: {
    primaryColor: "#1B4332",
    borderRadius: "12px",
    fontFamily: "Inter, sans-serif"
  }
});

{
  "projectId": "proj_123",
  "contactId": "ct_m1n2o3",
  "contactEmail": "jane@example.com",
  "formResponseId": "resp_a1b2c3d4",
  "metadata": {}
}

https://linkycal.com/api/mcp

{
  "mcpServers": {
    "linkycal": {
      "type": "http",
      "url": "https://linkycal.com/api/mcp"
    }
  }
}

curl -H "Authorization: Bearer lc_live_a1b2c3d4e5f6..." \
  "https://linkycal.com/api/projects/proj_123/contacts"

{
  "error": "Descriptive error message"
}

Contacts

Offset pagination with limit and offset. The default limit is 50, the maximum is 100, and the response includes the full filtered total.

Contact activity

Cursor pagination with a default limit of 20 and maximum of 100. Pass the returned opaque nextCursor unchanged.

Tags

Optional cursor pagination from 1 to 100 items. When using cursor, repeat the same limit on the next request.

Other lists

Other list operations currently return their complete result unless their section or OpenAPI operation declares a limit.

{
  "trigger": "booking_created",
  "actions": [
    {
      "type": "webhook",
      "config": {
        "url": "https://your-app.com/webhooks/linkycal",
        "method": "POST",
        "headers": {
          "X-Webhook-Secret": "your_secret"
        }
      }
    }
  ]
}