Search Knowledge Base Articles

Lead - Add New Lead [code]

Create Lead API

IT IS IMPORTANT TO FOLLOW THE INFORMATION BELOW

Endpoint:
POST /api/leads

Description

Create a new lead in the CRM. Optionally, if enabled for your API user, this endpoint can also open a trading account for the lead.

Required Headers

Header Value/Example Required Description
authtoken your-api-token-here Yes API authentication token. Must be provided in the request headers.
Content-Type application/json
application/x-www-form-urlencoded
multipart/form-data
application/xml		 Yes The format of the request body. JSON, form-data, or XML are supported.

Important Notes

  • Trading Account Creation:
    To open a trading account for the lead, the API user (your token) must have the "Open Trading Account" feature enabled. If not enabled, only the lead will be created in the CRM.
    Password is required only if trading account creation is enabled for your API user.
  • Status ID Reference:
    The status field must be set to a valid status ID.
    To fetch all available statuses, send a GET request to /api/leads/statuses.
    See the documentation for lead statuses here.
  • Custom Fields:
    You can send custom fields as additional key-value pairs in the request. To find available custom field keys, visit: https://your_crm_url/admin/custom_fields

Request Body Parameters

CHECK FOR ONLY ONE FIELD FOR SOURCE OR SOURCE_ID. BOTH WILL NOT WORK TOGETHER

Name Type Required Description
name string Yes Lead name
source string No Lead source ID
status string No Lead status ID (see above)
email string Yes Lead email address
assigned string No Assigned staff ID
client_id string No Related client/customer ID
tags string No Comma-separated tags
contact string No Contact name
title string No Position/title
website string No Website URL
phonenumber/phone string No Phone number
company string No Company name
address string No Address
city string No City
state string No State
country string No Country ID
default_language string No Default language
description string No Description
custom_contact_date string No Custom contact date
contacted_today string No Contacted today flag
is_public string No Public flag
username string No Trading account username (if applicable)
password string Conditional Trading account password (required only if trading account creation is enabled)
custom_fields object No Custom fields (key-value pairs, see below)

Request Example (JSON)

{
  "name": "John Doe",
  "source": "1",
  "status": "4",
  "email": "john.doe@example.com",
  "phonenumber": "1234567890",
  "company": "Nanza",
  "assigned": "5",
  "leads_funnel_param": "SEO"
}

Request Example (XML)

<lead>
    <name>John Doe</name>
    <source>1</source>
    <status>4</status>
    <email>john.doe@example.com</email>
    <phonenumber>1234567890</phonenumber>
    <company>Nanza</company>
    <assigned>5</assigned>
    <leads_funnel_param>SEO</leads_funnel_param>
</lead>

Success Response

{
  "status": true,
  "message": "john.doe@example.com has been successfully registered",
  "lead_id": 123,
  "autologin_link": "https://platform.example.com/autologin/abc123" // Only if trading account created
}

Error Response (Validation Error)

{
  "status": false,
  "message": "Validation failed",
  "errors": {
    "email": "The Email field must contain a valid email address.",
    "name": "The Name field is required."
  }
}

Related Endpoints

Did you find this article useful?

Related Articles