Create a Lead
Creates one Lead for the authenticated organization, including website form submissions and external CRM imports. Requires Idempotency-Key. Supports Campaign attribution, Sales Type assignment, Lead Source, owner/default-owner assignment, standard contact/address fields, customFields, and External References. Use /v1/schema before calling to discover valid customFields and required Field values. External References are created transactionally and conflicts return 409. Side effects include API actor ActivityLog, domain outbox event, idempotency capture, and usage telemetry. Required scope: leads:write.
Creates one Lead for the authenticated organization, including website form submissions and external CRM imports. Requires Idempotency-Key. Supports Campaign attribution, Sales Type assignment, Lead Source, owner/default-owner assignment, standard contact/address fields, customFields, and External References. Use /v1/schema before calling to discover valid customFields and required Field values. External References are created transactionally and conflicts return 409. Side effects include API actor ActivityLog, domain outbox event, idempotency capture, and usage telemetry. Required scope: leads:write.
Organization API key. Format: Bearer sk_live_...
In: header
Request Body
application/json
JSON request payload for createLead.
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/leads" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Ada", "lastName": "Lovelace", "email": "ada@example.com", "phone": "+15555550123", "address": "1 Market St", "city": "San Francisco", "state": "CA", "zipCode": "94105", "sourceId": "source_website", "campaignId": "campaign_spring_2026", "salesTypeIds": [ "sales_type_install" ], "notes": "Submitted the rooftop solar estimate form.", "customFields": { "roofType": "tile" }, "externalReferences": [ { "externalSystem": "website", "externalObject": "ContactFormSubmission", "externalId": "form_submission_123", "metadata": { "page": "/solar-estimate" } } ] }'{ "data": { "id": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "phone": "string", "address": "string", "city": "string", "state": "string", "zipCode": "string", "status": "string", "sourceId": "string", "campaignId": "string", "ownerId": "string", "notes": "string", "source": {}, "campaign": {}, "owner": {}, "salesTypeIds": [ "string" ], "salesTypes": [ {} ], "customFields": {}, "externalReferences": [ {} ], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }, "meta": { "requestId": "string", "version": "v1", "timestamp": "2019-08-24T14:15:22Z", "rateLimit": { "limit": 0, "remaining": 0, "reset": 0 } }}