Create an eflow

Three creation modes: an empty draft, content inline, or templateId to copy a gallery template. Send an Idempotency-Key header to make a retry after a timeout safe — replaying the same key returns the original eflow rather than creating a second one.

Requires the eflows:write scope.

Example request

curl https://api.acquainto.com/v1/eflows \
  -H "Authorization: Bearer acq_live_xxxxxxxx" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "title": "string",
    "description": "string",
    "tonePreset": "efficient",
    "resumeTokenTtlHours": 1
  }'

Request body

titlestringrequired
descriptionstring | null
tonePreset"efficient" | "friendly" | "concierge"
resumeTokenTtlHoursinteger
notifyOnCompletionboolean
introScreenEnabledboolean
requireLinkTokenboolean
openingStatementstring | null
openingStatementSurfacesarray of "hosted" | "iframe" | "chat_box"
completionStatementstring | null
completionStatementSurfacesarray of "hosted" | "iframe" | "chat_box"
completionCtaLabelstring | null
completionCtaUrlstring | null
completionCtaSurfacesarray of "hosted" | "chat_box"
completionRedirectUrlstring | null
completionEmailContent"link_only" | "full"
contentobject
- questionsarray of object
  - keystring
  - textstringrequired
  - type"text" | "single_select" | "multi_select" | "scale" | "email" | "phone" | "date" | "money" | "number" | "url"required
  - requiredboolean
  - optionsarray of object
    - idstring
    - labelstringrequired
    - valuestringrequired
  - configobject
- branchesarray of object
  - keystring
  - sourceQuestionKeystringrequired
  - triggerOptionIdstringrequired
  - labelstringrequired
  - questionsarray of object
    - keystring
    - textstringrequired
    - type"text" | "single_select" | "multi_select" | "scale" | "email" | "phone" | "date" | "money" | "number" | "url"required
    - requiredboolean
    - optionsarray of object
      - idstring
      - labelstringrequired
      - valuestringrequired
    - configobject
templateIdstring

Responses

201Create an eflow

idstringrequired
A eflow id, prefixed `eflow_`.
titlestringrequired
descriptionstring | nullrequired
status"draft" | "live" | "paused" | "archived"required
tonePreset"efficient" | "friendly" | "concierge"required
resumeTokenTtlHoursintegerrequired
How long a respondent may leave and come back before their progress expires.
notifyOnCompletionbooleanrequired
introScreenEnabledbooleanrequired
Show the pre-conversation intro screen -- who is asking, how long it takes, where the answers go -- before the first question, with a Start button. False drops the respondent straight into turn 1, and no session (or model call) exists until they answer.
requireLinkTokenbooleanrequired
Refuse to start a new session for this eflow unless the request carries a valid link token minted by POST /v1/eflows/{id}/links. Off by default: a bare {eflowId} starts an anonymous session same as always. On, an anonymous POST /api/v1/sessions gets a 403 link_token_required -- resuming an existing session is unaffected.
openingStatementstring | nullrequired
openingStatementSurfacesarray of "hosted" | "iframe" | "chat_box"required
completionStatementstring | nullrequired
completionStatementSurfacesarray of "hosted" | "iframe" | "chat_box"required
completionCtaLabelstring | nullrequired
completionCtaUrlstring | nullrequired
completionCtaSurfacesarray of "hosted" | "chat_box"required
completionRedirectUrlstring | nullrequired
Where a respondent is sent ~8s after the completion screen, with a visible notice they can decline. Applies where the conversation is the page (the hosted link and inline embeds); ignored in the floating chat box and iframe embeds, where navigating would move the embed rather than the page. https: only.
completionEmailContent"link_only" | "full"required
How much of a response a completion email carries. `full` embeds every answer inline. `link_only` sends the eflow title, respondent, completion time and question count plus a link into the app, and no answer content -- an email is the one copy of a response neither the retention sweep nor an erasure request can reach. Existing eflows are `full`; that is what they have always sent.
versionintegerrequired
Increments on every write. Send it back as `If-Match` so a concurrent edit fails loudly instead of being clobbered.
createdAtstringrequired
updatedAtstringrequired
publishedAtstring | nullrequired
The *first* time this eflow went live, not the latest -- a pause/resume cycle does not move it.
contentobjectrequired
- questionsarray of objectrequired
  - idstringrequired
    A question id, prefixed `q_`.
  - keystring | nullrequired
    The stable identifier to key your own storage on. Null only for questions authored before keys existed and never re-saved since.
  - textstringrequired
    The authored prompt. A label, not a key -- it changes when someone fixes a typo.
  - typestringrequired
  - requiredbooleanrequired
  - optionsarray of object
    Present on select-type questions only.
    - idstringrequired
    - labelstringrequired
    - valuestringrequired
  - configobjectrequired
    Whatever type-specific options the question carries beyond `type` and `options`. Two are required, not defaulted: `min` and `max` on a `scale` question (e.g. 1 and 10), and `currency` on a `money` question. A `scale` range spans at most 10 (11 buttons); the widget draws one button per integer and the row cannot wrap.
