Get Lead

Look up a single lead by phone number. Returns the lead's profile fields along with its labels, lead stage, lead group, and assignee user.

The phone query parameter can be any phone number associated with the lead — primary or secondary. The lookup matches against the lead's full phone list.

Authentication Required

Requires the x-api-key header. See Overview for details.

HTTP Request

GET /enterprise/api/lead

Query Parameters

Parameter	Type	Required	Description
phone	string	Yes	Any phone number on the lead, in E.164 format.

Try it

Loading playground…

Code Examples

cURL

curl -X GET "https://prod-api.superfone.co.in/superfone/enterprise/api/lead?phone=%2B918000000001" \
  -H "x-api-key: your_api_key_here"

JavaScript

const url = new URL(
  'https://prod-api.superfone.co.in/superfone/enterprise/api/lead'
);
url.searchParams.set('phone', '+918000000001');

const response = await fetch(url, {
  method: 'GET',
  headers: { 'x-api-key': process.env.SF_API_KEY }
});

const result = await response.json();
console.log(result.data);

TypeScript

interface Lead {
  id: number;
  org_id: number;
  first_name: string | null;
  last_name: string | null;
  email: string[] | null;
  website: string | null;
  business_name: string | null;
  additional_info: string | null;
  city: string | null;
  deal_value: number | null;
  status: string | null;
  source: string | null;
  source_type: string | null;
  address: {
    text: string | null;
    additional: string | null;
    initials: string | null;
    latitude: number | null;
    longitude: number | null;
  };
  assignee_user_id: number | null;
  lead_stage_id: number | null;
  lead_group_id: number | null;
  created_at: string;
  updated_at: string | null;
  phones: Array<{ phone: string; customer_id: number }>;
  labels: Array<{
    id: number;
    title: string;
    colour: string;
    text_colour: string;
    status: string;
  }>;
  lead_stage: {
    id: number;
    title: string;
    org_id: number;
    status: string;
    type: string | null;
    position: number | null;
  } | null;
  lead_group: {
    id: number;
    title: string;
    org_id: number;
    status: string;
    type: string | null;
  } | null;
  assignee_user: {
    id: number;
    first_name: string | null;
    last_name: string | null;
  } | null;
}

interface ApiResponse<T> {
  data: T;
  message: string;
}

async function getLead(phone: string): Promise<Lead> {
  const url = new URL(
    'https://prod-api.superfone.co.in/superfone/enterprise/api/lead'
  );
  url.searchParams.set('phone', phone);

  const response = await fetch(url, {
    method: 'GET',
    headers: { 'x-api-key': process.env.SF_API_KEY! }
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.message);
  }

  const result: ApiResponse<Lead> = await response.json();
  return result.data;
}

Python

import os
import requests

url = 'https://prod-api.superfone.co.in/superfone/enterprise/api/lead'
headers = {'x-api-key': os.environ['SF_API_KEY']}
params = {'phone': '+918000000001'}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
print(response.json()['data'])

Success Response

Status Code: 200 OK

{
  "data": {
    "id": 12345,
    "org_id": 42,
    "first_name": "Asha",
    "last_name": "Kumar",
    "email": ["asha@example.com"],
    "website": null,
    "business_name": "Acme Pvt Ltd",
    "additional_info": null,
    "city": "Bengaluru",
    "deal_value": 50000,
    "status": "ACTIVE",
    "source": "website-form",
    "source_type": "OTHERS",
    "address": {
      "text": null,
      "additional": null,
      "initials": null,
      "latitude": null,
      "longitude": null
    },
    "assignee_user_id": 678,
    "lead_stage_id": 9,
    "lead_group_id": 3,
    "created_at": "2026-04-01T10:30:00.000Z",
    "updated_at": "2026-05-12T08:15:00.000Z",
    "phones": [
      { "phone": "+918000000001", "customer_id": 12345 },
      { "phone": "+918000000002", "customer_id": 12345 }
    ],
    "labels": [
      {
        "id": 17,
        "title": "Hot",
        "colour": "#ff5722",
        "text_colour": "#ffffff",
        "status": "ACTIVE"
      }
    ],
    "lead_stage": {
      "id": 9,
      "title": "New Lead",
      "org_id": 42,
      "status": "ACTIVE",
      "type": "INITIAL",
      "position": 1
    },
    "lead_group": {
      "id": 3,
      "title": "Inbound",
      "org_id": 42,
      "status": "ACTIVE",
      "type": null
    },
    "assignee_user": {
      "id": 678,
      "first_name": "Ravi",
      "last_name": "Patel"
    }
  },
  "message": "success"
}

Response Fields

Field	Type	Description
id	number	Internal lead ID
org_id	number	Account that owns the lead
first_name	string | null	First name
last_name	string | null	Last name
email	string[] | null	Email addresses
website	string | null	Website
business_name	string | null	Business / company name
additional_info	string | null	Free-form notes
city	string | null	City
deal_value	number | null	Estimated deal value
status	string | null	Lead status (typically ACTIVE)
source	string | null	Free-form source string
source_type	string | null	One of the predefined source types
address	object	Address object (see upsert-lead)
assignee_user_id	number | null	ID of assigned team member
lead_stage_id	number | null	ID of attached lead stage
lead_group_id	number | null	ID of attached lead group
phones	object[]	All phone numbers belonging to the lead
labels	object[]	Labels attached to the lead
lead_stage	object | null	Expanded lead stage object
lead_group	object | null	Expanded lead group object
assignee_user	object | null	Expanded assignee with id, first_name, last_name
created_at	string	ISO 8601 timestamp
updated_at	string | null	ISO 8601 timestamp of last update

Error Responses

Status	Message	When it occurs
400	Phone query parameter is required	phone missing from query string
400	Invalid phone number	phone is not a valid E.164 number
401	UnAuthorized, Please Provide Valid API Key	Missing or invalid x-api-key
404	Customer not found	No lead in your account has this phone number

Example error

{
  "message": "Customer not found"
}

Related Endpoints

• Create or Update Lead — Write side of this endpoint