Guides

Capture forms

Define structured forms your assistant fills in during a conversation and delivers to email or SMS recipients.

A capture form is a structured set of questions attached to an assistant. Each form has a trigger describing when it applies, an introMessage the assistant uses to start the form, an ordered list of typed fields to collect, and one or more recipients (email and/or SMS) who receive the captured answers.

Typical use: a callback-request form ("caller wants a call back") that collects name, phone, and reason, then emails the details to your front desk.

Method	Path	Purpose
GET	`/capture-forms`	List capture forms (optionally by assistant)
GET	`/capture-forms/{id}`	Get one capture form
POST	`/capture-forms`	Create a capture form
PUT	`/capture-forms/{id}`	Replace a capture form
PATCH	`/capture-forms/{id}`	Partially update a capture form
DELETE	`/capture-forms/{id}`	Delete a capture form

Form structure#

Field	Type	Required	Description
`assistantId`	UUID	Yes	The assistant this form belongs to (ownership is validated)
`name`	string	Yes	Form name
`trigger`	string	Yes	When the assistant should run this form
`introMessage`	string	Yes	What the assistant says when starting the form
`emailRecipients`	string[] (emails)	See note	Who receives the results by email
`smsRecipients`	string[] (phone numbers)	See note	Who receives the results by SMS
`fields`	field[]	Yes (min 1)	The questions to collect — see below
`properties`	object	No	Free-form metadata, defaults to `{}`
`isActive`	boolean	No	Whether the form is active

At least one recipient

On create (and full replace), emailRecipients and smsRecipients together must contain at least one entry. SMS recipients must be valid phone numbers. On PATCH the rule is enforced whenever you touch either recipients field.

Fields#

Each entry in fields:

Field	Type	Required	Description
`key`	string	Yes	Unique per form, lowercase snake_case (e.g. `contact_email`)
`question`	string	Yes	What the assistant asks
`type`	`string` \| `number`	Yes	Expected answer type
`required`	boolean	No	Whether the answer is mandatory
`options`	string[]	No	Allowed choices
`action`	string	No	Extra action hint for this field
`wait_for_response`	boolean	No	Whether to pause for the answer
`prompt`	string	No	Guidance injected into the system prompt to steer how the AI asks this field. Supports `{question}` (replaced with this field's question) and `{{property}}` client-parameter placeholders.

Duplicate key values across fields are rejected with a validation error.

Create a capture form#

POST /capture-forms

bash

curl -X POST https://core-api.heysadie.ai/capture-forms \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "ASSISTANT_ID",
    "name": "Callback request",
    "trigger": "The caller asks for a call back from a human.",
    "introMessage": "Sure — I just need a few details so the team can call you back.",
    "emailRecipients": ["[email protected]"],
    "fields": [
      {
        "key": "caller_name",
        "question": "What is your full name?",
        "type": "string",
        "required": true
      },
      {
        "key": "callback_number",
        "question": "What is the best number to reach you on?",
        "type": "string",
        "required": true
      },
      {
        "key": "reason",
        "question": "What is the call back regarding?",
        "type": "string"
      }
    ],
    "isActive": true
  }'

List capture forms#

GET /capture-forms

Query param	Type	Required	Description
`limit`	number	No	Page size, max 500 (default 50)
`offset`	number	No	Items to skip
`assistantId`	UUID	No	Only forms for this assistant

Terminal

curl "https://core-api.heysadie.ai/capture-forms?assistantId=ASSISTANT_ID" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Update a capture form#

Two options:

PUT /capture-forms/{id} — full replace; the body is the same as create (all required fields again, at least one recipient).
PATCH /capture-forms/{id} — partial update; assistantId is still required in the body, everything else is optional. Sending fields replaces the whole field list (min 1 entry).

Terminal

curl -X PATCH https://core-api.heysadie.ai/capture-forms/CAPTURE_FORM_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "assistantId": "ASSISTANT_ID", "isActive": false }'

Delete a capture form#

Terminal

curl -X DELETE https://core-api.heysadie.ai/capture-forms/CAPTURE_FORM_ID \
  -H "Authorization: ApiKey YOUR_API_KEY"

Next steps#

Assistants — the assistant a form belongs to.
Custom instructions — lighter-weight behavior tweaks that don't collect data.

PreviousConversations NextCustom instructions