Skip to main content

Patient numbers — definition CRUD and referenceId

The GraphQL API now supports managing Practice Number definitions (catalogue entries such as NH_ID) and exposes a stable correlation id on patient number assignments.

New mutations​

All require the settingsGeneral permission on the integration token.

  • createPatientNumber(input: CreatePatientNumberInput!) — create a Practice Number definition.
  • updatePatientNumberDefinition(id: ID!, input: UpdatePatientNumberDefinitionInput!) — update name and/or primary.
  • deletePatientNumberDefinition(id: ID!) — soft-delete a definition (system definitions cannot be deleted).

CreatePatientNumberInput.idType follows the Heydoc UI rules:

  • GB practices: USER (default) or NHS_UK when no active NHS definition exists.
  • FR practices: USER (default) or INS_FR when no active INS definition exists.

Primary identifier​

Only one Practice Number definition may be primary: true at a time. Setting primary: true on create or update demotes the previous primary definition.

New field on patient numbers​

  • PatientNumber.referenceId (ID!) — the id of the Practice Number definition. Same value as createPatientNumber.data.id and the numberId passed to addPatientNumber. Returned even when the definition has been soft-deleted (name may be null in that case).
mutation {
  createPatientNumber(input: { name: "NH_ID" }) {
    data { id }
    error
  }
}

mutation {
  addPatientNumber(
    patientId: "..."
    patientNumber: { numberId: "<definition id>", value: "..." }
  ) {
    data { numbers { referenceId name value } }
    error
  }
}

query {
  patient(id: "...") {
    numbers { id referenceId name value }
  }
}

This is an additive change. Existing queries and mutations are unaffected.