> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.default.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fire a trigger
> Runs the workflow connected to the API trigger with the submitted form responses. Always returns the `executionId`. The `outcome` is what the workflow exited with, discriminated on `outcome.type`. `scheduler` means a meeting should be booked. Pass `outcome.schedulingLinkId` as the event to [`POST /v1/scheduling/events/{event}/slots`](/api-reference/scheduling/get-available-slots) and `executionId` as `workflowExecutionId` when [booking](/api-reference/scheduling/book-a-meeting). `redirect` carries a URL the workflow chose to send the lead to. `none` means the workflow finished, or is still running in the background, without offering either. That is a valid outcome, not an error.
Requires the `triggers:write` scope.
Every call starts a new workflow run and repeats the steps before the scheduler, including CRM writes and steps that consume a routing assignment. When you already have an outcome, reuse it instead of firing again.
## OpenAPI
````yaml /api-reference/openapi.json post /v1/triggers/{trigger}
openapi: 3.1.0
info:
title: Default Public API
version: 1.0.0
description: >-
Customer-facing REST API for scheduling and workflow triggers: list events,
fetch availability, book, reschedule, or cancel meetings, and fire API
triggers. Authenticate every request with `Authorization: Bearer `
using an API key created in workspace settings (Settings → API Keys). Keys
carry permissions (`scheduling:read`, `scheduling:write`, `triggers:read`,
`triggers:write`; a write key also satisfies read for its surface) and can
be revoked at any time. Requests are rate limited to 30 per minute per key —
a 429 response carries a `Retry-After` header with the seconds until the
window resets. This is a server-to-server API: no CORS headers are sent, so
it cannot be called directly from a browser.
servers:
- url: https://api.default.com
security:
- apiKey: []
paths:
/v1/triggers/{trigger}:
post:
tags:
- Triggers
summary: Fire a trigger
description: >-
Runs the workflow connected to the API trigger with the submitted form
responses. Always returns the `executionId`. The `outcome` is what the
workflow exited with, discriminated on `outcome.type`. `scheduler` means
a meeting should be booked. Pass `outcome.schedulingLinkId` as the event
to [`POST
/v1/scheduling/events/{event}/slots`](/api-reference/scheduling/get-available-slots)
and `executionId` as `workflowExecutionId` when
[booking](/api-reference/scheduling/book-a-meeting). `redirect` carries
a URL the workflow chose to send the lead to. `none` means the workflow
finished, or is still running in the background, without offering
either. That is a valid outcome, not an error.
Requires the `triggers:write` scope.
operationId: fireTrigger
parameters:
- name: trigger
in: path
required: true
description: Trigger id from the list endpoint.
schema:
description: Trigger id from the list endpoint.
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
description: >-
The lead being routed. Identity always comes from this
field, never from responses. The connected form's email
field is filled from it automatically.
type: string
format: email
responses:
description: >-
Form field values, keyed by field name from the list
endpoint.
default: {}
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
- type: array
items:
type: string
context:
description: >-
Web context you know about the lead. All fields optional. It
becomes form submission data the workflow can reference and
records as attribution on a booked meeting.
type: object
properties:
utmParams:
description: >-
UTM attribution from the page the lead came from,
standard keys only.
type: object
properties:
utm_source:
type: string
maxLength: 1024
utm_medium:
type: string
maxLength: 1024
utm_campaign:
type: string
maxLength: 1024
utm_term:
type: string
maxLength: 1024
utm_content:
type: string
maxLength: 1024
gclid:
description: Google click id.
type: string
maxLength: 1024
pageUrl:
description: URL of the page the lead was on.
type: string
maxLength: 2048
referrer:
description: Referrer of that page.
type: string
maxLength: 2048
userAgent:
description: The lead's browser user agent.
type: string
maxLength: 1024
ipAddress:
description: The lead's IP address.
type: string
maxLength: 64
required:
- email
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
executionId:
type: string
format: uuid
outcome:
anyOf:
- type: object
properties:
type:
type: string
const: scheduler
schedulerUrl:
type: string
schedulingLinkId:
type: string
format: uuid
required:
- type
- schedulerUrl
- schedulingLinkId
additionalProperties: false
- type: object
properties:
type:
type: string
const: redirect
url:
type: string
required:
- type
- url
additionalProperties: false
- type: object
properties:
type:
type: string
const: none
required:
- type
additionalProperties: false
required:
- executionId
- outcome
additionalProperties: false
'400':
description: Error (INVALID_REQUEST, WORK_EMAIL_REQUIRED)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INVALID_REQUEST
- WORK_EMAIL_REQUIRED
message:
type: string
details:
type: array
items:
type: string
examples:
INVALID_REQUEST:
summary: INVALID_REQUEST
value:
error:
code: INVALID_REQUEST
message: Request validation failed
details:
- 'personEmail: Invalid email address'
WORK_EMAIL_REQUIRED:
summary: WORK_EMAIL_REQUIRED
value:
error:
code: WORK_EMAIL_REQUIRED
message: This event requires a work email address
'401':
description: Error (INVALID_API_KEY)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INVALID_API_KEY
message:
type: string
details:
type: array
items:
type: string
examples:
INVALID_API_KEY:
summary: INVALID_API_KEY
value:
error:
code: INVALID_API_KEY
message: Missing, malformed, or revoked API key
'403':
description: Error (MISSING_SCOPE)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- MISSING_SCOPE
message:
type: string
details:
type: array
items:
type: string
examples:
MISSING_SCOPE:
summary: MISSING_SCOPE
value:
error:
code: MISSING_SCOPE
message: >-
This API key is missing the required 'triggers:write'
scope
'404':
description: Error (NOT_FOUND)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- NOT_FOUND
message:
type: string
details:
type: array
items:
type: string
examples:
NOT_FOUND:
summary: NOT_FOUND
value:
error:
code: NOT_FOUND
message: Trigger not found
'429':
description: Error (RATE_LIMITED)
headers:
Retry-After:
description: Seconds until the current rate-limit window resets.
schema:
type: integer
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- RATE_LIMITED
message:
type: string
details:
type: array
items:
type: string
examples:
RATE_LIMITED:
summary: RATE_LIMITED
value:
error:
code: RATE_LIMITED
message: Rate limit exceeded for this API key
'500':
description: Error (INTERNAL_ERROR)
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- INTERNAL_ERROR
message:
type: string
details:
type: array
items:
type: string
examples:
INTERNAL_ERROR:
summary: INTERNAL_ERROR
value:
error:
code: INTERNAL_ERROR
message: Internal server error
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
description: >-
Organization API key, created in workspace settings (Settings → API
Keys). Sent as `Authorization: Bearer `. Shown once at creation;
revocable and permission-scoped per key.
````