Skip to main content
Talk to salesStart

Create lead

Create a new lead with automatic company matching and deduplication.

POST/api/leads/
HTTP referenceScope leads:writeUpdated April 25, 2026

This page documents the canonical HTTP contract for this endpoint.

At least one concrete person identity signal is required: a non-placeholder LinkedIn URL/member ID/Sales URL, first or last name, email/email_addresses, or phone/phone_numbers. Body fields organization_id, organizationId, user_id, userId, created_by, and createdBy are rejected; the optional legacy query parameters organization_id and user_id are accepted but ignored. Authenticated organization and actor determine ownership. The response is the normalized Lead record and may include populated company and priority data.

Query parameters

  • organization_id · optional

    string

    Legacy compatibility parameter; accepted but ignored. Organization comes from authentication.

  • user_id · optional

    string

    Legacy compatibility parameter; accepted but ignored. Actor comes from authentication.

Body parameters

  • first_name · optional

    string

    Lead first name.

  • last_name · optional

    string

    Lead last name.

  • email · optional

    string

    Primary email address; may satisfy the required person identity signal.

  • email_addresses · optional

    array<object>

    Optional email channel entries.

  • primary_phone · optional

    string

    Optional primary phone; may satisfy the required person identity signal.

  • phone_numbers · optional

    array<object>

    Optional phone channel entries.

  • company_domain · optional

    string

    Company domain for matching.

  • linkedin_url · optional

    string

    LinkedIn profile URL.

  • linkedin_member_id · optional

    string

    LinkedIn member identifier; may satisfy the person identity requirement.

  • linkedin_sales_url · optional

    string

    LinkedIn Sales profile URL; may satisfy the person identity requirement.

  • company_name · optional

    string

    Optional company name.

  • company_linkedin_url · optional

    string

    Optional company LinkedIn URL.

  • location · optional

    string

    Optional location.

  • notes · optional

    string

    Optional notes.

  • custom_fields · optional

    object

    Custom field values; defaults to {}.

  • ownerUserId · optional

    string

    Optional owner user ID; does not set authenticated actor or organization.

  • title · optional

    string

    Job title.

  • lead_source · optional

    string

    Lead source identifier. Defaults to api_create.

  • lead_status · optional

    string

    Initial Lead status; valid values: new, qualified, contacting, converted, customer, unqualified, bad_data, nurture.

Errors

StatusMeaning
400Lead creation failed or invalid payload.
401Invalid API key or missing auth.
403Missing leads:write scope.
409Lead already exists (duplicate detected).

Docs