> For the complete documentation index, see [llms.txt](https://docs.saleschat.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saleschat.pro/api-documentation/leads.md).

# Leads

## Create a new lead for the specified organization

> Creates a new lead with the provided details. The request must include either a valid bearer token or an x-org-api-key for authentication. The response will contain the details of the created lead.

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://apis.saleschat.pro"}],"security":[{"bearer-key":[]},{}],"components":{"securitySchemes":{"bearer-key":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CreateLeadV4Request":{"required":["attributes","crm_id","first_name","phone_number"],"type":"object","properties":{"crm_id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"object"}},"phone_number":{"type":"string"},"opt_in_date":{"type":"integer","format":"int64"}}},"CreateLeadV4Response":{"type":"object","properties":{"lead_id":{"type":"string"},"crm_id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"object"}},"phone_number":{"type":"string"},"opt_in_date":{"type":"integer","format":"int64"}}},"ErrorRespDto":{"type":"object","properties":{"error_code":{"type":"integer"},"error_message":{"type":"string"},"error_description":{"type":"string"},"payload":{"type":"object"}}}}},"paths":{"/v4/orgs/{orgId}/leads":{"post":{"tags":["Leads"],"summary":"Create a new lead for the specified organization","description":"Creates a new lead with the provided details. The request must include either a valid bearer token or an x-org-api-key for authentication. The response will contain the details of the created lead.","operationId":"createLead","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLeadV4Request"}}},"required":true},"responses":{"200":{"description":"Successfully created lead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLeadV4Response"}}}},"401":{"description":"Unauthorized - Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"403":{"description":"Forbidden - You don't have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"404":{"description":"Org not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"422":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"429":{"description":"Lead with this crm_id already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"500":{"description":"Failed to create lead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}}}}}}}
```

## Assign a lead to a user

> Assigns the specified lead to a user. The request must include either a valid bearer token or an x-org-api-key for authentication. The request body should contain either the ID or the email of the user to assign the lead to.

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://apis.saleschat.pro"}],"security":[{"bearer-key":[]},{}],"components":{"securitySchemes":{"bearer-key":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"AssignLeadRequest":{"type":"object","properties":{"user_id":{"type":"string"},"user_email":{"type":"string"}}},"ErrorRespDto":{"type":"object","properties":{"error_code":{"type":"integer"},"error_message":{"type":"string"},"error_description":{"type":"string"},"payload":{"type":"object"}}}}},"paths":{"/v4/orgs/{orgId}/leads/{leadId}/assign":{"put":{"tags":["Leads"],"summary":"Assign a lead to a user","description":"Assigns the specified lead to a user. The request must include either a valid bearer token or an x-org-api-key for authentication. The request body should contain either the ID or the email of the user to assign the lead to.","operationId":"assign","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"leadId","in":"path","description":"Saleschat-generated lead ID (UUID) or the lead's CRM ID — both are resolved.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignLeadRequest"}}},"required":true},"responses":{"202":{"description":"Successfully assigned lead"},"401":{"description":"Unauthorized - Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"403":{"description":"Forbidden - You don't have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"404":{"description":"Org or lead not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"422":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"500":{"description":"Failed to assign lead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}}}}}}}
```

## Add an event for a lead

> Records a custom event for the specified lead. If the event type matches a known automation trigger it will be enqueued for processing. Uses distinct\_id for idempotency — duplicate requests with the same distinct\_id are silently accepted.

```json
{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://apis.saleschat.pro"}],"security":[{"bearer-key":[]},{}],"components":{"securitySchemes":{"bearer-key":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CreateLeadEventRequest":{"required":["event"],"type":"object","properties":{"distinct_id":{"maxLength":36,"minLength":0,"type":"string"},"event":{"maxLength":256,"minLength":0,"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"object"}}}},"ErrorRespDto":{"type":"object","properties":{"error_code":{"type":"integer"},"error_message":{"type":"string"},"error_description":{"type":"string"},"payload":{"type":"object"}}}}},"paths":{"/v4/orgs/{orgId}/leads/{leadId}/events":{"put":{"tags":["Leads"],"summary":"Add an event for a lead","description":"Records a custom event for the specified lead. If the event type matches a known automation trigger it will be enqueued for processing. Uses distinct_id for idempotency — duplicate requests with the same distinct_id are silently accepted.","operationId":"createLeadEvent","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"leadId","in":"path","description":"Saleschat-generated lead ID (UUID) or the lead's CRM ID — both are resolved.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLeadEventRequest"}}},"required":true},"responses":{"202":{"description":"Event accepted"},"401":{"description":"Unauthorized - Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"403":{"description":"Forbidden - You don't have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"404":{"description":"Org or lead not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"422":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}},"500":{"description":"Failed to process event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorRespDto"}}}}}}}}}
```