Send leads from your website with the write API

The write API lets an external system, usually your marketing site, create leads exactly as if they came through a native form. This article issues the token and makes the first call. The API is currently in beta.

Issue a service token

1. Go to Settings, then Service tokens. Admins only.
2. Click Mint token. Pick the brand it belongs to and the intake form submissions will run through. The form's field rules validate every payload.
3. Grant the leads:write scope and set an optional expiry and rate limit (60 requests a minute by default).
4. Copy the secret. It is shown once and starts with a recognisable prefix.
5. Click API documentation on the same page for the reference with your workspace's base URL.

Make the call

Send a POST to /api/v1/leads with the bearer token, a JSON body, and an Idempotency-Key header:

POST /api/v1/leads
Authorization: Bearer <service token>
Content-Type: application/json
Idempotency-Key: <your event id>

{ "email": "ada@acme.com", "firstName": "Ada", "company": "Acme",
  "website": "https://acme.com", "message": "Interested in an SEO retainer",
  "sourceUrl": "https://yoursite.com/contact",
  "utm": { "utm_source": "google", "utm_campaign": "brand" } }

A success returns 201 with the lead id, the form it ran through, and unmappedFields listing values the form has no field for. Those were not stored; add the field to the form or drop it from the payload. The response is identical whether the contact was new or matched, so the endpoint cannot be used to probe the CRM.

What happens inside

The payload runs through the same intake as a form: contact dedup by email, company match by domain, deal dedup, consent recorded with the API as its source, workflow triggers, and owner notification.

Errors

Log the requestId on failure; it matches server logs. Write to Verbial alongside your existing submission handling, never in its place, so an outage cannot break a form.

What to check

• Bodies over 64 KB are rejected.
• Revoke a token from the Service tokens page; revocation is immediate.