Phone to Udyam Comprehensive API

Introduction

The Phone to Udyam PAN Details API (POST api/v3/phoneToUdyamComprehensive) provides a single, unified endpoint to fetch all Udyam registration profiles associated with a given mobile phone number, automatically enriched with the Enterprise Permanent Account Number (PAN) for each registration.

This endpoint builds on the existing Phone-to-Udyam flow and adds automated parallel PAN resolution per (phone, Udyam) pair using the VehicleInfo vendor.

Key Capabilities & Highlights

End-to-End Enterprise Identification: Translates a single 10-digit mobile number into all associated MSME Udyam registrations and their corresponding PANs.

Parallel PAN lookup: Resolves PANs concurrently across multiple Udyam entries to minimize overall latency.

API Specification

Endpoint Details

HTTP Method: POST

Path: api/v3/phoneToUdyamComprehensive

Headers: Requires standard Client Authentication Key

Content-Type: application/json

Request Schema

{
  "phone": "9833545333"
}

Field Validation Rules

Field	Type	Required	Validation Pattern / Rules
phone	String	Yes	Trimmed 10-digit mobile number matching ^[0-9]{10}$

Response Schema (HTTP 200 OK)

Returns a JSON array where each element corresponds to a unique Udyam registration associated with the input phone number.

Field Definitions

Field Path	Type	Description
serialNo	Number	1-based index position in the response array.
udyamNumber	String	Format: UDYAM-XX-00-0000000 (e.g., UDYAM-DL-05-0003958).
result	Object	Full Udyam registration profile details.
result.generalInfo	Object	Enterprise metadata and general information.
result.ownerDetails	Object	Enterprise owner details.
result.enterpriseType	Array	Classification history (coerced to [] if empty upstream).
result.unitsDetails	Array	Manufacturing/service units details (coerced to [] if empty upstream).
result.nationalIndustryClassificationCodes	Array	NIC code list (coerced to [] if empty upstream).
result.panDetails.panNumber	String	The 10-character PAN string if found; otherwise sentinel value NOT_FOUND or UNAVAILABLE.
result.panDetails.status	String	PAN lookup status: FOUND, NOT_FOUND, or UNAVAILABLE.

Example Response Body

Per-Entry PAN Status Matrix (result.panDetails)

PAN resolution errors do not fail the main request. Each entry reports its own PAN resolution status:

status	panNumber Value	Description & Developer Handling
FOUND	Valid PAN (e.g. AAGCC2825A)	Vendor returned a verified PAN for the (phone, Udyam) pair. Hit is cached in Mongo.
NOT_FOUND	"NOT_FOUND"	Upstream returned 404 or empty/placeholder customer_id (e.g., "NA"). Definitive answer for current record; not cached so future hits can update.
UNAVAILABLE	"UNAVAILABLE"	Upstream vendor timeout, HTTP 429/5xx error, network failure, or input regex validation failure (UDYAM format). Retryable state.

Error Handling & Status Matrix

Request-Level Errors

If the request fails prior to retrieving Udyam details, an appropriate HTTP error status is returned:

HTTP Status	Reason Code	Condition / Description
400 Bad Request	BAD_REQUEST	Phone parameter missing, invalid format, or all phone-to-Udyam vendors returned 400.
404 Not Found	NOT_FOUND	No Udyam registrations found for input phone, or details failed for all Udyams with at least one 404 response.
409 Conflict	UPSTREAM_ERROR	Upstream vendor timeout, network failure, or detail extraction failed for all Udyams without any 404.