Update Billing Profile¶

Updates a billing profile and returns the updated record.

Endpoint¶

PATCH /v2/billing-profiles/{billing_profile_id}

Path Parameters¶

Parameter	Type	Required	Description
`billing_profile_id`	string	Yes	The billing profile this record belongs to.

Request¶

curl --location '{base_url}/v2/billing-profiles/b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14' \
  --request PATCH \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/merge-patch+json' \
  --data '{}'

Response¶

Success Response¶

Code: 200 OK

{
  "id": "b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14",
  "kind": "OWN",
  "display_name": "Example Therapy \u2014 Billing Group A",
  "status": "ACTIVE",
  "is_default": false,
  "npi_verified": true,
  "identity": {
    "npi": "1740398215",
    "npi_type": "NPI-2",
    "tax_id": "831234567",
    "tax_id_type": "EIN",
    "ptan": null,
    "taxonomies": [],
    "primary_taxonomy_code": null,
    "primary_group_code": null,
    "address": null,
    "contact": {
      "phone": "+1-555-0143",
      "fax": null,
      "email": "m.delgado@example.com"
    }
  },
  "clinic_ids": [
    "5831"
  ],
  "taxonomy_print_default": "NPPES",
  "external_partner_ref": null,
  "effective_from": "2026-01-01",
  "effective_to": null,
  "pcn_prefix": "SPRY",
  "pcn_format_version": 2,
  "max_pcn_length": 20,
  "claim_reference_effective_from": "2026-01-01",
  "claim_reference_effective_to": null,
  "era_return_channel_id": null,
  "billing_profile_id": null
}

Response Fields¶

Field	Type	Description
`id`	string	The billing profile's own id.
`kind`	string	Whether this is the organisation's own billing entity or a third-party partner's. One of `OWN`, `PARTNER`.
`display_name`	string or null
`status`	string	Lifecycle state of the record. One of `ACTIVE`, `INACTIVE`.
`is_default`	boolean	Whether this is the organisation's default billing profile. Exactly one profile is always the default, and it can't be set to `INACTIVE`.
`npi_verified`	boolean	Whether onboarding validated the NPI against NPPES.
`identity`	object or null	NPI/tax id identity for this profile. Required for `kind: "OWN"`. See Identity.
`clinic_ids`	array of string	Clinics billed under this profile.
`taxonomy_print_default`	string	Whether the claim print default uses the NPPES taxonomy or is left blank. One of `NPPES`, `BLANK`.
`external_partner_ref`	string or null	Your own reference for a `PARTNER` profile.
`effective_from`	string or null
`effective_to`	string or null
`pcn_prefix`	string or null	Prefix prepended to generated patient control numbers.
`pcn_format_version`	integer or null	Version tag for the patient-control-number format in use.
`max_pcn_length`	integer or null	Maximum length of a generated patient control number.
`claim_reference_effective_from`	string or null	Start of the window this profile's claim-reference numbering applies in.
`claim_reference_effective_to`	string or null	End of that window. `null` for open-ended.
`era_return_channel_id`	string or null	Which ERA return channel delivers remittances for this profile.
`billing_profile_id`	integer or null	The billing profile this record belongs to.

Identity¶

Field	Type	Description
`npi`	string or null
`npi_type`	string or null	NPI type of the billing entity. Always `NPI-2` (organisation NPI).
`tax_id`	string or null	Nine digits, no hyphen.
`tax_id_type`	string or null	One of `EIN`, `SSN`.
`ptan`	string or null	Provider Transaction Access Number.
`taxonomies`	array
`primary_taxonomy_code`	string or null	NUCC provider taxonomy code.
`primary_group_code`	string or null	Group code printed alongside the primary taxonomy, when the payer requires one.
`address`	any or null
`contact`	object or null	Contact details for this billing profile. See Contact.

Contact¶

Field	Type	Description
`phone`	string or null
`fax`	string or null
`email`	string or null

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¶

PATCH is a JSON Merge Patch (RFC 7386): an omitted field is left alone, an explicit null clears it, and an array replaces the existing one wholesale.
Send If-Match with the ETag from a prior read. * opts into last-writer-wins. A stale value returns 412; a missing one returns 428.
There's no DELETE — set status to INACTIVE instead. The default profile can't be deactivated: that returns 409 (conflict) — the response message explains; upstream error codes are not forwarded.