# The payer directory

> Find the payer and its published payer ID before anything else, from public federal files, each ID with its source.

Page: https://payerworks.com/docs/payers · Markdown: https://payerworks.com/docs/payers.md

> Payerworks writes and explains files; it sends nothing to a payer. Every file a route writes says `transmitted: false`, and is yours to send on your own connection. A test key is for invented data only, never a real patient.

A search of payers and plan programs from public federal files, with a payer ID only where the payer publishes it, each with the page it came from and the day it was read. It is a directory, not a list of payers Payerworks can send to: Payerworks is connected to no payer yet.

## Routes

- [GET /v1/payers](#get-v1-payers): Search the payer directory
- [GET /v1/payers/{id}](#get-v1-payers-id): One directory row

Each route shows its call with curl and with the two clients, then its real answer, shortened, and the fields it holds. The client calls assume one client made once, `const pw = new Payerworks()` in JavaScript or `pw = payerworks.Payerworks()` in Python, each reading PAYERWORKS_API_KEY and PAYERWORKS_BASE_URL, and `body` is the request.json shown.

### GET /v1/payers

**Search the payer directory.** Payers and plan programs from public federal files (Medicare Advantage and Part D contracts, Medicaid managed care plans, insurers’ loss ratio filings, employer plans’ Form 5500 carriers) and the Medicare contractors; not a list Payerworks can send to; a payer ID only where the payer publishes it, with the page and the day it was read. Search with q by name, a misspelling, a payer ID, a NAIC code or a CMS contract ID (a state named in q is read as state=); narrow with state and type; page with limit (up to 100) and starting_after. Every row says connection none, and an all-digit payer ID under five digits is warned about: leading zeros are part of it.

Request

```bash
curl -sS -X GET "$PAYERWORKS_BASE_URL/v1/payers?q=18003" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY"
```

With the JavaScript client

```js
const answer = await pw.getPayers({ query: {"q":"18003"} });
```

With the Python client

```python
answer = pw.get_payers(query={"q": "18003"})
```

The answer (200)

```json
{
  "object": "list",
  "scope": "Payers and plan programs from public federal files; not a list of payers Payerworks can send to; payer IDs only where the payer publishes one.",
  "payer_ids_are": "A payer ID is shown only where the payer or its Medicare contractor publishes it, with the page and the day it was read. Clearinghouses can route the same payer under other IDs, and Payerworks is connected to no payer yet.",
  "built_on": "2026-10-19",
  "query": {
    "q": "18003",
    "state": null,
    "type": null
  },
  "total": 1,
  "data": [
    {
      "id": "pwd_fe5efb2967c8dc5d",
      "object": "payer_directory_row",
      "kind": "plan_program",
      "name": "Medicare DME MAC Jurisdiction C (CGS Administrators)",
      "aliases": [
        "DME MAC C",
        "DME MAC Jurisdiction C"
      ],
      "program": "medicare_dme",
      "organization_id": "pwd_deeb1d92abd324d6",
      "organization_name": "CGS Administrators",
      "parent": "Medicare fee-for-service (Original Medicare)",
      "states": [
        "AL",
        "AR"
      ],
      "nationwide": false,
      "area_stated": true,
      "payer_id": "18003",
      "payer_id_words": null,
      "published_payer_ids": [
        {
          "payer_id": "18003",
          "for": "Medicare DME claims, Jurisdiction C",
          "transactions": [
            "claims"
          ],
          "claim_type": "professional",
          "source": {
            "url": "https://www.cgsmedicare.com/jc/claims/edi.html",
            "label": "CGS JC DME: electronic claims",
            "read_on": "2026-10-19"
          }
        }
      ],
      "naic_codes": [],
      "cms_contract_ids": [],
      "hios_issuer_ids": [],
      "connection": "none",
      "transmits": false,
      "match": {
        "by": "payer_id",
        "exact": true,
        "payer_id": "18003"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "warnings": [],
  "connection": "none",
  "transmits": false
}
```

Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in [/openapi.json](https://payerworks.com/openapi.json).

| Field | Type | What it is |
| --- | --- | --- |
| `object` | the value "list" |  |
| `scope` | string | What the directory is, and is not. |
| `payer_ids_are` | string |  |
| `built_on` | string | YYYY-MM-DD. |
| `query` | object |  |
| `total` | integer |  |
| `data` | list of object |  |
| `has_more` | boolean |  |
| `next_cursor` | string or null |  |
| `warnings` | list of FieldProblem |  |
| `bluecard` | object | Asked about BlueCard: how it routes, in words. |
| `medicare_words` | string |  |
| `connection` | the value "none" |  |
| `transmits` | the value false |  |

### GET /v1/payers/{id}

**One directory row.** One row in full by its directory id (pwd_ and 16 hex): its names, where its sources say it serves (or Not stated), programs, the payer IDs it publishes with their sources, and the files it came from. A payer ID sent here is refused 400 not_a_directory_row_id and pointed to the search, never answered as not found.

Request

```bash
curl -sS -X GET "$PAYERWORKS_BASE_URL/v1/payers/pwd_fe5efb2967c8dc5d" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY"
```

With the JavaScript client

```js
const answer = await pw.getPayersById("pwd_fe5efb2967c8dc5d");
```

With the Python client

```python
answer = pw.get_payers_by_id("pwd_fe5efb2967c8dc5d")
```

The answer (200)

```json
{
  "id": "pwd_fe5efb2967c8dc5d",
  "object": "payer_directory_row",
  "kind": "plan_program",
  "name": "Medicare DME MAC Jurisdiction C (CGS Administrators)",
  "aliases": [
    "DME MAC C",
    "DME MAC Jurisdiction C"
  ],
  "program": "medicare_dme",
  "organization_id": "pwd_deeb1d92abd324d6",
  "organization_name": "CGS Administrators",
  "parent": "Medicare fee-for-service (Original Medicare)",
  "states": [
    "AL",
    "AR"
  ],
  "nationwide": false,
  "area_stated": true,
  "payer_id": "18003",
  "payer_id_words": null,
  "published_payer_ids": [
    {
      "payer_id": "18003",
      "for": "Medicare DME claims, Jurisdiction C",
      "transactions": [
        "claims"
      ],
      "claim_type": "professional",
      "source": {
        "url": "https://www.cgsmedicare.com/jc/claims/edi.html",
        "label": "CGS JC DME: electronic claims",
        "read_on": "2026-10-19"
      }
    }
  ],
  "naic_codes": [],
  "cms_contract_ids": [],
  "hios_issuer_ids": [],
  "connection": "none",
  "transmits": false,
  "naic_group_codes": [],
  "dme_jurisdiction": "C",
  "claims_mailing_address": null,
  "medicare": "fee_for_service",
  "medicaid": null,
  "possibly_same_as": [],
  "possibly_same_as_words": null,
  "sources": [
    "payer_pages"
  ],
  "children": [],
  "scope": "Payers and plan programs from public federal files; not a list of payers Payerworks can send to; payer IDs only where the payer publishes one.",
  "payer_ids_are": "A payer ID is shown only where the payer or its Medicare contractor publishes it, with the page and the day it was read. Clearinghouses can route the same payer under other IDs, and Payerworks is connected to no payer yet.",
  "built_on": "2026-10-19",
  "source_files": [
    {
      "key": "payer_pages"
    }
  ]
}
```

Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in [/openapi.json](https://payerworks.com/openapi.json).

| Field | Type | What it is |
| --- | --- | --- |
| `id` | string | The directory row id: pwd_ and 16 hex, Payerworks’ own, never a payer ID. |
| `object` | the value "payer_directory_row" |  |
| `kind` | one of "organization", "plan_program" |  |
| `name` | string |  |
| `aliases` | list of string |  |
| `types` | list of one of "commercial_insurer", "group_health_carrier", "group_dental_carrier", "medicare_advantage", "medicare_cost_plan", "medicare_part_d", "pace", "medicaid_managed_care", "medicaid_pccm", "medicaid_dental", "medicaid_behavioral_health", "medicaid_long_term_care", "medicaid_transportation", "medicaid_limited_benefit", "medicare_fee_for_service", "medicare_contractor", "medicare_dme", "tricare", "payer" | An organization’s kinds. |
| `program` | one of "commercial_insurer", "group_health_carrier", "group_dental_carrier", "medicare_advantage", "medicare_cost_plan", "medicare_part_d", "pace", "medicaid_managed_care", "medicaid_pccm", "medicaid_dental", "medicaid_behavioral_health", "medicaid_long_term_care", "medicaid_transportation", "medicaid_limited_benefit", "medicare_fee_for_service", "medicare_contractor", "medicare_dme", "tricare", "payer" | A plan program’s kind. |
| `organization_id` | string or null |  |
| `organization_name` | string or null |  |
| `parent` | string or null |  |
| `states` | list of string |  |
| `nationwide` | boolean | True only where the source says the whole country. |
| `area_stated` | boolean | False when no file or page the row was read from says where it serves: its states are then empty, and Not stated, never guessed. |
| `area_words` | string | With area_stated false: Not stated, in words. |
| `area_note` | object | What the row’s own page says about where it serves, with the page. |
| `employer_group_states` | list of string | States where CMS lists the contract for employer group plans only; never in states. |
| `see_payer_ids` | object | A Medicare Advantage contract with no published ID of its own whose parent organization publishes payer IDs for its plans: the row that holds them. The IDs are never copied onto this row. |
| `payer_id` | string or null | The one claims payer ID the payer publishes; null when it publishes none Payerworks has read, or several. |
| `payer_id_words` | string or null | Why payer_id is null, in words. |
| `published_payer_ids` | list of object | Every ID the payer or its Medicare contractor publishes, each with its page and the day it was read. |
| `naic_codes` | list of string |  |
| `cms_contract_ids` | list of string |  |
| `hios_issuer_ids` | list of string |  |
| `connection` | the value "none" | Payerworks is connected to no payer yet. |
| `transmits` | the value false |  |
| `naic_group_codes` | list of string |  |
| `programs` | list of string |  |
| `plan_type` | string |  |
| `organization_type` | string |  |
| `effective_date` | string |  |
| `medicaid_programs` | list of string |  |
| `regions` | list of string |  |
| `dme_jurisdiction` | string |  |
| `legal_state` | string |  |
| `domiciliary_states` | list of string |  |
| `claims_mailing_address` | object or null | The claims mailing address the payer gave CMS, an organization fact. |
| `medicare` | the value "fee_for_service" or list of string or null | fee_for_service, or the Medicare programs the row offers, or null. |
| `medicaid` | list of string |  |
| `possibly_same_as` | list of string |  |
| `possibly_same_as_words` | string or null |  |
| `sources` | list of string |  |
| `children` | list of object |  |
| `scope` | string |  |
| `payer_ids_are` | string |  |
| `built_on` | string |  |
| `source_files` | list of object |  |

## Reading the answer

- Each row says how it matched (`match.by`: name, alias, legal form or spelling) and whether exactly, and carries `connection: "none"` and `transmits: false`. A row with no published payer ID says so, never a guessed one.

## Troubleshooting

- `not_a_directory_row_id` (400): GET /v1/payers/{id} takes a directory row id, which begins pwd_, never a payer ID. Search with ?q= first.
- `payer_not_in_directory` (404): The directory holds no published facts about that payer.

Every refusal these routes may answer, with its status. Any route may also answer the codes every route shares, on [Every error](https://payerworks.com/docs/errors).

| Code | Status | What it means |
| --- | --- | --- |
| `invalid_payer_query` | 400 | A search parameter is out of shape; the error names it in field (q, state, type, limit or starting_after). |
| `not_a_directory_row_id` | 400 | GET /v1/payers/{id} takes a directory row id (pwd_ and 16 hex), never a payer ID: search GET /v1/payers?q= to find a payer by its payer ID or name. |
| `payer_not_in_directory` | 404 | The Payerworks directory holds no published facts about this payer. It lists payers and plan programs from public federal files, not every payer, and not the payers Payerworks can send to. |
| `payer_directory_unavailable` | 503 | The payer directory is not loaded where this was asked; the Payerworks API answers it. |

## Example

[payers.mjs](https://payerworks.com/docs/examples/payers.mjs) runs every step below against the API with a test key. It needs [payerworks.mjs](https://payerworks.com/sdk/payerworks.mjs) and [sample-data.mjs](https://payerworks.com/docs/examples/sample-data.mjs) beside it.

payers.mjs

```js
// Payerworks example: the payer directory. Docs: https://payerworks.com/docs/payers
//
// Run it with Node 18 or later, with the JavaScript client (https://payerworks.com/sdk/payerworks.mjs)
// and sample-data.mjs beside this file:
//   PAYERWORKS_API_KEY=pw_test_... PAYERWORKS_BASE_URL=<the base URL shown with your key> node payers.mjs
// A test key and invented data only. Payerworks sends nothing to a payer: every file it writes is yours.
import { pathToFileURL } from 'node:url';
import { Payerworks, PayerworksError } from './payerworks.mjs';
import { refusalOf } from './sample-data.mjs';

/** @param {Payerworks} pw */
export async function run(pw) {
  // 1. Search by name or payer ID. A payer ID is shown only where the payer publishes it, with its source.
  const found = await pw.getPayers({ query: { q: '18003' } });
  const row = found.data[0];

  // 2. One row by its directory id (pwd_...), never by a payer ID.
  const one = await pw.getPayersById(row.id);

  // 3. The failure path: a payer ID in place of a row id is refused, and the error says to search first.
  const refused = await refusalOf(() => pw.getPayersById('99999'), { PayerworksError });

  return { total: found.total, name: one.name, payer_id: one.payer_id, connection: one.connection, transmits: one.transmits, refused };
}

// Run as a script: node <this file>, with PAYERWORKS_API_KEY and PAYERWORKS_BASE_URL set.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  console.log(JSON.stringify(await run(new Payerworks()), null, 2));
}
```

What it answered, run against the API in Payerworks’ own tests (your request ids will differ)

```json
{
  "total": 1,
  "name": "Medicare DME MAC Jurisdiction C (CGS Administrators)",
  "payer_id": "18003",
  "connection": "none",
  "transmits": false,
  "refused": {
    "status": 400,
    "code": "not_a_directory_row_id",
    "request_id": "req_3"
  }
}
```