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


---

# Agent Instructions: 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://run.emailchaser.com/api-reference/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.