Organization API

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, an Originator (the owner is credited when originatorId is omitted), 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.

/api/v1/leads

Create a Lead. Use an organization API key with leads:write. Check the response envelope and meta.requestId before triggering dependent workflow steps.

Required scopes

leads:writeIdempotency-Key required

Parameters

No path or query parameters.

Request body

#/components/schemas/LeadCreateRequestrequired

Field	Type	Description
firstNamerequired	string	Optional unless marked required.
lastNamerequired	string	Optional unless marked required.
email	string	Optional unless marked required.
phone	string	Optional unless marked required.
address	string	Optional unless marked required.
city	string	Optional unless marked required.
state	string	Optional unless marked required.
zipCode	string	Optional unless marked required.
status	NEW \| CONTACTED \| QUALIFIED \| UNQUALIFIED	Optional unless marked required.
sourceId	string	Optional unless marked required.
campaignId	string	Optional unless marked required.
salesTypeIds[]	array<string>	Optional unless marked required.
ownerId	string	Optional unless marked required.
originatorId	string \| null	The active or draft same-organization Team Member credited with bringing this sale in. When omitted, the owner is credited.
notes	string	Optional unless marked required.
customFields	object	Field Values keyed by savedIdentity from /v1/schema resources.leads.customFields.
externalReferences[]	array<object>	Optional unless marked required.
externalReferences[].externalSystemrequired	string	Optional unless marked required.
externalReferences[].externalObjectrequired	string	Optional unless marked required.
externalReferences[].externalIdrequired	string	Optional unless marked required.

websiteLeadForm

{
  "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"
      }
    }
  ]
}

leadWithCustomFields

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "ada@example.com",
  "ownerId": "team_member_123",
  "sourceId": "source_123",
  "customFields": {
    "roofType": "tile"
  },
  "externalReferences": [
    {
      "externalSystem": "salesforce",
      "externalObject": "Lead",
      "externalId": "00Q123"
    }
  ]
}

Responses

201

Created Lead envelope

#/components/schemas/LeadEnvelope

400

Validation, ownership, idempotency, or custom Field error