POST/transactional-api/register-permanent-nhs-patient

Register Permanent NHS Patient

Registers a new GMS permanent registration for a patient, the same effect as a receptionist completing GMS registration in Medicus. User-restricted only: the calling staff member must have a CIS2 identity with the B0825 (Amend Patient Demographics) RBAC activity code. Place of birth is not accepted here: for an NHS Number patient it is sourced from the PDS record, not from the request.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/register-permanent-nhs-patient' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "nhsNumber": "9730069441",
    "acceptanceType": "transfer-in",
    "responsibleHealthAuthority": "BAA",
    "usualGp": "4d59c916-9726-11ec-af3f-0a58a9feac02",
    "dateOfEntryIntoUK": "2026-01-01",
    "dateOfLeavingUK": "2025-09-01",
    "dateOfEnlistment": "2015-01-01",
    "dateOfDischarge": "2020-01-01",
    "medicationDispensedByPractice": false,
    "preferredLocationId": "7c2b6e2a-1f0e-4a3e-9b0a-2f6c8e4d5a1b",
    "preferredCollectionLocationId": "9a1e2d3c-4b5f-4a6e-8c7d-1e2f3a4b5c6d",
    "previousHomeAddress": {
      "line1": "90 York Way",
      "line2": "Kings Cross",
      "line3": "string",
      "locality": "London",
      "administrativeArea": "Greater London",
      "postalCode": "N1 9AG"
    },
    "previousGPName": "Kings Cross Surgery",
    "residentialInstituteCode": "V0",
    "gpNotes": "PROOF_OF_IDENTIFICATION",
    "gpNotesText": "Passport seen at registration"
  }'

Body parameters

Field	Type	Required	Description
nhsNumber	string	Yes	A verified NHS number for the patient.
acceptanceType	enum	Yes	One of: birth, first-acceptance, transfer-in, immigrant, ex-services.
responsibleHealthAuthority	enum	Yes	The NHAIS trading partner code for the health authority responsible for the patient. Fixed list, does not vary by practice. One of: BRS, LNC, LNH, BAA, BD, BE, LNW, BIR, BRA, LNL, LNT, BU, ROC, YW, CB, LND, CH, CR, DR, COV, LNR, CU, MID, DE, DN, DCR, DO, DUD, LNM, LNA, TE, LNE, EX, GAT, GG, SO, WR, HT, LNK, KHU, IM, LNJ, KC, LNN, LNS, LA, LDS, LD, LL, LIP, MAN, LNP, NEW, NF, YN, NO, NR, NN, OX, LNB, ROT, SLF, WBH, SOP, SHE, SA, WMF, SM, STL, ST, SPT, SU, SUN, SY, WAK, WAL, WA, GMK, TW, WIG, WL, BIK, WOM.
usualGp	string<uuid>	No
dateOfEntryIntoUK	string<date>	No	Required when acceptanceType is immigrant.
dateOfLeavingUK	string<date>	No
dateOfEnlistment	string<date>	No	Required when acceptanceType is ex-services and previousHomeAddress is not supplied.
dateOfDischarge	string<date>	No
medicationDispensedByPractice	boolean	Yes
preferredLocationId	string<uuid>	No	One of the ids returned by list-sites.
preferredCollectionLocationId	string<uuid>	No	Sets a dispensing collection-point preference for the patient, if supplied. One of the ids returned by list-collection-locations.
previousHomeAddress	object	No	Required when acceptanceType is transfer-in, or ex-services without dateOfEnlistment/dateOfDischarge.
previousGPName	string	No	Required when acceptanceType is transfer-in.
residentialInstituteCode	enum	No	One of: V0, Y0.
gpNotes	enum	No	One of: PROOF_OF_IDENTIFICATION, REGISTRATION_UNDER_OUT_OF_AREA_SCHEME, OTHER.
gpNotesText	string	No	Required when gpNotes is OTHER.

Responses

200 Patient registered.

Response fields

Field	Type	Description
patientId	string<uuid>

{
  "patientId": "b3d1f7a2-6c4e-4b9a-8e0f-1a2b3c4d5e02"
}

400 Validation error.

19 possible code values

