Leads

Create a lead from any external source — a website form, a landing page, or another system — using the Leads API. New leads are added to the team that owns the API key used in the request.

Create a lead

POST /api/method/crm.api.leads.create_lead

Headers

See Authentication for details.

Header	Required	Description
`X-API-Key`	Yes	The team API key.
`X-API-Secret`	Yes	The matching API secret.

Body parameters

Parameters can be sent as form-data or JSON.

Field	Required	Description
`name`	Yes	Full name of the lead. The first word becomes the first name; the rest becomes the last name.
`email`	No	Email address. Validated; an invalid address is rejected.
`phone`	No	Phone number. Skipped if the value is not a valid number.
`mobile_no`	No	Mobile number. Skipped if the value is not a valid number.
`country_code`	No	Dial code for phone parsing, for example `+91`. Used to split plain numbers into country code and national number.
`source`	No	Lead source name (team-scoped `CRM Lead Source`). If the name does not exist for the team, it falls back to `API`.
`organization`	No	Organization name.
`job_title`	No	Job title.
`website`	No	Website URL.
`territory`	No	Territory.
`industry`	No	Industry.
`annual_revenue`	No	Annual revenue.
`no_of_employees`	No	Number of employees.
`currency`	No	Currency code. Overridden to the workspace currency on creation and locked thereafter.
`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`	No	UTM attribution fields.
`<any_custom_field>`	No	Any field not listed above is captured into the lead's `extra_fields` JSON column (empty strings are ignored). See below.

Example request

curl -X POST https://crm.pixelwand.io/api/method/crm.api.leads.create_lead \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d "name=John Doe" \
  -d "email=john@example.com" \
  -d "phone=+1234567890" \
  -d "country_code=+91" \
  -d "source=Website" \
  -d "utm_source=google" \
  -d "referral_code=REF123" \
  -d "campaign_id=CAMP456"

Any parameter not in the list above is treated as a custom field and stored in the lead's extra_fields JSON column. These fields appear in the lead detail view under Extra Fields and behave identically to fields captured from unknown CSV columns during import.

# These unknown fields get stored in extra_fields automatically
-d "referral_code=REF123"
-d "campaign_id=CAMP456"
-d "custom_note=Found us via podcast"

The resulting extra_fields on the lead will be:

{
  "referral_code": "REF123",
  "campaign_id": "CAMP456",
  "custom_note": "Found us via podcast"
}

Responses

Success

{
  "success": true,
  "lead_id": "CRM-LEAD-0001",
  "message": "Lead created successfully"
}

If phone or mobile_no was skipped, the message includes a suffix like Lead created successfully (skipped invalid fields: phone).

Error

{
  "success": false,
  "error": "Name is required",
  "message": "Validation failed"
}

Authentication errors return error as API key required, Team ID required, or Invalid API key with message as Authentication failed.

Notes

name is the only required field; a request without it is rejected.
Invalid phone or mobile_no values are silently skipped rather than failing the whole request, so the lead is still created. Numbers with + or 00 are split into national number and country_code; plain numbers need country_code to be parsed correctly.
If no organization is provided, the lead's organization defaults to the lead's name. If source is unknown for the team, it falls back to the API source.