Oystehr
Oystehr Services
FHIR
Friendly Patient ID

Generate Friendly Patient ID

The $generate-friendly-patient-id operation assigns a human-readable, sequential numeric identifier to a Patient resource. This is useful when you need a short, easy-to-communicate patient ID for use in front-desk workflows, printed materials, or patient-facing applications — as opposed to the default UUID-based FHIR resource ID.

Endpoint

POST /Patient/[id]/$generate-friendly-patient-id

No request body is required. The [id] path parameter is the FHIR resource ID of the Patient.

How It Works

  1. The operation looks up the Patient resource by its FHIR ID.
  2. A new sequential numeric identifier is generated, unique within your project.
  3. The identifier is added to the Patient's identifier array with a project-scoped system URL.
  4. The updated Patient resource is returned.

The generated identifier uses the system:

https://identifiers.fhir.oystehr.com/friendly-patient-id/{projectId}

where {projectId} is your Oystehr project ID.

Request

Generate friendly patient ID with the v3 SDK:

import { Patient } from 'fhir/r4b'; // npm install @types/fhir
import Oystehr from '@oystehr/sdk'
 
const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});
 
const updatedPatient/*: Patient*/ = await oystehr.fhir.generateFriendlyPatientId({ id: patient.id });

Response

A successful response returns the updated Patient resource with the new identifier appended:

{
  "resourceType": "Patient",
  "id": "example-patient-id",
  "identifier": [
    {
      "system": "https://identifiers.fhir.oystehr.com/friendly-patient-id/<your_project_id>",
      "value": "1"
    }
  ],
  "name": [
    {
      "family": "Smith",
      "given": ["John"]
    }
  ]
}

The value field contains the generated sequential numeric ID (e.g. "1", "2", "3", ...). Each call to this operation on a different Patient produces the next number in the sequence.

If the Patient already has other identifiers, the friendly ID is appended to the existing identifier array.

Error Responses

Status CodeCondition
404 Not FoundThe Patient resource does not exist or has been deleted.
422 Unprocessable EntityThe Patient already has a friendly patient identifier.

Important Behaviors

⚠️

Once a friendly patient ID has been generated, it cannot be modified or removed. Any attempt to alter or delete the friendly identifier through a subsequent Patient update will be rejected with a 422 Unprocessable Entity error. Other fields on the Patient resource can still be updated normally.

  • One per Patient: Each Patient can have at most one friendly patient ID. Calling the operation again on a Patient that already has one will return a 422 error.
  • Sequential and unique: IDs are assigned as incrementing integers, unique across all Patients within your project.
  • Concurrency safe: The operation handles concurrent requests safely. If multiple requests are made simultaneously for different Patients, each will receive a distinct ID.
  • Project-scoped: The identifier system is scoped to your project. Different projects maintain independent ID sequences.
Bulk Data ExportIAM