Create Credentialing Row¶

Creates a credentialing row for one billing-profile/payer/entity combination.

Endpoint¶

POST /v2/credentialing

Request Body¶

Parameter	Type	Required	Description
`billing_profile_id`	string	Yes	The billing profile this record belongs to.
`payer_id`	string	Yes	The billing-profile payer row's id — from List Billing Profile Payers. Not the payer registry id.
`entity`	string	Yes	Who this row is for: the literal string `GROUP` for the org-level row, or a provider id for an individual row.
`in_network`	boolean	No	Whether the provider is in-network with this payer. On a billing-profiles organisation it's derived, like `network_status`.
`network_status`	string	No	Whether the relationship is in-network or out-of-network. On a billing-profiles organisation it's derived: `IN_NETWORK` when the row is in network on its dates, `OUT_OF_NETWORK` otherwise. Writing `OUT_OF_NETWORK` there ends a row that covered past dates today; otherwise it marks a provider row `not_credentialed` and clears a `GROUP` row's dates. One of `IN_NETWORK`, `OUT_OF_NETWORK`.
`effective_from`	string (date)	No	`YYYY-MM-DD`.
`effective_to`	string (date)	No	`YYYY-MM-DD`.
`submitted_at`	string (date)	No	Date the application was submitted, `YYYY-MM-DD`.
`approved_at`	string (date)	No	When the payer approved the application. Drives `derived_status`. `YYYY-MM-DD`.
`committee`	boolean	No	Whether this row went through committee review. On a billing-profiles organisation it reads `true` exactly when `committee_date` is set, and `true` sent without a date sets `committee_date` to today.
`claim_hold`	object	No	Puts claims on hold for this row. Individual rows only — not accepted when `entity` is `GROUP`. See Claim Hold.
`cosigner`	object	No	The co-signer covering this row while credentialing is in progress. Individual rows only — not accepted when `entity` is `GROUP`. The co-signer must hold an `ACTIVE` credentialing row on the same billing profile and payer. See Cosigner.
`plan`	string	No	Omit (or `DEFAULT`) for the `DEFAULT` row. A card plan type creates that plan's override row, pre-filled from the `DEFAULT` row, which must exist. Billing-profiles organisations only.
`committee_date`	string (date)	No	The date the committee approved the provider, `YYYY-MM-DD`. Billing-profiles organisations only; left out of responses when unset.
`not_credentialed`	boolean	No	Provider rows: the payer refused to credential this provider. Billing-profiles organisations only; left out of responses unless `true`.
`not_accepted`	boolean	No	`GROUP` rows: the payer does not accept the clinic. Billing-profiles organisations only; left out of responses unless `true`.

Claim Hold¶

Parameter	Type	Required	Description
`from`	string (date) or null	Conditional	When the hold starts. Required when `claim_hold` is sent. `YYYY-MM-DD`.
`to`	string (date) or null	No	When the hold ends. `null` for an open-ended hold. `YYYY-MM-DD`.

Cosigner¶

Parameter	Type	Required	Description
`provider_id`	string or null	Conditional	The co-signing provider. Required when `cosigner` is sent.
`effective_from`	string (date) or null	No	`YYYY-MM-DD`.
`effective_to`	string (date) or null	No	`YYYY-MM-DD`.

Request¶

Create a provider's row:

curl --location '{base_url}/v2/credentialing' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "billing_profile_id": "b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14",
  "payer_id": "9f1c8a2e-4b31-4d0a-9c77-2f5ab8e10c44",
  "entity": "d27a6b10-9f34-4e82-b5c1-7a03e8946fd2",
  "network_status": "IN_NETWORK",
  "effective_from": "2026-01-01",
  "submitted_at": "2026-06-01",
  "approved_at": "2026-07-15",
  "claim_hold": {
    "from": "2026-09-01",
    "to": null
  }
}'

Response¶

Success Response¶

Code: 201 Created

