> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorbitcrm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Programmatically interact with OrbitForms to manage forms, submissions, scheduling, meetings, and more.

## Authentication

Include your API key in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

> [!WARNING]
>
> Keep your API key secret. Do not expose it in client-side code or public repositories.

## Base URL

```
https://app.useorbitcrm.ai/api/v1
```

## Endpoints

### Forms

**List all forms**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/forms" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Get form submissions**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/forms/:formId/submissions" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Create form** (`title` is required)

```bash theme={null}
curl -X POST "https://app.useorbitcrm.ai/api/v1/forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Form", "fields": [...]}'
```

### Contacts

**List contacts** (with optional filters: `page`, `per_page`, `status`, `search`, `email`, `tag`, `external_id` + `external_source`, `sort` / `order` ([sorting](https://docs.useorbitcrm.ai/developers/api/crm.md#sorting)); `updated_since` / `cursor` read the [changes feed](https://docs.useorbitcrm.ai/developers/api/crm.md#changes-feed))

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/contacts?status=active&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Get contact**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/contacts/:contactId" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Update contact**

```bash theme={null}
curl -X PATCH "https://app.useorbitcrm.ai/api/v1/contacts/:contactId" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"custom_fields": {"company": "Acme Inc"}}'
```

**Delete contact** (needs the `contacts:delete` scope, and the key's owner must be an admin or the owner of the workspace; the contact's call recordings and transcripts are deleted with it, best effort: see [Deleting recordings](https://docs.useorbitcrm.ai/developers/api/dialer.md#deleting-recordings) for what happens when a provider fails)

```bash theme={null}
curl -X DELETE "https://app.useorbitcrm.ai/api/v1/contacts/:contactId" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

> [!NOTE]
>
> Every contact endpoint checks that the key's owner is still a member of the workspace. Viewers' keys can only read; writes need an editor, admin or owner.

**Add tag to contact**

```bash theme={null}
curl -X POST "https://app.useorbitcrm.ai/api/v1/contacts/:contactId/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_id": "tag_xyz"}'
```

**Remove tag from contact**

```bash theme={null}
curl -X DELETE "https://app.useorbitcrm.ai/api/v1/contacts/:contactId/tags?tag_id=tag_xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Contact Tags

**List contact tags**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/contact-tags" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Create contact tag**

```bash theme={null}
curl -X POST "https://app.useorbitcrm.ai/api/v1/contact-tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "High Intent"}'
```

**Delete contact tag**

```bash theme={null}
curl -X DELETE "https://app.useorbitcrm.ai/api/v1/contact-tags/:tagId" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Scheduling Pages

**List scheduling pages**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/scheduling-pages" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Get scheduling page**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/scheduling-pages/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Create scheduling page** (`title` is required)

```bash theme={null}
curl -X POST "https://app.useorbitcrm.ai/api/v1/scheduling-pages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "30-min Call", "page_type": "one_on_one"}'
```

**Delete scheduling page**

```bash theme={null}
curl -X DELETE "https://app.useorbitcrm.ai/api/v1/scheduling-pages/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Meetings

**List meetings** (optional filters: `status`, `since`, `until`, `scheduling_page_id`, `page`, `per_page`)

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/meetings?status=completed&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Get meeting**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/meetings/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example response:

```json theme={null}
{
  "data": {
    "id": "meeting_abc123",
    "status": "completed",
    "attendee_name": "Jane Doe",
    "attendee_email": "client@example.com",
    "start_time": "2026-03-07T14:00:00Z",
    "end_time": "2026-03-07T14:30:00Z",
    "timezone": "America/New_York",
    "meeting_link": "https://...",
    "notes": "Discussed pricing and implementation timeline",
    "scheduling_page_id": "page_xyz",
    "created_at": "2026-03-01T09:00:00Z"
  }
}
```

**Update meeting** (allowed fields: `status`, `notes`, `cancellation_reason`)

```bash theme={null}
curl -X PATCH "https://app.useorbitcrm.ai/api/v1/meetings/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled", "cancellation_reason": "Requested by attendee"}'
```

**Delete meeting**

```bash theme={null}
curl -X DELETE "https://app.useorbitcrm.ai/api/v1/meetings/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Availability Schedules

**List availability schedules**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/availability-schedules" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Get availability schedule**

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/availability-schedules/:id" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Sequences

Sequences have a separate API reference. See [Sequences API](https://docs.useorbitcrm.ai/developers/api/sequences.md) for full documentation.

## Rate Limits

API requests are rate limited per API key. Read endpoints allow **1,000 requests per minute**; creation endpoints have their own hourly caps (for example, 100 form creations per hour). OAuth apps receive tiered limits based on their verification status.

Exceeding a limit returns `429 Too Many Requests` with a `Retry-After` header telling you when to try again.

## Iframe Tracking Integration

Send tracking parameters from your page into OrbitForms forms for attribution and analytics.

### How It Works

1. **Pass tracking fields to the form** — Add `comet_token` as a query param on the form's URL, or send any of the supported fields from your page into the embedded form via `postMessage`
2. **Orbit captures them** — When a user submits, these values are stored with the submission
3. **Use in workflows** — Reference them in workflows, webhooks, or exports for attribution reporting

> [!NOTE]
>
> Arbitrary URL parameters can also be captured with [Hidden fields](https://docs.useorbitcrm.ai/guides/form-fields.md) — set a hidden field's value source to "URL parameter" and it will store that query param with every submission.

### Supported Tracking Fields

| Field | Description |
| - | - |
| `comet_token` | Cometly attribution token |
| `attribution_id` | Generic attribution ID |
| `tracking_id` | Campaign or source tracking |
| `visitor_id` | Visitor identifier |
| `session_id` | Session identifier |

Example (JavaScript, parent page of an iframe embed):

```javascript theme={null}
// Send tracking fields into the embedded form
const iframe = document.querySelector('iframe');
iframe.contentWindow.postMessage({
  comet_token: 'abc123',
  attribution_id: 'campaign_xyz',
  visitor_id: getVisitorId()
}, 'https://orbitforms.ai');
```

> [!NOTE]
>
> When embedding via iframe, the parent page can also pass these fields to the form with `postMessage` — see the Cometly iframe-tracking pattern linked in the [Embed Script documentation](https://docs.useorbitcrm.ai/developers/embed.md). If you're an analytics or attribution provider and want to integrate with OrbitForms, contact support for partnership options.

## Next Steps

> [card] [Webhooks](https://docs.useorbitcrm.ai/guides/webhooks.md)
>
> Receive real-time submission data

> [card] [Integrations](https://docs.useorbitcrm.ai/guides/integrations)
>
> Connect to CRMs and tools


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.