List Labels

Search and paginate through your account's labels. Use this to discover the label names you need to pass to add_labels or remove_labels in the upsert-lead request.

List-only via API

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

Authentication Required

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

HTTP Request

GET /enterprise/api/label

Query Parameters

Parameter	Type	Required	Default	Description
text	string	No	—	Case-insensitive substring filter on the label 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/label?text=hot&page=1&page_size=20" \
  -H "x-api-key: your_api_key_here"

JavaScript

const url = new URL(
  'https://prod-api.superfone.co.in/superfone/enterprise/api/label'
);
url.searchParams.set('text', 'hot');
url.searchParams.set('page', '1');
url.searchParams.set('page_size', '20');

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/label',
    headers={'x-api-key': os.environ['SF_API_KEY']},
    params={'text': 'hot', 'page': 1, 'page_size': 20}
)
print(response.json()['data'])

Success Response

Status Code: 200 OK

{
  "data": {
    "rows": [
      {
        "id": 17,
        "org_id": 42,
        "title": "Hot",
        "colour": "#ff5722",
        "text_colour": "#ffffff",
        "status": "ACTIVE",
        "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": 20,
    "total_items": 1
  },
  "message": "success"
}

Response Fields

Field	Type	Description
data.rows[].id	number	Internal label ID
data.rows[].title	string	Label name — this is the value to pass in add_labels / remove_labels
data.rows[].colour	string	Background colour (hex)
data.rows[].text_colour	string	Text colour (hex)
data.rows[].status	string	ACTIVE or DISABLED
data.rows[].created_by	number | null	User ID who created the label
data.rows[].updated_by	number | null	User ID who last updated the label
data.rows[].created_at	string	ISO 8601 timestamp
data.rows[].updated_at	string	ISO 8601 timestamp
data.total_pages	number	Total pages available
data.current_page	number	Page number returned
data.page_size	number	Items per page
data.total_items	number	Total matching labels across all pages

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 values in add_labels / remove_labels