Skip to content

Create Billing Profile

Creates a billing profile.

Endpoint

POST /v2/billing-profiles

Request Body

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

Identity

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

Contact

Parameter Type Required Description
phone string or null No
fax string or null No
email string or null No

Request

curl --location '{base_url}/v2/billing-profiles' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "kind": "OWN",
  "display_name": "Example Therapy \u2014 Billing Group A",
  "status": "ACTIVE",
  "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
}'

Response

Success Response

Code: 201 Created

{
  "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
}

The Location header carries the URL of the created resource.

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

  • identity.npi and identity.tax_id are required for kind: "OWN".
  • The profile's own billing_profile_id field is a separate downstream mirror id (an integer, null until publish) — every other endpoint's billing_profile_id means this profile's id instead.