Create a lead

Creates a new lead in the workspace. The request body must include the lead identifier (default: phone); other fields are optional. An actions array creates timeline entries on the new lead in the same call.

This endpoint supports partial success — fields and actions that fail validation are reported in a remarks array while the lead itself is still created.

Request

Field	Value
Method	POST
URL	https://next.telecrm.in/autoupdate/v2/enterprise/{enterpriseId}/lead
Auth	Bearer token (Sync-typed). See Authentication.
Headers	Content-Type: application/json

Path parameters

Name	Type	Required	Description
enterpriseId	string	yes	The enterprise (workspace) ID. Find it under Settings → Website and API in the dashboard.

Body

Field	Type	Required	Description
fields	object	yes	Lead field values keyed by field API name. Must include the lead identifier. Each value must conform to its field type.
actions	array of object	no	Initial timeline entries. Each entry is a custom action (with bare numeric type) or a PAYMENT action.

Example request

curl -X POST "https://next.telecrm.in/autoupdate/v2/enterprise/{enterpriseId}/lead" \
  -H "Authorization: Bearer YOUR_SYNC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "name": "Jane Doe",
      "phone": "919999999999",
      "email": "jane.doe@example.com"
    },
    "actions": [
      {
        "type": "1001",
        "fields": { "note": "Site visit completed" }
      }
    ]
  }'

Responses

201 Created

The lead was created. Some fields or actions in the request may have been ignored due to validation; check the remarks array.

{
  "lead_id": "603d2b2f9b1e8a001c8e4f5c",
  "actions": [
    { "action_id": "603d2b2f9b1e8a001c8e4f5d", "status": "CREATED" }
  ],
  "remarks": [
    { "field": "fields.rating", "status": "IGNORED", "remark": "Rating must be between 1 and 5" }
  ]
}

400 Bad Request

Lead-level validation failed (e.g. the identifier field was missing).

{
  "error": {
    "code": "INVALID_LEAD",
    "message": "Lead identifier field 'phone' not found in request body."
  }
}

401 Unauthorized

See the universal 401 in the overview.

409 Conflict

A lead with the same identifier value already exists. Use POST /lead/{leadId} to update it instead.

{
  "error": {
    "code": "LEAD_ALREADY_EXISTS",
    "message": "Lead with leadid value 919999999999 already exists"
  }
}

Notes

• Standard field API names: name, phone, email, rating, status, assignee. Custom fields use whatever API name was configured under Settings → Lead Fields.
• A field is dropped with a remark, rather than failing the request, when its API name doesn't exist in the workspace (Field definition not found) or when the field is hidden from the default view (Field is hidden). A hidden field looks entirely valid from the caller's side — check isVisible on GET /custom-fields before relying on one.
• Sync custom action type is the bare numeric code ("1001"), not the ACTION_ form used by Async.
• See Pitfalls for common mistakes around identifiers, partial success, and 409 handling.