{
  "id": "3a6d2f8b-1c4e-4b7a-8e2d-5f9c0a1b3d7e",
  "billing_profile_id": "b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14",
  "payer_id": "9f1c8a2e-4b31-4d0a-9c77-2f5ab8e10c44",
  "payer_name": null,
  "entity": "d27a6b10-9f34-4e82-b5c1-7a03e8946fd2",
  "entity_name": "Morgan Delgado",
  "npi_type": "INDIVIDUAL",
  "in_network": true,
  "network_status": "IN_NETWORK",
  "effective_from": "2026-01-01",
  "effective_to": null,
  "submitted_at": "2026-06-01",
  "approved_at": "2026-07-15",
  "committee": false,
  "claim_hold": {
    "from": "2026-09-01",
    "to": null
  },
  "cosigner": {
    "provider_id": "d27a6b10-9f34-4e82-b5c1-7a03e8946fd2",
    "effective_from": "2026-01-01",
    "effective_to": null
  },
  "derived_status": "ACTIVE",
  "retroactive": {
    "applies": true,
    "days": 30
  },
  "profile_payer_credentialing_id": null,
  "plan": "DEFAULT",
  "credentialing_status": "CREDENTIALED",
  "group_network_status": "IN_NETWORK"
}

The Location header carries the URL of the created resource.

Response Fields¶

Field	Type	Description
`id`	string	The credentialing row's id.
`billing_profile_id`	string or null	The billing profile this record belongs to.
`payer_id`	string or null	The billing-profile payer row's id — from List Billing Profile Payers. Not the payer registry id.
`payer_name`	string or null
`entity`	string	Who this row is for: the literal string `GROUP` for the org-level row, or a provider id for an individual row.
`entity_name`	string or null	Display name for `entity` — `"Group"` for the `GROUP` row, otherwise the provider's name.
`npi_type`	string or null	Whether this is a group NPI or an individual NPI. One of `GROUP`, `INDIVIDUAL`.
`in_network`	boolean or null	Whether the provider is in-network with this payer. On a billing-profiles organisation it's derived, like `network_status`.
`network_status`	string or null	Whether the relationship is in-network or out-of-network. On a billing-profiles organisation it's derived: `IN_NETWORK` when the row is in network on its dates, `OUT_OF_NETWORK` otherwise. Writing `OUT_OF_NETWORK` there ends a row that covered past dates today; otherwise it marks a provider row `not_credentialed` and clears a `GROUP` row's dates. One of `IN_NETWORK`, `OUT_OF_NETWORK`.
`effective_from`	string or null
`effective_to`	string or null
`submitted_at`	string or null	Date the application was submitted, `YYYY-MM-DD`.
`approved_at`	string or null	When the payer approved the application. Drives `derived_status`.
`committee`	boolean	Whether this row went through committee review. On a billing-profiles organisation it reads `true` exactly when `committee_date` is set, and `true` sent without a date sets `committee_date` to today.
`claim_hold`	object or null	Puts claims on hold for this row. `null` releases the hold. Set through Hold Claims / Release Claims, or inline on create and update. See Claim Hold.
`cosigner`	object or null	The co-signer covering this row while credentialing is in progress. `null` removes it. The co-signer must hold an `ACTIVE` credentialing row on the same billing profile and payer. See Cosigner.
`derived_status`	string	Computed from `submitted_at`, `approved_at`, `effective_from` and `effective_to` — never set directly. One of `NONE`, `SUBMITTED`, `DUE`, `ACTIVE`, `EXPIRED`.
`retroactive`	object or null	Derived from the payer's retroactive credentialing rules. Never set directly. See Retroactive.
`profile_payer_credentialing_id`	integer or null	A stable id in the downstream billing system, once published. `null` before publish.
`plan`	string	`DEFAULT` (every plan) or the card plan type this row overrides. Billing-profiles organisations only; absent elsewhere.
`credentialing_status`	string	Computed from the row's dates and refusal flag — never set directly. A `GROUP` row: `IN_NETWORK`, `PENDING`, `NOT_ACCEPTED` or `NO_CONTRACT`. A provider row: `CREDENTIALED`, `PENDING`, `NOT_CREDENTIALED`, `ENDED` or `NONE`. Billing-profiles organisations only. One of `IN_NETWORK`, `PENDING`, `NOT_ACCEPTED`, `NO_CONTRACT`, `CREDENTIALED`, `NOT_CREDENTIALED`, `ENDED`, `NONE`.
`group_network_status`	string	The `credentialing_status` of the clinic (`GROUP`) row for this row's billing profile, payer and plan, falling back to its `DEFAULT` row; `NO_CONTRACT` when there is none. Billing-profiles organisations only. One of `IN_NETWORK`, `PENDING`, `NOT_ACCEPTED`, `NO_CONTRACT`.
`not_credentialed`	boolean	Provider rows: the payer refused to credential this provider. Billing-profiles organisations only; left out of responses unless `true`.
`not_accepted`	boolean	`GROUP` rows: the payer does not accept the clinic. Billing-profiles organisations only; left out of responses unless `true`.
`committee_date`	string or null	The date the committee approved the provider, `YYYY-MM-DD`. Billing-profiles organisations only; left out of responses when unset.

