Create a lead

Create a lead in a CRM workspace and get the created record back.

POSThttps://nextgenpanel.cloudshope.com/api/v1/crm/workspaces/{workspaceId}/leads/create

Creates a lead in the given workspace. phone is the only required field — a 10-digit number.

Status, source and priority are picklist fields referenced by numeric id, and the assigned agent is a user id. Fetch the ids from the workspace's picklist and agent endpoints. If you omit statusId or priorityId, the workspace default is used; a lead with no sourceId stays sourceless.

If no contactId is given, a contact is found or created for the phone number automatically.

Any custom fields defined on the workspace go under customFields as a { key: value } object.

Authentication

Send Authorization: Bearer <token>. The token's account must be allowed to create leads in this workspace.

Path parameters

Name	Type	Required	Description
`workspaceId`	integer	Yes	The CRM workspace to create the lead in.

Body parameters

Name	Type	Required	Description
`phone`	string (10 digits)	Yes	Recipient phone number, exactly 10 digits.
`name`	string	No	Lead name. Defaults to "Untitled" if omitted.
`email`	string	No	A valid email address.
`assignedAgentId`	integer	No	User id of the agent this lead is assigned to.
`contactId`	integer	No	Link to an existing contact instead of matching on phone.
`statusId`	integer	No	Picklist option id for the lead status / Kanban column.
`sourceId`	integer	No	Picklist option id for the lead source.
`priorityId`	integer	No	Picklist option id for the lead priority.
`customFields`	object	No	`{ key: value }` for custom fields defined on the workspace.

Request

curl -X POST https://nextgenpanel.cloudshope.com/api/v1/crm/workspaces/8/leads/create \
  -H "Authorization: Bearer cs_live_9f2c…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ravi Menon",
    "email": "ravi@example.com",
    "phone": "9876543210",
    "sourceId": 31
  }'

Response

{
  "id": 5821,
  "workspaceId": 8,
  "name": "Ravi Menon",
  "email": "ravi@example.com",
  "phone": "9876543210",
  "assignedAgentId": null,
  "contactId": 9033,
  "statusId": 44,
  "sourceId": 31,
  "priorityId": 12,
  "customFields": {},
  "createdBy": 210,
  "createdAt": "2026-09-08T09:14:22.000Z",
  "updatedAt": "2026-09-08T09:14:22.000Z",
  "status": { "id": 44, "value": "new", "label": "New", "color": "#3B82F6" },
  "source": { "id": 31, "value": "website", "label": "Website", "color": null },
  "priority": { "id": 12, "value": "medium", "label": "Medium", "color": "#F59E0B" },
  "contact": { "id": 9033, "name": "Ravi Menon", "phone": "9876543210" },
  "collaborators": []
}

201 — example response

Errors

Status	Type	When
400	`INVALID_AGENT`	`assignedAgentId` does not match a known user.
400	`INVALID_CONTACT`	`contactId` does not match a contact in this workspace.
404	`not-found`	The workspace does not exist on this account or is inactive.
422	`validation-failed`	A field failed validation. The `errors` array names each field and why.
401	`unauthorized`	The `Authorization` header is missing, malformed or the token is invalid or expired.
403	`forbidden`	The token is valid but the account is not allowed to perform this action.