Code	Description	When
missing-nhs-number	The nhsNumber is required.	nhsNumber is blank
invalid-nhs-number	The nhsNumber is not a valid NHS number.	nhsNumber is present but not a valid NHS number
missing-acceptance-type	The acceptanceType is required.	acceptanceType is blank
invalid-acceptance-type	The acceptanceType is required and must be a recognised value.	acceptanceType is present but not a recognised value
missing-responsible-health-authority	The responsibleHealthAuthority is required.	responsibleHealthAuthority is blank
invalid-responsible-health-authority	The responsibleHealthAuthority is required and must be a recognised value.	responsibleHealthAuthority is present but not a recognised value
invalid-usual-gp	The usualGp is not valid.	usualGp is not a valid UUID
invalid-preferred-location-id	The preferredLocationId is not valid.	preferredLocationId is not a valid UUID
invalid-preferred-collection-location-id	The preferredCollectionLocationId is not valid.	preferredCollectionLocationId is not a valid UUID
invalid-date-of-entry-into-uk	The dateOfEntryIntoUK is required and must be a valid date in Y-m-d format.	dateOfEntryIntoUK is missing or invalid for an immigrant acceptanceType
invalid-date-of-leaving-uk	The dateOfLeavingUK is not valid.	dateOfLeavingUK is invalid, or inconsistent with dateOfEntryIntoUK
invalid-date-of-enlistment	The dateOfEnlistment is required and must be a valid date in Y-m-d format.	dateOfEnlistment is missing or invalid for an ex-services acceptanceType without a previousHomeAddress
invalid-date-of-discharge	The dateOfDischarge is not valid.	dateOfDischarge is missing, invalid, or before dateOfEnlistment
invalid-previous-home-address	The previousHomeAddress is required, with at least line1.	previousHomeAddress (or its line1) is missing when required
invalid-previous-gp-name	The previousGPName is required.	previousGPName is missing for a transfer-in acceptanceType
invalid-residential-institute-code	The residentialInstituteCode is not a recognised value.	residentialInstituteCode is set to an unrecognised value
invalid-gp-notes	The gpNotes is not a recognised value.	gpNotes is set to an unrecognised value
invalid-gp-notes-text	The gpNotesText is required (max 60 characters) when gpNotes is OTHER.	gpNotesText is missing or too long when gpNotes is OTHER
patient-already-registered	The patient for this NHS number already has an active permanent registration.	the patient already has an active permanent registration

Response fields

Field	Type	Description
errors[].code	string
errors[].description	string

{
  "errors": [
    {
      "code": "missing-nhs-number",
      "description": "The nhsNumber is required."
    }
  ]
}

403 The calling staff member cannot be authorised for this action.

3 possible code values

Code	Description	When
cis2-not-logged-in	This staff member is not currently logged in with CIS2. They must log in with CIS2 and try again.	the calling staff member is not currently logged in with CIS2 (never logged in, or their session has lapsed and could not be refreshed)
cis2-activity-not-granted	This staff member's CIS2 role does not have the RBAC activity code required.	the calling staff member's CIS2 role lacks the required RBAC activity code
application-restricted-not-supported	This endpoint is only available to user-restricted callers.	the call is application-restricted rather than user-restricted

Response fields

Field	Type	Description
errors[].code	string
errors[].description	string

{
  "errors": [
    {
      "code": "cis2-not-logged-in",
      "description": "This staff member is not currently logged in with CIS2. They must log in with CIS2 and try again."
    }
  ]
}

404 A referenced id does not correspond to anything.

3 possible code values

Code	Description	When
usual-gp-not-found	No staff member was found for the given usualGp.	usualGp is a validly formed UUID but no staff member exists with that id
preferred-location-not-found	No site was found for the given preferredLocationId.	preferredLocationId is a validly formed UUID but no site exists with that id
preferred-collection-location-not-found	No collection location was found for the given preferredCollectionLocationId.	preferredCollectionLocationId is a validly formed UUID but no collection location exists with that id

Response fields

Field	Type	Description
errors[].code	string
errors[].description	string

{
  "errors": [
    {
      "code": "usual-gp-not-found",
      "description": "No staff member was found for the given usualGp."
    }
  ]
}

409 Another registration for this NHS number was still running after 30 seconds.

Response fields

Field	Type	Description
errors[].code	string
errors[].description	string

{
  "errors": [
    {
      "code": "registration-in-progress",
      "description": "Another registration for this NHS number is still in progress. Try again shortly."
    }
  ]
}