List Lead Stages

Search and paginate through your account's lead stages. Use this to discover the stage names you need to pass to lead_stage_name in the upsert-lead request.

List-only via API

Only listing lead stages is supported via API. To create, edit, or delete lead stages, use the Superfone dashboard.

Authentication Required

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

HTTP Request

GET /enterprise/api/lead-stage

Query Parameters

Parameter	Type	Required	Default	Description
text	string	No	—	Case-insensitive substring filter on the stage title
page	number	No	1	Page number — starts at 1, not 0
page_size	number	No	50	Items per page

Try it

Loading playground…

Code Examples

cURL

curl -X GET "https://prod-api.superfone.co.in/superfone/enterprise/api/lead-stage?page=1&page_size=50" \
  -H "x-api-key: your_api_key_here"

JavaScript

const url = new URL(
  'https://prod-api.superfone.co.in/superfone/enterprise/api/lead-stage'
);
url.searchParams.set('page', '1');
url.searchParams.set('page_size', '50');

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.rows);

Python

import os
import requests

response = requests.get(
    'https://prod-api.superfone.co.in/superfone/enterprise/api/lead-stage',
    headers={'x-api-key': os.environ['SF_API_KEY']},
    params={'page': 1, 'page_size': 50}
)
print(response.json()['data'])

Success Response

Status Code: 200 OK

{
  "data": {
    "rows": [
      {
        "id": 9,
        "org_id": 42,
        "title": "New Lead",
        "status": "ACTIVE",
        "type": "INITIAL",
        "position": 1,
        "is_editable": true,
        "identifier": null,
        "created_by": 678,
        "updated_by": null,
        "created_at": "2026-01-15T09:00:00.000Z",
        "updated_at": "2026-01-15T09:00:00.000Z"
      },
      {
        "id": 10,
        "org_id": 42,
        "title": "Qualified",
        "status": "ACTIVE",
        "type": "NONE",
        "position": 2,
        "is_editable": true,
        "identifier": null,
        "created_by": 678,
        "updated_by": null,
        "created_at": "2026-01-15T09:00:00.000Z",
        "updated_at": "2026-01-15T09:00:00.000Z"
      }
    ],
    "total_pages": 1,
    "current_page": 1,
    "page_size": 50,
    "total_items": 2
  },
  "message": "success"
}

Response Fields

Field	Type	Description
data.rows[].id	number	Internal lead stage ID
data.rows[].title	string	Stage name — this is the value to pass as lead_stage_name
data.rows[].status	string	ACTIVE or DISABLED
data.rows[].type	string	One of INITIAL, FINAL_POSITIVE, FINAL_NEGATIVE, NONE
data.rows[].position	number | null	Display order in the pipeline
data.rows[].is_editable	boolean	Whether this stage can be edited (system stages are not editable)
data.rows[].identifier	string | null	Internal identifier for system stages (e.g. AI receptionist stages)
data.rows[].created_at	string	ISO 8601 timestamp
data.rows[].updated_at	string	ISO 8601 timestamp

Stage names must be unique to be used in upsert

Create or Update Lead matches stages by name. If two stages share a title, the upsert call returns 400 Multiple lead stages found with this name. Provide unique — keep names unique in your pipeline.

Error Responses

Status	Message	When it occurs
401	UnAuthorized, Please Provide Valid API Key	Missing or invalid x-api-key

Related Endpoints

• Create or Update Lead — Pass the returned title value as lead_stage_name