Reference Codes API¶

Search and validate standard healthcare reference codes (ICD-10, HCPCS, etc.).

Overview¶

The Reference Codes API provides access to a comprehensive database of healthcare codes, including ICD-10-CM (Diagnosis), ICD-10-PCS (Procedure), HCPCS/CPT, and various billing codes (Revenue, Value, Condition, etc.).

Base Path: /api/v1/reference-codes

Authentication: Required for all endpoints (Bearer token)

Code Types¶

The type parameter used in many endpoints corresponds to the following code categories:

Value	Type	Description
0	HCPCS	CPT or HCPCS codes
1	DX	ICD-10 Diagnosis codes (ICD-10-CM)
2	PCS	ICD-10 Procedure codes (ICD-10-PCS)
3	REV	Revenue codes
4	VAL	Value codes
5	COND	Condition codes
6	OCCUR	Occurrence codes
7	SPAN	Occurrence span codes
8	MOD	Modifier codes

Endpoints¶

List Codes¶

Retrieve a list of reference codes with pagination and filtering.

Endpoint: GET /reference-codes/

Query Parameters:

Parameter	Type	Required	Description
`type`	integer	No	Filter by code type (see table above)
`active_only`	boolean	No	Only return active codes (default: true)
`skip`	integer	No	Number of records to skip (default: 0)
`limit`	integer	No	Maximum records to return (default: 100, max: 1000)

Response:

{
  "data": [
    {
      "type": 1,
      "code": "I10",
      "description": "Essential (primary) hypertension",
      "start_date": 20161001,
      "end_date": 21991231
    }
  ],
  "count": 15000
}

Search Codes¶

Search for codes by value or description.

Endpoint: GET /reference-codes/search

Query Parameters:

Parameter	Type	Required	Description
`q`	string	Yes	Search query (min length 1)
`type`	integer	No	Code type (default: 1 [DX])
`active_only`	boolean	No	Only return active codes (default: true)
`date`	date	No	Check validity for specific date (YYYY-MM-DD)
`limit`	integer	No	Maximum results (default: 20, max: 100)

Response:

Returns a list of matching codes ordered by relevance.

Get Code¶

Retrieve a specific reference code.

Endpoint: GET /reference-codes/{code}

Path Parameters:

Parameter	Type	Required	Description
`code`	string	Yes	The code value (e.g., "I10")

Query Parameters:

Parameter	Type	Required	Description
`type`	integer	No	Code type (default: 1 [DX])
`date`	date	No	Check validity for specific date

Response:

Returns the single reference code object.

Validate Codes¶

Validate multiple codes in a single request.

Endpoint: POST /reference-codes/validate

Request Body:

{
  "codes": ["I10", "INVALID"],
  "type": 1,
  "date": "2024-01-01"
}

Response:

Returns a dictionary keyed by code value with validation status.

{
  "I10": {
    "is_valid": true,
    "is_active": true,
    "description": "Essential (primary) hypertension",
    "error": null,
    "start_date": 20161001,
    "end_date": 21991231
  },
  "INVALID": {
    "is_valid": false,
    "is_active": null,
    "description": null,
    "error": "Code not found",
    "start_date": null,
    "end_date": null
  }
}

Bulk Retrieve Codes¶

Retrieve details for multiple codes at once.

Endpoint: POST /reference-codes/bulk

Request Body:

{
  "codes": ["I10", "E11.9"],
  "type": 1,
  "date": "2024-01-01"
}

Response:

Returns a list of found reference code objects.