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

# Leads

## Create or update leads in bulk

> Creates or updates multiple leads. If a lead with the same email already exists, it will be updated. Optionally associate leads with a campaign.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.CreateLeadsResponse":{"type":"object","properties":{"count":{"type":"integer"},"message":{"type":"string"}}},"models.ErrorInvalidRequest":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorCampaignNotFound":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorFailedToCreateLeads":{"type":"object","properties":{"error":{"type":"string"}}},"models.CreateOrUpdateLeadsRequest":{"type":"object","required":["leads"],"properties":{"campaignId":{"type":"integer"},"leads":{"type":"array","maxItems":1000,"minItems":1,"items":{"$ref":"#/components/schemas/models.LeadInput"}}}},"models.LeadInput":{"type":"object","required":["email"],"properties":{"company":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"linkedin":{"type":"string"},"phone":{"type":"string"},"title":{"type":"string"},"website":{"type":"string"}}}}},"paths":{"/leads":{"post":{"description":"Creates or updates multiple leads. If a lead with the same email already exists, it will be updated. Optionally associate leads with a campaign.","tags":["Leads"],"summary":"Create or update leads in bulk","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true}],"responses":{"201":{"description":"Leads processed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateLeadsResponse"}}}},"400":{"description":"Invalid request body or no leads provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorInvalidRequest"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"Campaign not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorCampaignNotFound"}}}},"500":{"description":"Failed to create leads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorFailedToCreateLeads"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateOrUpdateLeadsRequest"}}},"description":"Leads to create or update","required":true}}}}}
```

## Get a lead by ID

> Retrieves detailed information about a specific lead.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.GetLeadResponse":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/models.LeadResponse"}}},"models.LeadResponse":{"type":"object","properties":{"company":{"type":"string"},"createdAt":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"id":{"type":"integer"},"lastName":{"type":"string"},"linkedin":{"type":"string"},"phone":{"type":"string"},"title":{"type":"string"},"updatedAt":{"type":"string"},"website":{"type":"string"}}},"models.ErrorInvalidLeadID":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorForbidden":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorNotFound":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/leads/{id}":{"get":{"description":"Retrieves detailed information about a specific lead.","tags":["Leads"],"summary":"Get a lead by ID","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Lead ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"Lead details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.GetLeadResponse"}}}},"400":{"description":"Invalid lead ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorInvalidLeadID"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Forbidden - lead does not belong to your space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorForbidden"}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorNotFound"}}}}}}}}}
```

## Update a lead by ID

> Updates an existing lead's information. Only provided fields will be updated.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.UpdateLeadResponse":{"type":"object","properties":{"lead":{"$ref":"#/components/schemas/models.LeadResponse"},"message":{"type":"string"}}},"models.LeadResponse":{"type":"object","properties":{"company":{"type":"string"},"createdAt":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"id":{"type":"integer"},"lastName":{"type":"string"},"linkedin":{"type":"string"},"phone":{"type":"string"},"title":{"type":"string"},"updatedAt":{"type":"string"},"website":{"type":"string"}}},"models.ErrorInvalidLeadID":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorForbidden":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorNotFound":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorFailedToUpdateLead":{"type":"object","properties":{"error":{"type":"string"}}},"models.UpdateLeadRequest":{"type":"object","properties":{"company":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"linkedin":{"type":"string"},"phone":{"type":"string"},"title":{"type":"string"},"website":{"type":"string"}}}}},"paths":{"/leads/{id}":{"put":{"description":"Updates an existing lead's information. Only provided fields will be updated.","tags":["Leads"],"summary":"Update a lead by ID","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Lead ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"Lead updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.UpdateLeadResponse"}}}},"400":{"description":"Invalid lead ID or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorInvalidLeadID"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Forbidden - lead does not belong to your space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorForbidden"}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorNotFound"}}}},"500":{"description":"Failed to update lead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorFailedToUpdateLead"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.UpdateLeadRequest"}}},"description":"Lead fields to update","required":true}}}}}
```

## Delete a lead by ID

> Deletes a lead and all associated unsent emails. If the lead is associated with campaigns, it will be removed from those campaigns first.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.DeleteLeadResponse":{"type":"object","properties":{"id":{"type":"integer"},"message":{"type":"string"}}},"models.ErrorInvalidLeadID":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorForbidden":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorNotFound":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorFailedToDeleteLead":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/leads/{id}":{"delete":{"description":"Deletes a lead and all associated unsent emails. If the lead is associated with campaigns, it will be removed from those campaigns first.","tags":["Leads"],"summary":"Delete a lead by ID","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Lead ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"Lead deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.DeleteLeadResponse"}}}},"400":{"description":"Invalid lead ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorInvalidLeadID"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Forbidden - lead does not belong to your space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorForbidden"}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorNotFound"}}}},"500":{"description":"Failed to delete lead","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorFailedToDeleteLead"}}}}}}}}}
```