- branchesarray of objectrequired
  - idstringrequired
    A branch id, prefixed `br_`.
  - keystring | nullrequired
  - sourceQuestionKeystring | nullrequired
    The question whose answer opens this branch.
  - triggerOptionIdstringrequired
    The option on `sourceQuestionKey` that opens it.
  - labelstringrequired
  - questionsarray of objectrequired
    - idstringrequired
      A question id, prefixed `q_`.
    - keystring | nullrequired
      The stable identifier to key your own storage on. Null only for questions authored before keys existed and never re-saved since.
    - textstringrequired
      The authored prompt. A label, not a key -- it changes when someone fixes a typo.
    - typestringrequired
    - requiredbooleanrequired
    - optionsarray of object
      Present on select-type questions only.
      - idstringrequired
      - labelstringrequired
      - valuestringrequired
    - configobjectrequired
      Whatever type-specific options the question carries beyond `type` and `options`. Two are required, not defaulted: `min` and `max` on a `scale` question (e.g. 1 and 10), and `currency` on a `money` question. A `scale` range spans at most 10 (11 buttons); the widget draws one button per integer and the row cannot wrap.

400The request was malformed or failed validation.

errorobjectrequired
- type"invalid_request_error" | "authentication_error" | "permission_error" | "not_found_error" | "idempotency_error" | "rate_limit_error" | "api_error"required
  The bucket a client branches on to decide how to react.
- codestringrequired
  Stable machine-readable code. Branch on this, not on `message`.
- messagestringrequired
  Human-readable. May change without notice.
- paramstring
  The offending request field, when the error names one.
- requestIdstringrequired
  Echoes the `req_...` id; quote it in support requests.

401Missing, invalid, or revoked credential.

errorobjectrequired
- type"invalid_request_error" | "authentication_error" | "permission_error" | "not_found_error" | "idempotency_error" | "rate_limit_error" | "api_error"required
  The bucket a client branches on to decide how to react.
- codestringrequired
  Stable machine-readable code. Branch on this, not on `message`.
- messagestringrequired
  Human-readable. May change without notice.
- paramstring
  The offending request field, when the error names one.
- requestIdstringrequired
  Echoes the `req_...` id; quote it in support requests.

403The credential lacks the scope this route requires.

errorobjectrequired
- type"invalid_request_error" | "authentication_error" | "permission_error" | "not_found_error" | "idempotency_error" | "rate_limit_error" | "api_error"required
  The bucket a client branches on to decide how to react.
- codestringrequired
  Stable machine-readable code. Branch on this, not on `message`.
- messagestringrequired
  Human-readable. May change without notice.
- paramstring
  The offending request field, when the error names one.
- requestIdstringrequired
  Echoes the `req_...` id; quote it in support requests.

409Error.

errorobjectrequired
- type"invalid_request_error" | "authentication_error" | "permission_error" | "not_found_error" | "idempotency_error" | "rate_limit_error" | "api_error"required
  The bucket a client branches on to decide how to react.
- codestringrequired
  Stable machine-readable code. Branch on this, not on `message`.
- messagestringrequired
  Human-readable. May change without notice.
- paramstring
  The offending request field, when the error names one.
- requestIdstringrequired
  Echoes the `req_...` id; quote it in support requests.

429Rate limited. Retry after the interval in `Retry-After`.

errorobjectrequired
- type"invalid_request_error" | "authentication_error" | "permission_error" | "not_found_error" | "idempotency_error" | "rate_limit_error" | "api_error"required
  The bucket a client branches on to decide how to react.
- codestringrequired
  Stable machine-readable code. Branch on this, not on `message`.
- messagestringrequired
  Human-readable. May change without notice.
- paramstring
  The offending request field, when the error names one.
- requestIdstringrequired
  Echoes the `req_...` id; quote it in support requests.

500Something failed on our side. Safe to retry.

errorobjectrequired
- type"invalid_request_error" | "authentication_error" | "permission_error" | "not_found_error" | "idempotency_error" | "rate_limit_error" | "api_error"required
  The bucket a client branches on to decide how to react.
- codestringrequired
  Stable machine-readable code. Branch on this, not on `message`.
- messagestringrequired
  Human-readable. May change without notice.
- paramstring
  The offending request field, when the error names one.
- requestIdstringrequired
  Echoes the `req_...` id; quote it in support requests.

Browse every operation, with full request/response schemas, in the full API reference.