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.
network_status	string	No	Whether the relationship is in-network or out-of-network. 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.
claim_hold	object	No	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	No	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.

Claim Hold

Parameter	Type	Required	Description
from	string (date) or null	No	When the hold starts. 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	No	The co-signing provider.
effective_from	string (date) or null	No	YYYY-MM-DD.
effective_to	string (date) or null	No	YYYY-MM-DD.

Request

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",
  "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
  }
}'

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
}

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.
network_status	string or null	Whether the relationship is in-network or out-of-network. 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.
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.

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).