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.
`source`	No	Lead source (default: `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.
`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` (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 "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"
}

Error

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

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.