'Add Leads' API Documentation

The Add Leads API lets customers send leads into Convin Sense campaigns in real-time, while attaching custom data for better segmentation and reporting. It also ensures data integrity through strict authentication and validation rules.

Base URL: https://{orgId}.convin.ai/

Endpoint: POST /v2/lead/add

1. Authentication

All requests must include two headers for authentication:

Header	Description
`x-api-key`	API key
`x-api-token`	API token

Note: Go to Settings --> API Credentials to fetch the API Key and API Token.

Rules:

Both headers are required.
Both must belong to the same organization.
Keys must be active.
If authentication fails → 401 Unauthorized.

Example:

POST /v2/lead/add
Content-Type: application/json
x-api-key: your_api_key
x-api-token: your_api_token

2. Request Format

Method & Endpoint

POST /v2/lead/add

Body Parameters

Field	Type	Required	Description
`phone_number`	string	Yes	Valid phone number (E.164 recommended). Max 15 chars.
`name`	string	No	Lead’s name. Max 100 chars. Unicode supported.
`email`	string	No	Valid email. Max 255 chars.
`external_id`	string	No	Customer’s unique ID for deduplication. Must be unique per campaign if provided.
`custom_data`	object	No	Add arbitrary key–value pairs (up to 50 characters each) under the `custom_data` object. Convin will automatically include this data in all API responses for the corresponding lead. This helps you track and map leads with your internal systems. ⚠️ Note: Do not use reserved keys — `name`, `email`, `phone_number`, `external_id`, `campaign_id`, or `campaign_name`.
`campaign_id`	string	Conditional	Required if `campaign_name` is not present. Takes precedence if both exist.
`campaign_name`	string	Conditional	Required if `campaign_id` not provided. Case-insensitive.
Other fields	mixed	Optional	Any additional key-value pairs. Must match mapped variables configured for that campaign.

Note: Go to Campaign Settings --> Lead Ingestion Tab to find the campaign_id.

Example Request

{
  "phone_number": "+91955552671",
  "name": "Arjun Kumar",
  "email": "[email protected]",
  "external_id": "CUST-1001",
  "campaign_name": "Summer Sale",
  "custom_data": {
    "source": "facebook",
    "ad_id": "12345"
  },
  "product_interest": "Gold Plan"
}

3. Validation Rules

3.1 Org Validation

API key and token must belong to a valid organization.
Reject if mismatch → 403 Forbidden.

3.2 Campaign Validation

Must include campaign_id or campaign_name.
If both provided → system uses campaign_id.
Campaign must:
- Belong to the same org.
- Be Active or Paused.
Rejected if: Completed or does not exist.

3.3 Required Fields

phone_number must be present and valid.
Either campaign_id or campaign_name must be present.

3.4 Field Mapping Validation

All mapped fields configured for that campaign must exist in payload.
Missing fields → 422 Unprocessable Entity.

3.5 Data Type & Format Validation

Reject if type mismatch (e.g., array instead of string).
Reject empty strings for required fields.
Validate email if provided.
Validate phone number (digits only, max 15 chars).

3.6 Payload Constraints

Max payload size: 1 MB.
Oversized request → 413 Payload Too Large.

3.7 JSON Integrity

Invalid JSON → 400 Bad Request.

4. Responses

4.1 Success (200)

{
  "status": "success",
  "message": "Lead added successfully",
  "lead_id": "lead_abc123",
  "campaign_id": "cmp_456",
  "custom_data": {
    "source": "facebook",
    "ad_id": "12345"
  }
}

4.2 Error Responses

400 Bad Request – Invalid JSON

{
  "status": "error",
  "message": "Invalid JSON"
}

401 Unauthorized – Invalid credentials

{
  "status": "error",
  "message": "Invalid API key or token"
}

403 Forbidden – Org mismatch / reserved field

{
  "status": "error",
  "message": "API key and token do not belong to the same organization"
}

404 Not Found – Invalid campaign

{
  "status": "error",
  "message": "Invalid campaign_id or campaign_name"
}

413 Payload Too Large

{
  "status": "error",
  "message": "Payload exceeds 1MB limit"
}

422 Unprocessable Entity – Missing required/mapped fields

{
  "status": "error",
  "message": "Missing required field: phone_number"
}

{
  "status": "error",
  "message": "Payload missing mapped field: product_interest"
}

{
  "status": "error",
  "message": "Invalid data type for field: custom_data"
}

429 Too Many Requests

{
  "status": "error",
  "message": "Rate limit exceeded. Please try again later."
}

5. Rate Limiting

100 requests per minute per org.
Exceeding this limit → 429 Too Many Requests.