📌 Create Leads API

This endpoint allows you to create multiple leads for your organization in a single API call.
You can send a maximum of 100 leads per request.

🔐 Authentication: Requires an API key in the request headers.

🔗 Endpoint

POST /api/leads

📥 Request

Headers

x-api-key (string, required) - Your API key for authentication.

Request Body

The request must contain a JSON array of lead objects, following the schema below:

📌 Lead Schema

Field	Type	Max Length	Required	Description
`firstName`	string	100	optional	The first name of the lead.
`lastName`	string	100	optional	The last name of the lead.
`email`	string	100	optional	The email address of the lead, must follow proper email format.
`phone`	string	50	optional	The phone number of the lead.
`companyName`	string	100	optional	The name of the company the lead works for.
`companyWebsite`	string	150	optional	The website URL of the company, must be in URL format.
`jobTitle`	string	100	optional	The job title of the lead.
`address`	string	200	optional	The address of the lead’s company.
`state`	string	100	optional	The state or region of the lead’s company.
`country`	string	50	optional	The country where the lead’s company is located.
`industry`	string	100	optional	The industry the lead’s company operates in.
`companySize`	string	10	optional	The size of the lead’s company, for example “50-100”, or “1000+”.
`annualRevenue`	string	20	optional	The annual revenue of the lead’s company, formatted as a string.
`source`	string	50	optional	The source of the lead, default is `USER_API`. This field is auto-filled if not provided.
`linkedinUrl`	string	100	optional	The LinkedIn URL of the lead.

Validation Rules

At least one of email or phone must be provided.
The request must include between 1 and 100 leads.

Example Request Body


json
[
  {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "1234567890",
    "companyName": "Tech Co",
    "companyWebsite": "https://techco.com",
    "jobTitle": "Engineer",
    "address": "123 Main St",
    "state": "California",
    "country": "USA",
    "industry": "Technology",
    "companySize": "50-100",
    "annualRevenue": "$1M",
    "source": "USER_API",
    "linkedinUrl": "https://linkedin.com/in/johndoe"
  }
]

📤 Response

✅ Success Response

Status Code: 201 Created


json
{
  "message": "Successfully created leads",
  "duplicates": <number>,
  "created": <number>
}

duplicates: The number of duplicate leads that were skipped.
created: The number of new leads successfully created.

❌ Error Responses

🔑 Invalid or Missing API Key

Status Code: 401 Unauthorized


json
{
  "message": "Invalid or Missing API Key"
}

⚠️ Validation Errors

Status Code: 400 Bad Request


json
{
  "message": ["fieldName: error message"]
}

📌 Maximum Leads Limit Exceeded

Status Code: 400 Bad Request


json
{
  "message": "You have reached the maximum number of leads allowed for your organization. You can create <number> more leads."
}

🔄 Other Errors

Status Code: 500 Internal Server Error


json
{
  "message": "Something went wrong"
}

📌 Notes

API Key Validation: You must pass your API key in the x-api-key header. Ensure the key is valid and has sufficient permissions.
Lead Count Management: The number of leads you can create depends on your organization’s subscription limits. The API enforces these limits automatically.
Skipped or Duplicated Fields: If there are duplicate fields in the request, the API will skip them and only add unique values. It will also increase the usage count for only unique fields.
Error Handling: Detailed error messages are provided to help you correct validation issues or unexpected input.

📌 Example cURL Request


bash
curl -X POST /api/leads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com"
    }
  ]'