Platform API

Update organization billing profile

Upsert practice identity, billing providers, and rendering providers for an authorized organization.

PUThttps://app.mindbill.org/partner/v2/organizations/{id}/billing-profile

Use when your product owns organization setup — server callers and OrganizationOnboarding use the same business routes. Server writes require orgs:write; browser settings writes require organization:manage. The singular /organization routes address the credential organization; /organizations/{id} addresses an authorized linked organization. Browser sessions and organization-scoped keys must use their fixed organization ID; an account-scoped partner key may address any linked organization it is authorized to manage.

AuthenticationServer API key or browser session + Origin

Permissions by credentialServer: orgs:write · Browser: organization:manage

IdempotencyRequired for safe retries

Use this URL with a server API key or a browser session and its exact allowed Origin. Both credentials use the same request and response contract. See the component API inventory for exact paths and SDK methods.

Path parameters

FieldTypeDescription

idRequired

string

An authorized linked organization ID. Browser sessions and organization-scoped keys must use their fixed organization ID.

Request body

FieldTypeDescription

practiceIdentity

object

Practice name, legalName, taxId, npi, phone, email — merged over existing values; unset fields are preserved.

billingProviders[]

object[]

Pay-to providers upserted by id, then externalId, else appended with a generated id. Existing records are never deleted.

practiceIdentity.taxIdType / billingProviders[].taxIdType

"EIN" | "SSN"

Tax identifier type; defaults to EIN. SSNs are encrypted at rest. Changing type requires a replacement taxId.

practiceIdentity.taxId / billingProviders[].taxId

string

Omit to preserve an existing identifier; send an empty string to explicitly clear it. Do not send response-only taxIdConfigured or taxIdLast4 in settings writes.

renderingProviders[]

object[]

Rendering providers upserted by id or externalId. Each record requires name and npi; omission does not delete saved records.

Examples

curl https://app.mindbill.org/partner/v2/organizations/$ORG_ID/billing-profile \
  --request PUT \
  --header "Authorization: Bearer $MINDBILL_API_KEY" \
  --header "Idempotency-Key: organization-profile-0001" \
  --header "Content-Type: application/json" \
  --data '{
    "practiceIdentity": { "name": "Example Medical Group", "taxId": "94-1234567", "npi": "1234567893" }
  }'

Response

200 OK

{
  "data": {
    "organizationId": "org_01J4",
    "practiceIdentity": { "name": "Example Medical Group", "taxId": "94-1234567", "npi": "1234567893" },
    "billingProviders": [],
    "renderingProviders": [],
    "locations": [],
    "w9": null,
    "onboarding": { "status": "configuring", "complete": false, "checklist": [] }
  }
}

FieldTypeDescription

data.organizationIdRequired

string

The organization.

data.practiceIdentity / billingProviders / renderingProviders / locations / w9Required

object

The profile after the write. Saved SSNs return taxId as an empty string, with taxIdType: SSN, taxIdConfigured, and taxIdLast4; no plaintext SSN is returned.

data.onboardingRequired

{ status, complete, checklist[] }

MindBill's onboarding checklist — the same one the embeddable component renders.