Claim Hold¶

Field	Type	Description
`from`	string or null	When the hold starts.
`to`	string or null	When the hold ends. `null` for an open-ended hold.

Cosigner¶

Field	Type	Description
`provider_id`	string or null	The co-signing provider.
`effective_from`	string or null
`effective_to`	string or null

Retroactive¶

Field	Type	Description
`applies`	boolean	Whether a retroactive grace period applies to this row.
`days`	integer	Length of the retroactive window in days; `0` when `applies` is `false`.

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`409 Conflict`	`conflict`	The record conflicts with existing state — see the endpoint's notes.
`412 Precondition Failed`	`precondition_failed`	`If-Match` is stale. Re-read the resource and retry.
`423 Locked`	`locked`	The organisation has a publish in progress. Retry once it finishes.
`428 Precondition Required`	`precondition_required`	`If-Match` is required on this write.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

payer_id here is the billing-profile payer row id — from List Billing Profile Payers, not the payer registry id.
entity is the literal string GROUP for the org-level row, or a provider id for an individual row.
409 on a duplicate (billing profile, payer, entity).
On a billing-profiles organisation, a create matching a row that was ended and kept as history returns 409 CRED_ROW_ENDED: extend that row's effective_to with Update Credentialing Row instead, which re-opens it.
On a billing-profiles organisation, plan set to a card plan type creates that plan's override row, pre-filled from the DEFAULT row, which must exist; without plan the DEFAULT row is created, as before. payer_id stays the payer's DEFAULT row either way.
network_status / in_network and committee are still accepted there: IN_NETWORK keeps the row with its dates (undated reads as incomplete, not in network), and committee: true without committee_date sets it to today.
On other organisations a card plan type in plan, a committee_date, or not_credentialed / not_accepted set to true returns 400 BILLING_PROFILES_ONLY; plan: "DEFAULT" and false are accepted.
plan, include_plan_overrides, credentialing_status, group_network_status, committee_date, not_credentialed and not_accepted arrive with the payer-credentialing release. Until it reaches your environment they are absent from responses and refused on writes (400).
When onboarding refuses a write, each errors[] entry carries a code naming the rule that failed, and field names the field in snake_case, as this API spells it (an empty field means the whole row, or the whole create, not one field). A 400 for a body that fails this API's own schema check (an unknown field, a wrong type, a value outside the listed ones) has no code; its field is the JSON pointer of the offending value (/effective_from) or the name of the missing field. Codes from this endpoint: DUPLICATE_PLAN_ROW (409, the plan's row exists), CRED_ROW_ENDED (409, the row exists as history), PLAN_OVERRIDE_NEEDS_DEFAULT, PLAN_INVALID, REFUSAL_WITH_DATES (not_credentialed or not_accepted together with dates), COSIGNER_NOT_AFFILIATED, COSIGNER_NO_EMR_ID, COSIGNER_SELF, COSIGNER_NOT_CREDENTIALED, BILLING_PROFILES_ONLY.
claim_hold and cosigner apply to individual rows only — not to GROUP.