Healthcode-relevant invoice fields

Summary

The invoice and invoices queries now expose Healthcode-relevant data without adding fields to global User or Contact types. All new fields are opt-in via GraphQL selection.

This release is additive. Existing queries are unchanged when the new fields are omitted.

Invoice snapshot vs current (live) data

Many Healthcode fields can come from either values stored on the invoice (snapshots taken at creation or update) or live records loaded when you query. Partners should choose deliberately:

Healthcode need	Recommended field	Data source
Patient title at invoice time	patientTitle	Invoice snapshot
Patient title now	patient.title	Current patient record
Patient DOB at invoice time	patientDob	Invoice snapshot
Patient DOB now	patient.dob	Current patient record
Patient forename / surname	patient.firstName, patient.lastName	Current patient record — may differ from the name on the invoice if the patient has since changed their name
Patient gender	patient.sex / patient.gender	Current patient record
Patient address	patient.address	Current patient record
Policy / registration number at invoice time	insuranceDetails.registrationNumber	Invoice snapshot (from INSURER relationship matching accountId at creation)
Policy / registration number now	patient.relatedAccounts → contactDetails.policyNumber (match relatedAccountId to accountId)	Current relationship
Authorisation code at invoice time	insuranceDetails.authorizationCode	Invoice snapshot
Authorisation code now	patient.relatedAccounts → contactDetails.authorizationCode	Current relationship
Claim / specialist / payee provider default	doctorHealthcodeIdentifier	Current doctor user profile
Per-line provider default	lineItems.providerHealthcodeIdentifier	Current doctor user profile (same default as claim level)
Insurer Healthcode identifier	insuranceDetails.healthcodeIdentifier	Current contact record for accountId
Line item code	lineItems.healthcodeCode	Invoice snapshot (serviceCode, else industryStandardCode)
Line item description	lineItems.title	Invoice snapshot
Line item date	lineItems.date	Invoice snapshot
Line item value (incl. tax)	lineItems.netTotal	Invoice snapshot
Invoice number / total	invoiceNumber, total	Invoice snapshot

Semble does not change historical invoice snapshots when a patient or doctor updates their details later. If you need invoice-time values, use the snapshot fields on Invoice. If you need what is on the patient or doctor record now, use the nested patient, doctor, or live fields on insuranceDetails.

New fields

Invoice snapshots and status

• accountId — billed account (patient or insurer contact) stored on the invoice.
• patientTitle, patientDob — patient snapshots stored on the invoice.
• insuranceDetails — insurer snapshot (name, registrationNumber, authorizationCode) plus live healthcodeIdentifier from the billed contact.
• healthcode — submission status (status, providerReference, updatedAt).

Related entities (invoice-scoped, current data)

• doctorHealthcodeIdentifier — live Healthcode provider number from the invoice doctor; default for provider, payee provider, controlling specialist, and per-line provider at submission.

Line items (invoice snapshots unless noted)

• lineItems.healthcode — serviceCode, industryStandardCode, procedureCode.
• lineItems.healthcodeCode — preferred item code (serviceCode when set, otherwise industryStandardCode).
• lineItems.netTotal — line total including tax, matching Healthcode NetTotal.
• lineItems.providerHealthcodeIdentifier — current default provider number from the invoice doctor (same as doctorHealthcodeIdentifier).

Use the existing patient nested field for live address, sex, and name.

Out of scope

• submitInvoiceToHealthcode mutation and submission-time parameter overrides (serviceSetting, diagnosisCode, etc.).
• Healthcode practice credentials (siteId, password).
• episodeDate (requires a follow-up model change).

Example

query InvoiceHealthcode($id: ID!) {
  invoice(id: $id) {
    invoiceNumber
    date
    total
    accountId
    patientTitle
    patientDob
    insuranceDetails {
      registrationNumber
      authorizationCode
      healthcodeIdentifier
    }
    doctorHealthcodeIdentifier
    patient {
      firstName
      lastName
      dob
      sex
      address {
        postcode
        address
        city
        country
      }
      relatedAccounts {
        relationshipType
        contactDetails {
          relatedAccountId
          policyNumber
          authorizationCode
        }
      }
    }
    lineItems {
      date
      title
      quantity
      netTotal
      healthcodeCode
      providerHealthcodeIdentifier
      healthcode {
        serviceCode
        industryStandardCode
        procedureCode
      }
    }
    healthcode {
      status
      providerReference
    }
  }
}

Migration

No breaking changes. Partners integrating with Healthcode can request these fields on existing invoice / invoices queries when building claim payloads or reconciliation views.

• API reference: invoice
• API reference: invoices
• API reference: Invoice