> 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"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.saleschat.pro/api-documentation/leads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.