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

Register Patient Without NHS Number

Registers a new GMS permanent registration for a patient who has no NHS number yet (not yet traced, non-UK arrival, private-only, etc), the same effect as a receptionist completing the "without NHS number" GMS registration in Medicus. User-restricted only. Do not use this endpoint if the patient has an NHS number - use register-permanent-nhs-patient instead, which registers via PDS and keeps the patient's NHS number correctly linked. This endpoint never checks whether one exists, and registers the patient without one regardless.

Authorization: Bearer token (JWT). See Authentication.

Request

curl -L -X POST 'https://{tenantId}.api.england.medicus.health/transactional-api/register-permanent-patient-without-nhs-number' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "title": "Mrs",
    "firstName": "Jane",
    "middleNames": "Elizabeth",
    "lastName": "Doe",
    "dateOfBirth": "1990-05-12",
    "gender": "female",
    "currentHomeAddress": {
      "line1": "90 York Way",
      "line2": "Kings Cross",
      "line3": "string",
      "locality": "London",
      "administrativeArea": "Greater London"
    },
    "homePhoneNumber": "01632 960001",
    "mobilePhoneNumber": "07700 900001",
    "workPhoneNumber": "01632 960002",
    "temporaryPhoneNumber": "01632 960003",
    "emailAddress": "jane.doe@example.com",
    "placeOfBirthCountry": "GBR",
    "acceptanceType": "immigrant",
    "responsibleHealthAuthority": "BAA",
    "usualGp": "4d59c916-9726-11ec-af3f-0a58a9feac02",
    "preferredLocationId": "7c2b6e2a-1f0e-4a3e-9b0a-2f6c8e4d5a1b",
    "preferredCollectionLocationId": "9a1e2d3c-4b5f-4a6e-8c7d-1e2f3a4b5c6d",
    "dateOfEntryIntoUK": "2026-01-01",
    "dateOfLeavingUK": "2025-09-01",
    "medicationDispensedByPractice": false,
    "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
title	string	No
firstName	string	Yes
middleNames	string	No
lastName	string	Yes
dateOfBirth	string<date>	No
gender	enum	Yes	One of: male, female, indeterminate.
currentHomeAddress	object	No	Required when acceptanceType is transfer-in or immigrant.
homePhoneNumber	string	No
mobilePhoneNumber	string	No
workPhoneNumber	string	No
temporaryPhoneNumber	string	No
emailAddress	string<email>	No
placeOfBirthCountry	string	Yes	ISO 3166-1 alpha-3 code, or one of the UK internal codes (1=England, 2=Scotland, 3=Wales, 4=Northern Ireland, 7=Sark, 9=Alderney, 10=Channel Islands).
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
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.
dateOfEntryIntoUK	string<date>	No	Required when acceptanceType is immigrant.
dateOfLeavingUK	string<date>	No
medicationDispensedByPractice	boolean	Yes
previousHomeAddress	object	No	Required when acceptanceType is transfer-in or ex-services.
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.

23 possible code values

Code	Description	When
missing-first-name	The firstName is required.	firstName is blank
missing-last-name	The lastName is required.	lastName is blank
missing-gender	The gender is required.	gender is blank
invalid-gender	The gender is required and must be a recognised value.	gender is present but not one of male, female, indeterminate
invalid-date-of-birth	The dateOfBirth is not a valid date in Y-m-d format.	dateOfBirth is present but not a valid date in Y-m-d format
missing-place-of-birth-country	The placeOfBirthCountry is required.	placeOfBirthCountry is blank
invalid-place-of-birth-country	The placeOfBirthCountry is required and must be a recognised value.	placeOfBirthCountry is present but not a recognised value
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-current-home-address	The currentHomeAddress is required, with at least line1.	currentHomeAddress (or its line1) is missing when required
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
possible-duplicate-patient	An existing patient was found with the same family name and date of birth. Use match-patient to check for an existing record before registering a new one.	an existing patient already matches on family name and date of birth

Response fields

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

{
  "errors": [
    {
      "code": "missing-first-name",
      "description": "The firstName is required."
    }
  ]
}

403 The call is application-restricted rather than user-restricted.

Response fields

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

{
  "errors": [
    {
      "code": "application-restricted-not-supported",
      "description": "This endpoint is only available to user-restricted callers."
    }
  ]
}

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."
    }
  ]
}