Get Billing Profile

Returns a single billing profile.

Endpoint

GET /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' \
  --header 'Authorization: Bearer JWT_TOKEN'

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

• Keep the ETag from this response — writes require it as If-Match.