Customer Management

The Customer Management endpoints let you create, update, and look up CRM leads (contacts) in your Superfone account, and read the configuration data — labels, lead stages, lead groups, products, and source types — that you can attach to those leads.

These endpoints are part of the Enterprise API and are intended for server-to-server operations.

Authentication Required

All endpoints require an x-api-key header. Contact the Superfone team at hello@superfone.in to provision a key.

Base URL

All requests are made to:

https://prod-api.superfone.co.in/superfone

For example, the upsert-lead endpoint is:

POST https://prod-api.superfone.co.in/superfone/enterprise/api/lead

Authentication

Every request must include the x-api-key header:

x-api-key: your_api_key_here

A missing or invalid key returns 401 Unauthorized:

{
  "message": "UnAuthorized, Please Provide Valid API Key"
}

Response Format

All responses use the standard envelope.

Success:

{
  "data": {
    /* ... */
  },
  "message": "success"
}

Error:

{
  "message": "Customer phone is required to identify the record to update"
}

Endpoints

Leads

Method	Path	Description
POST	/enterprise/api/lead	Create or update a lead by primary phone number
GET	/enterprise/api/lead	Get a lead by phone number

Tasks

Method	Path	Description
POST	/enterprise/api/lead/:lead_id/task	Create a task against a lead
POST	/enterprise/api/lead/:lead_id/task/complete	Mark the open task complete
GET	/enterprise/api/lead/:lead_id/task	List tasks for a lead (paginated)

Configuration lookups

These endpoints return the catalog of values you can attach to a lead. Use them to discover the names you need to pass when calling the upsert endpoint (lead_stage_name, lead_group_name, add_labels, add_products, source_type).

Method	Path	Description
GET	/enterprise/api/source-type	List source types
GET	/enterprise/api/label	Search labels
GET	/enterprise/api/lead-stage	Search lead stages
GET	/enterprise/api/lead-group	Search lead groups
GET	/enterprise/api/product	Search products

Conventions

Phone number format

All phone numbers must be in E.164 format (international, with + prefix and no spaces or dashes).

Valid: +918000000001, +14155552671

Invalid: 8000000001, +91 80000 00001, +91-8000000001

Identifying a lead

The Enterprise API identifies a lead by its primary phone number (customer_phone), not by an internal ID. This makes it easy to integrate from systems that only know about the customer by phone.

If multiple leads share the same primary phone (a state that should not normally exist), the upsert endpoint returns 400 Customer phone exists in multiple contact rather than picking one arbitrarily.

Names instead of IDs

When attaching a lead stage, lead group, label, or product to a lead, you pass the name (lead_stage_name, add_labels, etc.), not an internal ID. Names are matched exactly against your account's catalog.

If a referenced name doesn't exist:

• lead_stage_name, lead_group_name — the request returns 404.
• add_labels, remove_labels, add_products — the unknown names are silently ignored, and only matching items are applied.

If multiple stages or groups share the same name, you'll get 400 Multiple lead stages found with this name. Provide unique — make sure your catalog uses unique names.

Pagination on list endpoints

The configuration list endpoints (/label, /lead-stage, /lead-group, /product) support pagination via query parameters:

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

The response shape is:

{
  "data": {
    "rows": [
      /* ... */
    ],
    "total_pages": 3,
    "current_page": 1,
    "page_size": 50,
    "total_items": 142
  },
  "message": "success"
}

HTTP Status Codes

Status	Meaning
200 OK	Request succeeded
400 Bad Request	Validation failed or required fields missing
401 Unauthorized	Missing or invalid API key
404 Not Found	Lead, lead stage, or lead group not found
500 Internal Server Error	Unexpected server error