Create a lead

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

POSThttps://nextgenpanelstaging.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 source is required: send sourceId, or sourceName (the option's label or value, e.g. "Website"). statusName and priorityName work the same way as alternatives to statusId and priorityId; an id sent alongside a name wins.

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	The lead's phone number, exactly 10 digits.
`name`	string	No	Lead name, up to 200 characters. 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. Defaults to the user the token belongs 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. Required unless `sourceName` is sent.
`priorityId`	integer	No	Picklist option id for the lead priority.
`statusName`	string	No	Alternative to `statusId`: the option's label or value (case-insensitive), 1–100 characters.
`sourceName`	string	No	Alternative to `sourceId`: the option's label or value (case-insensitive), 1–100 characters.
`priorityName`	string	No	Alternative to `priorityId`: the option's label or value (case-insensitive), 1–100 characters.
`boardOrder`	number	No	Position within the Kanban column.
`customFields`	object	No	`{ key: value }` for custom fields defined on the workspace. Values are validated against the workspace's field definitions.

Request

curl -X POST https://nextgenpanelstaging.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": 210,
  "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" },
  "collaborators": []
}

201 — example response

Errors

Status	Type	When
400	`SOURCE_REQUIRED`	Neither `sourceId` nor `sourceName` was given.
400	`INVALID_PICKLIST_OPTION`	A status, source or priority id or name is not an active option in this workspace.
400	`AMBIGUOUS_PICKLIST_OPTION`	A `statusName`, `sourceName` or `priorityName` matches more than one option.
400	`INVALID_AGENT`	`assignedAgentId` does not match a known user.
400	`INVALID_CONTACT`	`contactId` does not match a contact in this workspace.
403	`forbidden`	The token's user has no permission to create leads in this workspace, or the account has no CRM licence.
404	`not-found`	The workspace does not exist, is deleted, or belongs to another account.
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.