Reference
HTTP endpoints
On this page
This page lists every public HTTP endpoint served under /v1 on api.conclude.io, for developers wiring a website or mail provider to an app. Automation inside Conclude does not use these endpoints; it uses YAML, triggers, scripts, connectors, the lookup endpoint and agents. To work with connections, channels and the audit log from your own systems, use the API.
Summary
| Method and path | Called by | Purpose |
|---|---|---|
POST /v1/form/<cid> | Your web page | Create a ticket from a form submission |
POST /v1/activity.form/<cid> | Older embed scripts | Same handler as /v1/form/<cid>, kept for compatibility |
POST /v1/email/<id> | The inbound mail provider | Deliver an email to an email connector |
<cid> and <id> are connector IDs (web connector reference). Every endpoint applies a per-client rate limit (IP address plus user agent) first and answers 429 when it is exceeded.
POST /v1/form/<cid>
Creates a ticket in the channel where the app owning connector <cid> is installed; the web form guide covers the page side.
Request. Content-Type is application/json (a flat object of strings, up to 16 MB) or application/x-www-form-urlencoded (first value per field); anything else is 400. The connector ID is read from a cid header, a cid body field or the URL path, in that order; without one the response is 404. Fields map to attributes through the connector’s attributeMap (syntax; the keys are external and internal); unmapped fields keep their names, and every value is cut at 3000 characters. Two fields are special:
recaptcha: a Google reCAPTCHA v3 token, required with a score of at least 0.5 when the app’s secrets hold a reCAPTCHA private key; a token sent without a key also failsxid: an external ID from an earlier submission; if it names an existing ticket in the same organization, nothing is created andokis returned
Response. 200 with:
{"status": "ok", "xid": "<external id of the new ticket>"}
Most failures are also 200 with another status: validation_error, recaptcha_error, not_found_error, duplicate_request_error (identical payload within five minutes), rate_limit_error (the app’s rateLimit setting), internal_error or disabled_error. Two cases return 400 with {"error": "ValidationError", "details": "<message>"} instead: an unknown connector ID and an Origin host outside the connector’s domain list. When set, logMessage posts accepted submissions to a channel and logJunk posts rejected ones (reCAPTCHA or validation failure).
POST /v1/email/<id>
Receives raw inbound email from the mail provider (Twilio SendGrid) for an email connector. Your code never calls it; mail goes to the connector address from the email guide.
<id> is a connector ID or any, which resolves the connector from the To, Reply-To, Cc, Bcc and forwarding headers, then the envelope recipient. It returns 200 even for parse failures and mail dropped as definite spam, so the provider does not retry; only a missing ID (404) and the rate limit (429) differ. When no connector matches, the sender gets an automatic reply unless their message was one. No CORS headers are set.
CORS
The form endpoints answer browsers from any origin: responses carry Access-Control-Allow-Origin: *, and an OPTIONS preflight on any /v1 path returns 204 allowing POST, GET, OPTIONS and the Accept, Accept-Encoding, Accept-Language, Content-Type and Content-Length headers. Which sites may submit depends on the connector’s domain setting, not on CORS: it matches the Origin host or a subdomain against a comma-separated list. Non-browser clients can send any Origin; use reCAPTCHA and rateLimit against abuse.