Get Lead Information

Endpoint

POST /engage/v1/leads

Authentication

Every request must include a business access token in one of the following headers. If both headers are sent, Authorization is used.

• Tokens are scoped to the business, so only leads belonging to that business can be retrieved.
• A missing, invalid, or expired token returns 401 Unauthorized.
• Keep the token secret and rotate it immediately if it may have been exposed.

Request

Headers

Body

Send exactly one lookup value. lead_id takes effect if both values are sent; contact_number is ignored in that case.

POST /engage/v1/leads HTTP/1.1
Host: client-api.e-so.in
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "lead_id": 1234
}

Responses

Success — 200 OK

{
  "status": 200,
  "success": true,
  "message": "success.",
  "payload": {
    "id": 1234,
    "phone_number": "+919876543210",
    "country_code": 91,
    "source": "whatsapp",
    "name": "Example Lead",
    "auto_reminder": "ENABLED",
    "created_at": "2024-05-20T10:30:00.000Z",
    "opt_in": true,
    "updated_at": "2024-05-21T08:00:00.000Z",
    "origin": "api",
    "assign_user": {
      "name": "Example Owner",
      "email": "owner@example.com"
    },
    "journey": ["new_lead", "qualified"],
    "last_message_at": "2024-05-21T09:15:00.000Z",
    "lead_data": {
      "city": "Example City",
      "email": "lead@example.com",
      "custom_field": "value"
    }
  }
}

Error responses

Behavior

Code examples

cURL

# By lead ID
curl -X POST "https://client-api.e-so.in/engage/v1/leads" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lead_id": 1234}'

# By contact number
curl -X POST "https://client-api.e-so.in/engage/v1/leads" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contact_number": 919876543210}'

JavaScript — fetch

async function getLead({ leadId, contactNumber }) {
  const body = leadId
    ? { lead_id: leadId }
    : { contact_number: contactNumber };

  const response = await fetch("https://client-api.e-so.in/engage/v1/leads", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const data = await response.json();
  if (!response.ok) throw new Error(`${data.status}: ${data.message}`);
  return data.payload;
}

const lead = await getLead({ leadId: 1234 });
console.log(lead.name, lead.assign_user);

Python — requests

import requests

url = "https://client-api.e-so.in/engage/v1/leads"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
response = requests.post(url, json={"lead_id": 1234}, headers=headers)

if response.status_code == 200:
    lead = response.json()["payload"]
    print(lead["name"], lead["assign_user"])
else:
    print(f"Error {response.status_code}: {response.text}")

Related endpoints

Support

If an integration issue continues, contact EasySocial Support and include the request payload, response status and message, and the UTC timestamp. Never include the access-token value.