Inbound Leads API

Use the Inbound Leads API when a trusted server can send Convertly-shaped lead data. It is an intake API, not a general CRM read API.

Create an API key

API-key management is restricted to workspace Admins.

1. Open Settings -> API -> API Keys.
2. Create a key with a clear source name.
3. Copy the key when it is shown. Existing key values cannot be displayed later.
4. Store it in a server-side secret manager or environment variable.
5. Configure optional Lead Defaults and New Lead Alert recipients.

Never place the API key in browser JavaScript, a public form, a URL, documentation, or a client-side environment variable.

Send a request

Send a server-to-server POST request to:

https://app.convertlycrm.com/api/leads/inbound

Authenticate with either x-api-key or a Bearer Authorization header. Query-string API keys are not supported for normal production use.

curl -X POST "https://app.convertlycrm.com/api/leads/inbound" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY_FROM_A_SECRET_STORE" \
  -d '{
    "name": "Example Lead",
    "email": "lead@example.test",
    "phone": "+15555550100",
    "source": "API",
    "value": 2500,
    "utm_source": "partner",
    "utm_campaign": "spring-demo",
    "consent_status": "granted"
  }'

The example values are placeholders. Do not copy real customer data into documentation or test tools you do not control.

Supported data

The API accepts common contact names plus:

• Stage, approved source, owner, value, categories, notes, and custom fields
• UTM source, medium, campaign, term, and content
• Landing page and referrer
• Google and Meta click or browser identifiers
• Campaign, ad, and ad-set identifiers
• Supported consent status and timestamp

Unknown source labels are not added automatically. Configure approved sources in Settings -> General -> Lead Sources.

Lead Defaults

Per-key defaults fill supported fields missing from the payload. Submitted fields take priority. Source-level new-lead alert recipients remain independent from field defaults.

Duplicates and results

A matching tenant lead by normalized email or phone is updated with duplicate-submission context rather than duplicated. A successful duplicate result returns the existing lead ID.

Requests can also be rejected or skipped for invalid credentials, invalid data, abuse protection, or a spam-trap field. Review Settings -> API -> API Logs for safe result metadata.