Creates multiple leads in a single request. Duplicates (contact numbers already existing for the business) are silently ignored.

POST

https://client-api.e-so.in/api/v1/leads/bulk-create

AUTHORIZATION

Required

- Bearer Token in the Authorization header

Header Format Examples:

Authorization: Bearer <access_token>;

Error States:

• 401 Unauthorized: Missing, expired or invalid token.

• Error Response Example:

  {
    "status": 401,
    "message": "UnAuthorized Access-Token!",
    "success": false
  }

Note - Only one of the headers is required. If both are present, Authorization is preferred.

Request Specifications

Headers

Body

{
    "data": [
        {
            "contact-easysocial-whatsapp-api-support_number": 1234567890,
            "country_code": 91,
            "contact_number": "8192829284",
            "origin": "UPLOAD",
            "name": "Patel"
        }
    ]
}

EXAMPLE REQUEST

curl --request POST \
  --url 'https://client-api.e-so.in/api/v1/leads/bulk-create' \
  --header 'User-Agent: DocumentorRuntime/1.0' \
  --header 'Accept: */*' \
  --header 'Accept-Encoding: gzip, deflate, br' \
  --header 'Connection: keep-alive' \
  --header 'Cache-Control: no-cache' \
  --header 'X-Request-Token: 5d2f4549-d3bc-4d4e-8154-2cb55a7e41ca' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": [
        {
            "contact-easysocial-whatsapp-api-support_number": 1234567890,
            "country_code": 91,
"contact_number": "8272828749",
            "origin": "UPLOAD",
            "name": "Patel Testing docs"
        }
    ]
}'

EXAMPLE RESPONSE

{
  "status": 201,
  "success": true,
  "message": "New Contacts successfully added!"
}

Body Parameters

Validation Rules

• Maximum 500 leads per request
• Duplicate contact number values within a request are deduplicated (first occurrence kept)
• Additional fields beyond origin, contact number, and country_code must be primitive types (boolean, string, or number)

Error Responses

400 Bad Request - Validation Error

{
  "error": "VALIDATION_ERROR",
  "message": "contact number required validation failed"
}

417 Expectation Failed - Invalid Field Types

{
  "error": "VALIDATION_ERROR",
  "message": "Boolean, String and Number fields are supported!"
}

429 Too Many Requests - Rate Limit Exceeded

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Many frequent requests, rate limit exceeded. Please try again later."
}

Behavior Notes

1. Duplicate Handling: If a contact number already exists for the business, it is silently ignored (no error thrown)
2. Automatic Deduplication: Within the request, if the same contact number appears multiple times, only the first occurrence is processed
3. Platform Assignment: All leads are automatically assigned to the WhatsApp platform for the business
4. Field Normalization: All custom field keys are converted to lowercase

Related Endpoints