API Documentation
Reference for authenticating and integrating with the NOF1 Policy API.
Policy API
v1Programmatic access to payer coverage policies. Search by name, CPT code, payer, or LCD reference, and retrieve full policy details including coverage criteria and coding requirements.
The NOF1 Policy API gives your systems direct access to the same payer policy intelligence used in the NOF1 platform. Use it to power clinical decision support tools, automate prior authorization workflows, or build policy-aware analytics.
Authentication
All requests must include a valid API key as a Bearer token in the Authorization header. API keys are scoped to your organization and should be treated as secrets. Do not expose them in client-side code or commit them to version control.
Authorization: Bearer nof1_live_<your_api_key>
Requests without a valid token will receive a 401 response.
Base URL & Versioning
All endpoints are versioned under /v1. Breaking changes will be released under a new version prefix with advance notice.
All request and response bodies use JSON. Include Content-Type: application/json on any requests with a body.
Pagination
List endpoints return paginated results. Pass page and per_page query parameters to navigate through results. The response envelope includes a meta object with total counts.
{
"data": [ ... ],
"meta": {
"total": 142,
"page": 1,
"per_page": 20,
"total_pages": 8
}
}| Parameter | Type | Description | |
|---|---|---|---|
| page | integer | Page number to return. Default: 1. | |
| per_page | integer | Results per page. Default: 20. Maximum: 100. |
Result Ordering
When q is supplied (3 characters or more), Search Policies returns results in relevance order, most relevant first. Relevance is scored on where the match occurred: the policy name is weighted most heavily (an adjacent phrase match on the name highest of all), followed by drug names, procedure codes, taxonomy, and summary. Coverage-criteria text is searched for recall but does not raise a policy's rank.
A policy must match roughly two-thirds of your query terms to be returned at all. For one- and two-word queries every term must match; longer queries are treated more leniently, so a single unusual word will not exclude an otherwise relevant policy.
q. Requests that filter only (by cpt_code, payer_id, lcd_id, drug, or policy_type) have no relevance signal to sort on and are returned in an unspecified order. That order is not guaranteed to be stable across requests, so a policy may in rare cases appear on two pages or none while you are paging through a filter-only result set. If you need to enumerate a filter-only set exhaustively, de-duplicate the collected id values, or add a q term to get a stable relevance ordering.Rate Limits
Rate limits are applied per API key. Exceeded limits return a 429 response. Use the response headers to monitor your usage.
| Header | Type | Description | |
|---|---|---|---|
| X-RateLimit-Limit | Maximum requests allowed per minute. | ||
| X-RateLimit-Remaining | Requests remaining in the current window. | ||
| X-RateLimit-Reset | Unix timestamp when the window resets. | ||
| Retry-After | Seconds to wait before retrying (only present on 429 responses). |
Errors
NOF1 uses standard HTTP status codes. Error responses include a machine-readable code and a human-readable message.
{
"error": {
"code": "invalid_query",
"message": "At least one search parameter is required.",
"param": "q"
}
}| Status | Code | Description |
|---|---|---|
| 400 | invalid_query | A query parameter is missing, malformed, or out of range. |
| 401 | unauthorized | API key is missing, invalid, or revoked. |
| 404 | not_found | The requested policy or resource does not exist. |
| 429 | rate_limited | Too many requests. Slow down and retry after Retry-After seconds. |
List Payers
Returns NOF1's directory of supported payers: the curated payer taxonomy used across clinical and prior-auth workflows, not a live scan of indexed policies.
payer_id to filter on depends on which endpoint you're calling and on line of business. The same payer is frequently tracked under different payer_id values for clinical policy data versus prior-auth data, and those can differ per line of business too (e.g. Aetna's Medicare Advantage payer_id is aetna_medicare for clinical but Aetna-MA for prior auth). Use payer_ids.clinical.<lob> when searching policies or calling Get Policy, and payer_ids.prior_auth.<lob> when checking prior authorization. The top-level id is a stable NOF1 payer identifier (matches payer_key from Match Payer to NOF1 Payer). Don't use it as a payer_id filter value.Query Parameters
| Parameter | Type | Description | |
|---|---|---|---|
| lob | string | Filter to payers supported on this line of business. One of: commercial, medicare. | |
| page | integer | Page number. Default: 1. | |
| per_page | integer | Results per page. Default: 20. Maximum: 100. |
Example Request
curl "https://api.nofone.io/payers?lob=commercial" \ -H "Authorization: Bearer nof1_live_<your_api_key>"
Example Response 200
{
"data": [
{
"id": "aetna",
"name": "Aetna",
"lines_of_business": ["commercial", "medicare"],
"is_um_vendor": false,
"payer_ids": {
"clinical": { "commercial": "aetna", "medicare": "aetna_medicare" },
"prior_auth": { "commercial": "aetna", "medicare": "Aetna-MA" }
}
},
{
"id": "carelon",
"name": "Carelon",
"lines_of_business": ["commercial", "medicare"],
"is_um_vendor": true,
"payer_ids": {
"clinical": { "commercial": "Carelon", "medicare": "Carelon" },
"prior_auth": {}
}
},
{
"id": "premera",
"name": "Premera",
"lines_of_business": ["commercial"],
"is_um_vendor": false,
"payer_ids": {
"clinical": { "commercial": "Premera" },
"prior_auth": { "commercial": "Premera" }
}
}
],
"meta": {
"total": 3,
"page": 1,
"per_page": 20,
"total_pages": 1
}
}Notes
is_um_vendor is true for utilization-management vendors (e.g. Carelon, EviCore, Cohere) that process authorizations on behalf of one or more payers, rather than being a health plan themselves.
A payer_ids.clinical or payer_ids.prior_auth object can be missing a line of business, or be empty entirely (e.g. Carelon has no prior_auth entry above). That means NOF1 doesn't track a payer_id for that payer under that workflow/LOB, not that the lookup failed.
Match Payer to NOF1 Payer
Resolves free-text payer names from your own systems (e.g. from an eligibility feed or a manually entered payer field) to the corresponding NOF1 payer. Matching runs in three passes per query: exact name/alias match, partial token match, and (when neither finds a candidate) a semantic embedding match. If multiple payers tie for the best match, the query comes back ambiguous with all tied candidates instead of guessing.
Request Body
| Field | Type | Description | |
|---|---|---|---|
| queries | array | required | Payer name strings to resolve, one result returned per entry in the same order. Minimum 1, maximum 25. |
| lob | string | Restrict candidates to payers supported on this line of business. One of: commercial, medicare. Omit to match across both. |
Example Request
curl -X POST "https://api.nofone.io/payers/match" \
-H "Authorization: Bearer nof1_live_<your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"queries": ["Premera", "Blue Cross"],
"lob": "commercial"
}'Example Response 200
{
"data": [
{
"query": "Premera",
"matched": true,
"match_type": "exact",
"payer_key": "premera",
"payer": {
"display_name": "Premera",
"is_um_vendor": false,
"clinical": { "lines_of_business": { "Commercial": { "payer_id": "Premera" } } },
"prior_auth": { "lines_of_business": { "Commercial": { "payer_id": "Premera", "prior_auth_display": "Premera (C)" } } }
}
},
{
"query": "Blue Cross",
"matched": false,
"ambiguous": true,
"candidates": [
{
"match_type": "partial",
"payer_key": "bcbsma",
"payer": {
"display_name": "BCBSMA",
"is_um_vendor": false,
"clinical": { "lines_of_business": { "Commercial": { "payer_id": "BCBSMA" } } },
"prior_auth": null
}
},
{
"match_type": "partial",
"payer_key": "bcbsnc",
"payer": {
"display_name": "BCBSNC",
"is_um_vendor": false,
"clinical": { "lines_of_business": { "Commercial": { "payer_id": "BCBSNC" }, "Medicare Advantage": { "payer_id": "BCBSNC-MA" } } },
"prior_auth": { "lines_of_business": { "Commercial": { "payer_id": "BCBSNC", "prior_auth_display": "BCBSNC (C)" } } }
}
}
]
}
]
}Notes
Each result has one of three shapes: matched: true with a single payer; matched: false, ambiguous: true with a candidates array (as above); or matched: false, ambiguous: false with an empty candidates array when nothing matched at all. match_type is one of exact, partial, or semantic, reflecting which matching pass produced the result.
Search Policies
Returns a paginated list of policies matching the provided search criteria. lob is required; at least one additional search parameter must also be provided.
Query Parameters
| Parameter | Type | Description | |
|---|---|---|---|
| lob | string | required | Line of business. One of: commercial, medicare, medicaid, aca, or all (all searches across every line of business). |
| state | string | US state, as a 2-letter code or full name (OH, Ohio), or all. Narrows state-specific (Medicaid) policies to ones that apply in that state: the payer must operate there, and the policy must list the state or apply everywhere the payer operates. Policies from lines of business that are not state-specific are unaffected. | |
| q | string | Free-text search across policy name, summary, taxonomy, procedure codes, coverage-criteria text, and drug names. Results are returned in relevance order; see Result Ordering. Terms shorter than 3 characters fall back to a basic keyword match. Example: spinal cord stimulation. | |
| cpt_code | string | Filter to policies that reference this CPT code. Example: 63650. Can be supplied multiple times to OR across codes. | |
| payer_id | string | Filter to policies from a specific payer. Use a value from payer_ids.clinical.<lob> in the List Payers response, not its top-level id. | |
| lcd_id | string | Filter to policies that reference a specific LCD (Local Coverage Determination). Example: L37254. | |
| drug | string | Filter to policies covering a given drug. Matched case-insensitively against the drug's name, its brand and generic names, and the normalized synonym set NOF1 compiles for it, so a brand name also matches policies that only name the generic, and vice versa. Applied as a filter, not a relevance term; combine with q to rank within the matched set. Example: Humira. | |
| policy_type | string | Restrict results by policy type. One of: pharmacy (policies that govern at least one drug), medical (all other policies), any. Default: any. | |
| page | integer | Page number. Default: 1. | |
| per_page | integer | Results per page. Default: 20. Maximum: 100. |
Example Request
curl "https://api.nofone.io/policies?lob=commercial&cpt_code=63650&payer_id=pyr_premera&per_page=10" \ -H "Authorization: Bearer nof1_live_<your_api_key>"
Example Response 200
{
"data": [
{
"id": "a3f1c29e-7b4d-4e8a-9f2c-1a2b3c4d5e6f",
"name": "Spinal Cord Stimulation",
"payer": {
"id": "pyr_premera",
"name": "Premera Blue Cross"
},
"line_of_business": "commercial",
"lines_of_business": ["commercial"],
"effective_date": "2024-01-01",
"last_updated": "2024-11-15",
"cpt_codes": ["63650", "63655", "63661", "63662"],
"lcds_referenced": ["L37254"],
"is_drug_policy": false,
"is_primarily_drug_policy": false,
"drugs": []
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 10,
"total_pages": 1
}
}Get Policy
Returns the full details of a single policy: main fields, coding (CPT/HCPCS codes and coverage), criteria (clinical services and medical-necessity logic), and drug coverage (populated when the policy governs a drug). This single endpoint replaces the former separate /criteria, /coding, and /drugs endpoints, which have been removed.
Path Parameters
| Parameter | Type | Description | |
|---|---|---|---|
| policy_id | string | required | The UUID of the policy (e.g. a3f1c29e-7b4d-4e8a-9f2c-1a2b3c4d5e6f). |
Example Request
curl "https://api.nofone.io/policies/a3f1c29e-7b4d-4e8a-9f2c-1a2b3c4d5e6f" \ -H "Authorization: Bearer nof1_live_<your_api_key>"
Example Response: Clinical Policy 200
A non-drug policy: criteria.services carries the medical-necessity logic tree per service, and drug_coverage is an empty array.
{
"id": "a3f1c29e-7b4d-4e8a-9f2c-1a2b3c4d5e6f",
"name": "Spinal Cord Stimulation",
"payer": {
"id": "pyr_premera",
"name": "Premera Blue Cross"
},
"line_of_business": "commercial",
"lines_of_business": ["commercial"],
"effective_date": "2024-01-01",
"last_updated": "2024-11-15",
"url": "https://www.premera.com/medicalpolicies/8.01.004.pdf",
"lcds_referenced": [
{
"id": "L37254",
"title": "Spinal Cord Stimulation",
"contractor": "Noridian Healthcare Solutions",
"url": "https://www.cms.gov/medicare-coverage-database/details/lcd-details.aspx?LCDId=37254"
}
],
"is_drug_policy": false,
"is_primarily_drug_policy": false,
"coding": {
"cpt_codes": [
{ "code": "63650", "description": "Percutaneous implantation of neurostimulator electrode array, epidural", "covered": true, "notes": null },
{ "code": "63655", "description": "Laminectomy for implantation of neurostimulator electrodes, plate/paddle", "covered": true, "notes": null },
{ "code": "63661", "description": "Removal of spinal neurostimulator electrode percutaneous array", "covered": true, "notes": null }
],
"hcpcs_codes": [
{ "code": "E0756", "description": "Implanted spinal cord neurostimulator, pulse generator", "covered": true, "notes": null }
]
},
"criteria": {
"services_count": 2,
"covered_services_count": 1,
"excluded_services_count": 1,
"services": [
{
"service_name": "Spinal cord stimulation for chronic intractable pain",
"is_medically_necessary": true,
"med_nec_tree": {
"node_type": "head",
"type": "AND",
"children": [
{
"node_type": "leaf",
"condition": "Chronic intractable pain of the trunk or limbs not responsive to at least 6 months of conventional medical management"
},
{
"node_type": "head",
"type": "OR",
"children": [
{ "node_type": "leaf", "condition": "Failed back surgery syndrome with predominant leg pain" },
{ "node_type": "leaf", "condition": "Complex regional pain syndrome (CRPS) Type I or II" }
]
},
{
"node_type": "leaf",
"condition": "Successful trial stimulation period of at least 3 days demonstrating at least 50% pain relief"
}
]
}
},
{
"service_name": "Spinal cord stimulation for failed back surgery syndrome with predominant back pain",
"is_medically_necessary": false,
"med_nec_tree": null
}
]
},
"drug_coverage": []
}Example Response: Drug Policy 200
A drug policy: is_drug_policy is true and drug_coverage carries the per-drug utilization-management requirements.
{
"id": "b7d2e410-93cf-4a11-8c02-5d7e9f0a1b23",
"name": "Adalimumab (Humira and Biosimilars)",
"payer": {
"id": "pyr_aetna",
"name": "Aetna"
},
"line_of_business": "commercial",
"lines_of_business": ["commercial"],
"effective_date": "2024-03-01",
"last_updated": "2024-10-02",
"url": "https://www.aetna.com/policies/adalimumab.pdf",
"lcds_referenced": [],
"is_drug_policy": true,
"is_primarily_drug_policy": true,
"coding": {
"cpt_codes": [],
"hcpcs_codes": [
{ "code": "J0135", "description": "Injection, adalimumab, 20 mg", "covered": true, "notes": null }
]
},
"criteria": {
"services_count": 1,
"covered_services_count": 1,
"excluded_services_count": 0,
"services": [
{
"service_name": "Adalimumab for moderate to severe rheumatoid arthritis",
"is_medically_necessary": true,
"med_nec_tree": {
"node_type": "head",
"type": "AND",
"children": [
{ "node_type": "leaf", "condition": "Diagnosis of moderately to severely active rheumatoid arthritis" },
{ "node_type": "leaf", "condition": "Trial and failure of at least one conventional DMARD for a minimum of 3 months" }
]
}
}
]
},
"drug_coverage": [
{
"drug_name": "Adalimumab",
"drug_type": "biologic",
"brand_names": ["Humira", "Amjevita", "Hyrimoz"],
"generic_names": ["adalimumab-atto", "adalimumab-adaz"],
"indication": "Moderate to severe rheumatoid arthritis",
"fda_label_ids": ["BLA125057"],
"ndc_codes": ["00074-3799-02"],
"drug_requirements": [
"Diagnosis of moderately to severely active rheumatoid arthritis",
"Prescribed by or in consultation with a rheumatologist",
"Negative tuberculosis screening within the previous 12 months"
],
"step_therapy": [
"Trial and failure of at least one conventional DMARD (methotrexate, leflunomide, or sulfasalazine) for a minimum of 3 months"
],
"preferred_alternatives": ["Amjevita", "Hyrimoz"],
"specialty_requirements": ["Must be dispensed through a contracted specialty pharmacy"],
"dosage_requirements": ["40 mg subcutaneously every other week; maximum 2 syringes per 28 days"]
}
]
}Notes
Each element of a drug_coverage requirement array is a separate condition that must all be met. Alternatives within a single condition ("one of the following", "either/or") are preserved inside a single array element, so a single string may itself express a choice. Policies that don't govern any drug return is_drug_policy: false and an empty drug_coverage array. Always check is_drug_policy rather than array length alone.
Prior Authorization Check
Checks whether prior authorization is required for a set of CPT codes under a given payer and line of business. Returns a per-code determination along with the relevant policy and any documentation requirements. Accepts up to 10 CPT codes per request.
Request Body
| Field | Type | Description | |
|---|---|---|---|
| payer_id | string | required | The payer to check against. Use a value from payer_ids.prior_auth.<lob> in the List Payers response, not its top-level id. |
| cpt_codes | array | required | List of CPT code strings to check. Minimum 1, maximum 10. |
| lob | string | Line of business. One of: commercial, medicare, medicaid, or aca. Defaults to commercial. | |
| state | string | Required when lob is medicaid, and not accepted otherwise. Medicaid prior-auth rules differ by state. Pass a US state (2-letter code or full name) for that state's answer, or all for every state at once. Each result then also carries states, all_states (true when that is every state this payer operates in, never "all 50") and, for a single state, payer_operates_in_state. A state outside the payer's footprint returns prior_auth_required: false with payer_operates_in_state: false. |
Example Request
curl -X POST "https://api.nofone.io/prior-auth/check" \
-H "Authorization: Bearer nof1_live_<your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"payer_id": "pyr_premera",
"lob": "commercial",
"cpt_codes": ["63650", "63685", "95972"]
}'Example Response 200
{
"payer_id": "pyr_premera",
"lob": "commercial",
"results": [
{
"cpt_code": "63650",
"description": "Percutaneous implantation of neurostimulator electrode array, epidural",
"prior_auth_required": true,
"policies": [
{
"policy_id": "a3f1c29e-7b4d-4e8a-9f2c-1a2b3c4d5e6f",
"policy_name": "Spinal Cord Stimulation",
"policy_url": "https://www.premera.com/medicalpolicies/8.01.004.pdf"
}
]
},
{
"cpt_code": "63685",
"description": "Insertion or replacement of spinal neurostimulator pulse generator or receiver",
"prior_auth_required": true,
"policies": [
{
"policy_id": "a3f1c29e-7b4d-4e8a-9f2c-1a2b3c4d5e6f",
"policy_name": "Spinal Cord Stimulation",
"policy_url": "https://www.premera.com/medicalpolicies/8.01.004.pdf"
},
{
"policy_id": "b7e2d38f-8c5e-4f9b-a03d-2b3c4d5e6f7a",
"policy_name": "Implantable Neurostimulators for Pain",
"policy_url": "https://www.premera.com/medicalpolicies/7.01.125.pdf"
}
]
},
{
"cpt_code": "95972",
"description": "Electronic analysis of implanted neurostimulator pulse generator",
"prior_auth_required": false,
"policies": []
}
]
}Data Objects
Reference for the core object shapes returned by the API.
Policy
commercial, medicare. When you searched with a specific lob this is that value; otherwise it is the first entry of lines_of_business.["commercial", "medicare"].all_states is true.true if the policy governs coverage of at least one drug: a pharmacy policy, or a medical policy with a drug component.true if drugs are the policy's primary subject, rather than one component of a broader medical or procedural policy.{ cpt_codes, hcpcs_codes }, each an array of CodeEntry objects.{ services_count, covered_services_count, excluded_services_count, services }: services is an array of Service objects.is_drug_policy is false.CodeEntry
Each element of coding.cpt_codes and coding.hcpcs_codes in the Get Policy response.
false if the policy explicitly excludes this code from coverage.null.DrugCoverage
Each element of the drug_coverage array in the Get Policy response. Every requirement array is a list of conditions that must all be satisfied; empty arrays mean the policy states no requirement of that kind.
Payer
The payer sub-object embedded in Search Policies and Get Policy results, not the same shape as a List Payers entry (PayerListing, below).
PayerListing
Each element of the data array returned by List Payers.
premera), matching payer_key from Match Payer to NOF1 Payer. Not the value to filter on. Use payer_ids below.commercial, medicare.true for utilization-management vendors rather than health plans.{ clinical, prior_auth }, each a map of line of business (commercial | medicare) to the actual payer_id to filter on for that workflow. Use clinical for Search Policies / Get Policy, prior_auth for Prior Auth Check. A line of business may be missing if NOF1 doesn't track a payer_id for it under that workflow.Service
Each element of criteria.services in the Get Policy response.
true if the service is covered under some conditions; false if the service is explicitly excluded or considered experimental.null when is_medically_necessary is false. See CriteriaNode below.CriteriaNode
Recursive tree node. A node is either a head (logical operator with children) or a leaf (terminal condition).
head: a logic operator node with children; leaf: a terminal condition with no children.head nodes only. One of AND or OR: how the children must be satisfied.head nodes only. Array of child CriteriaNode objects.leaf nodes only. The plain-English clinical condition that must be satisfied.