{"openapi":"3.0.3","info":{"title":"Staff Index API","description":"## Overview\nA centralised staff index and provisioning system for NHS England. This service manages identity records and provisions accounts to external systems such as Local AD and NHS.net Connect.\n\nYou can:\n- Create new staff records\n- Search for existing staff records\n\n## Who can use this API\nDuring Private Beta, access is closed to a select few applications.\n\n## API status and roadmap\nThis API is [In development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n\nIf you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support).\n\n## Service level\nThis API is a bronze service during private beta, meaning it is operational and supported only during business hours (8am to 6pm), Monday to Friday excluding bank holidays.\n(The planned production service level will be platinum.)\n\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Network access\nThis API is available on the internet.\n\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Security and authorisation\nThis API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user.\n\nTo use this API, use the following security pattern:\n\n* [Application-restricted RESTful APIs - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)\n\n## Environments and testing\n| Environment       | Base URL                                     |\n| ----------------- | ---------------------------------------------|\n| Integration test  | `https://int.api.service.nhs.uk/staff-index` |\n| Production        | `https://api.service.nhs.uk/staff-index`     |\n\n### Sandbox testing\nWe currently do not have a [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing).\n\n### Integration testing\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):\n- is for formal integration testing\n- requires application authentication\n\nThis environment will persist records, however, the environment is periodically reset so records can be removed at any time.\n\nAnyone can register and create an access app for the integration environment following the onboarding instructions below. The API is listed as \"Staff Index - Application Restricted (Integration)\".\n\n## Onboarding\n\n1. Login to the developer platform and create an access app connected to the Staff Index API - https://onboarding.prod.api.platform.nhs.uk/\n2. Create and assign a Product ID to access app through [ServiceNow](https://www.support.internalservices.england.nhs.uk/nhs_digital?id=sc_cat_item&sys_id=6e048d0797d8cb94dd80f2df9153af0c)\n3. Follow these instructions for setting up signed JWT auth - https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication\n","version":"0.0.1"},"servers":[{"url":"/"}],"paths":{"/Person/{personUniqueIdentifier}":{"get":{"tags":["Person"],"summary":"Retrieve Person record","description":"Retrieve related records of a Person by their unique identifier.","operationId":"get_person_Person__personUniqueIdentifier__get","parameters":[{"name":"personUniqueIdentifier","in":"path","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"title":"Personuniqueidentifier","type":"string"}}],"responses":{"422":{"description":"Unprocessable Entity/Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityResponse"}}}},"200":{"description":"Person record retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPersonResponse"}}}},"404":{"description":"Staff identity record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}}},"deprecated":false}},"/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"The health check endpoint confirms the backend is reachable via the API and returns basic information about the service status.","operationId":"get_health_health_get","responses":{"422":{"description":"Unprocessable Entity/Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityResponse"}}}},"200":{"description":"Health check response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}}},"deprecated":false}},"/Person":{"post":{"tags":["Person"],"summary":"Create a new Person record","description":"This is the root level record for a person in the Staff Index that represents personal information that does not vary between roles or organisations.\nA Person record may be linked to multiple ServicePerson records.","operationId":"create_person_Person_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonRequest"}}},"required":true},"responses":{"422":{"description":"Unprocessable Entity/Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityResponse"}}}},"201":{"description":"Person record created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonResponse"}}}},"200":{"description":"Person record not created due to filter policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonFilteredResponse"}}}},"409":{"description":"Duplicate record or constraint violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}}},"deprecated":false}},"/ServicePerson":{"get":{"tags":["Service Person"],"summary":"Retrieve ServicePerson record","description":"Retrieve a ServicePerson record by the person's unique identifier and the organisation's ODS code.\nThis will also return details of any provisioned accounts.","operationId":"get_service_person_ServicePerson_get","parameters":[{"name":"personUniqueIdentifier","in":"query","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"title":"Personuniqueidentifier","type":"string"}},{"name":"odsCode","in":"query","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"title":"Odscode","type":"string"}}],"responses":{"422":{"description":"Unprocessable Entity/Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityResponse"}}}},"200":{"description":"Service Person record retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetServicePersonResponse"}}}},"404":{"description":"Staff identity record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}}},"deprecated":false},"post":{"tags":["Service Person"],"summary":"Create a new ServicePerson record","description":"The ServicePerson record represents a person's relationship with an organisation and must be linked to a Person record.\nThis endpoint may also trigger provisioning events to external systems.","operationId":"provision_service_person_ServicePerson_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServicePersonRequest"}}},"required":true},"responses":{"422":{"description":"Unprocessable Entity/Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityResponse"}}}},"201":{"description":"Service Person record created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServicePersonResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponse"}}}}},"deprecated":false}}},"components":{"schemas":{"CimProfileType":{"title":"CimProfileType","enum":["Standard","TAC","RPA"],"type":"string","description":"Valid CIM profile type values."},"CimServicePersonRequest":{"title":"CimServicePersonRequest","type":"object","properties":{"uuid":{"title":"Uuid","pattern":"^.{1,100}$","type":"string","description":"CIM UUID (up to 100 characters)","nullable":true},"profileType":{"allOf":[{"$ref":"#/components/schemas/CimProfileType"}],"description":"CIM profile type. Accepts canonical names (Standard, TAC, RPA) or legacy numbered values (1, 2, 3). Numbered values are mapped to their canonical equivalents.","nullable":true,"examples":["Standard","TAC","RPA","1","2","3"]},"statusId":{"allOf":[{"$ref":"#/components/schemas/CimStatus"}],"description":"CIM status (1 = Open, 2 = Closed)","nullable":true,"examples":["1","2"]}},"additionalProperties":false,"description":"CIM ServicePerson data."},"CimServicePersonResponse":{"title":"CimServicePersonResponse","type":"object","properties":{"uuid":{"title":"Uuid","type":"string","nullable":true},"profileType":{"title":"Profiletype","type":"string","nullable":true},"statusId":{"title":"Statusid","type":"string","nullable":true},"contact":{"allOf":[{"$ref":"#/components/schemas/ContactResponse"}],"nullable":true}}},"CimStatus":{"title":"CimStatus","enum":["1","2"],"type":"string","description":"Valid CIM status values."},"ConflictResponse":{"title":"ConflictResponse","required":["message"],"type":"object","properties":{"message":{"title":"Message","type":"string"}}},"ContactRequest":{"title":"ContactRequest","type":"object","properties":{"emailAddress":{"title":"Emailaddress","pattern":"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$","type":"string","description":"Valid email address with @ symbol and TLD","nullable":true,"examples":["john.doe@nhs.net","staff@example.com"]},"mobileNumber":{"title":"Mobilenumber","pattern":"^\\+?[1-9]\\d{1,14}$","type":"string","description":"Valid mobile phone number in E.164 format","nullable":true,"examples":["+447911123456","07911123456"]}},"additionalProperties":false,"description":"Contact information for a person."},"ContactResponse":{"title":"ContactResponse","type":"object","properties":{"emailAddress":{"title":"Emailaddress","type":"string","nullable":true},"mobileNumber":{"title":"Mobilenumber","type":"string","nullable":true}}},"CreatePersonFilteredResponse":{"title":"CreatePersonFilteredResponse","type":"object","properties":{"message":{"title":"Message","type":"string","default":"Person record not created as its source was not AfCID"}}},"CreatePersonResponse":{"title":"CreatePersonResponse","required":["person"],"type":"object","properties":{"person":{"$ref":"#/components/schemas/PersonResponse"}}},"CreateServicePersonResponse":{"title":"CreateServicePersonResponse","required":["servicePerson"],"type":"object","properties":{"servicePerson":{"$ref":"#/components/schemas/ServicePersonResponse"}}},"DigitalIdentityRequest":{"title":"DigitalIdentityRequest","required":["identityAssuranceSource","eGifReg"],"type":"object","properties":{"identityAssuranceSource":{"$ref":"#/components/schemas/IdentityAssuranceSource","examples":["1","3","4"],"description":"Source of identity assurance (1 = CareID, 2 = ESR, 3 = CIM, 4 = SSR/AfCID)"},"eGifReg":{"$ref":"#/components/schemas/EGifReg","examples":[0,1,3],"description":"eGIF registration level (0, 1, or 3)"},"identityAssuranceLevel":{"allOf":[{"$ref":"#/components/schemas/IdentityAssuranceLevel"}],"description":"Identity assurance level","nullable":true,"examples":["IAL_1","GPG45_VERY_HIGH"]}},"additionalProperties":false,"description":"Digital identity information for a person."},"DigitalIdentityResponse":{"title":"DigitalIdentityResponse","required":["identityAssuranceSource","eGifReg"],"type":"object","properties":{"identityAssuranceSource":{"title":"Identityassurancesource","type":"string"},"eGifReg":{"title":"Egifreg","type":"integer"},"identityAssuranceLevel":{"title":"Identityassurancelevel","type":"string","nullable":true}}},"EGifReg":{"title":"EGifReg","enum":[0,1,3],"type":"integer","description":"Valid eGIF registration level values."},"GetPersonResponse":{"title":"GetPersonResponse","required":["person"],"type":"object","properties":{"person":{"$ref":"#/components/schemas/PersonResponse"}}},"GetServicePersonResponse":{"title":"GetServicePersonResponse","required":["servicePerson"],"type":"object","properties":{"servicePerson":{"$ref":"#/components/schemas/ServicePersonResponse"}}},"HTTPValidationError":{"title":"HTTPValidationError","type":"object","properties":{"detail":{"title":"Detail","type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}},"HealthResponse":{"title":"HealthResponse","required":["status","service","commit","timestamp"],"type":"object","properties":{"status":{"$ref":"#/components/schemas/HealthStatus"},"service":{"title":"Service","type":"string"},"commit":{"title":"Commit","type":"string"},"timestamp":{"title":"Timestamp","type":"string"}}},"HealthStatus":{"title":"HealthStatus","enum":["pass","fail"],"type":"string"},"IdentityAssuranceLevel":{"title":"IdentityAssuranceLevel","enum":["IAL_1","IAL_2","IAL_3","GPG45_LOW","GPG45_MEDIUM","GPG45_HIGH","GPG45_VERY_HIGH"],"type":"string"},"IdentityAssuranceSource":{"title":"IdentityAssuranceSource","enum":["1","2","3","4"],"type":"string","description":"Valid identity assurance source values."},"InternalServerErrorResponse":{"title":"InternalServerErrorResponse","required":["message"],"type":"object","properties":{"message":{"title":"Message","type":"string"}}},"NotFoundResponse":{"title":"NotFoundResponse","required":["message"],"type":"object","properties":{"message":{"title":"Message","type":"string"}}},"PersonRecordLifecycleRequest":{"title":"PersonRecordLifecycleRequest","required":["creationOrganisationOdsCode","actualCreationDate"],"type":"object","properties":{"creationOrganisationOdsCode":{"title":"Creationorganisationodscode","pattern":"^[A-Za-z0-9]{3,10}$","type":"string","description":"ODS code of the organisation that created the record","examples":["RKE","7A4BV"]},"creationOrganisationName":{"title":"Creationorganisationname","type":"string","description":"Name of the organisation that created the record","nullable":true,"examples":["NHS Trust"]},"actualCreationDate":{"title":"Actualcreationdate","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}","type":"string","description":"Actual creation date in ISO 8601 format","examples":["2026-01-15T10:30:00"]}},"additionalProperties":false,"description":"Lifecycle metadata for the person record."},"PersonRecordLifecycleResponse":{"title":"PersonRecordLifecycleResponse","required":["creationOrganisationOdsCode","actualCreationDate"],"type":"object","properties":{"creationOrganisationOdsCode":{"title":"Creationorganisationodscode","type":"string"},"creationOrganisationName":{"title":"Creationorganisationname","type":"string","nullable":true},"actualCreationDate":{"title":"Actualcreationdate","type":"string"}}},"PersonRequest":{"title":"PersonRequest","required":["legalFirstName","legalSurname","dateOfBirth","digitalIdentity","personRecordLifecycle"],"type":"object","properties":{"title":{"allOf":[{"$ref":"#/components/schemas/Title"}],"description":"Title/salutation for the person","nullable":true,"examples":["Mr","Mrs","Dr"]},"legalFirstName":{"title":"Legalfirstname","maxLength":35,"pattern":"^[A-Za-z' -]+$","type":"string","description":"Legal first name"},"legalMiddleName":{"title":"Legalmiddlename","maxLength":35,"pattern":"^[A-Za-z' -]+$","type":"string","description":"Legal middle name","nullable":true},"legalSurname":{"title":"Legalsurname","maxLength":35,"minLength":2,"pattern":"^[A-Za-z' -]+$","type":"string","description":"Legal surname"},"preferredName":{"title":"Preferredname","maxLength":35,"pattern":"^[A-Za-z' -]+$","type":"string","description":"Preferred first name (name on smartcard)","nullable":true},"dateOfBirth":{"title":"Dateofbirth","pattern":"^\\d{4}-\\d{2}-\\d{2}$","type":"string","description":"Date of birth in ISO 8601 format (YYYY-MM-DD)","examples":["1980-12-31","1995-06-15"]},"nationalInsuranceNumber":{"title":"Nationalinsurancenumber","pattern":"^[A-CEGHJ-PR-TW-Z][A-CEGHJ-NPR-TW-Z][0-9]{6}[A-D]$","type":"string","description":"National Insurance Number in format: 2 letters, 6 digits, 1 letter (e.g., AB123456C)","nullable":true,"examples":["AB123456C","JY987654D"]},"contact":{"allOf":[{"$ref":"#/components/schemas/ContactRequest"}],"nullable":true},"digitalIdentity":{"$ref":"#/components/schemas/DigitalIdentityRequest"},"personRecordLifecycle":{"$ref":"#/components/schemas/PersonRecordLifecycleRequest"},"cimServicePerson":{"allOf":[{"$ref":"#/components/schemas/CimServicePersonRequest"}],"nullable":true}},"additionalProperties":false,"description":"Request model for creating a new staff identity record with validation.\nThis follows the logical data model (see linked MSI Data attributes table for details of mandatory/optional fields)\nhttps://nhsd-confluence.digital.nhs.uk/spaces/MSI/pages/1177387364/Logical+Data+Model\nValidation logic is currently following the CIM API\nhttps://nhsd-confluence.digital.nhs.uk/spaces/CIS/pages/456434755/CIM+-+API+-+Create+User"},"PersonResponse":{"title":"PersonResponse","required":["personUniqueIdentifier","legalFirstName","legalSurname","dateOfBirth","digitalIdentity","personRecordLifecycle"],"type":"object","properties":{"personUniqueIdentifier":{"title":"Personuniqueidentifier","type":"string"},"title":{"title":"Title","type":"string","nullable":true},"legalFirstName":{"title":"Legalfirstname","type":"string"},"legalMiddleName":{"title":"Legalmiddlename","type":"string","nullable":true},"legalSurname":{"title":"Legalsurname","type":"string"},"preferredName":{"title":"Preferredname","type":"string","nullable":true},"dateOfBirth":{"title":"Dateofbirth","type":"string"},"nationalInsuranceNumber":{"title":"Nationalinsurancenumber","type":"string","nullable":true},"cimServicePerson":{"allOf":[{"$ref":"#/components/schemas/CimServicePersonResponse"}],"nullable":true},"digitalIdentity":{"$ref":"#/components/schemas/DigitalIdentityResponse"},"personRecordLifecycle":{"$ref":"#/components/schemas/PersonRecordLifecycleResponse"}}},"ServiceAccounts":{"title":"ServiceAccounts","required":["serviceType","provisioningStatus"],"type":"object","properties":{"serviceType":{"title":"Servicetype","type":"string"},"provisioningStatus":{"title":"Provisioningstatus","type":"string"}}},"ServicePersonRequest":{"title":"ServicePersonRequest","required":["personUniqueIdentifier","odsCode","serviceLevelUserName","cimProfileType","isEnabled"],"type":"object","properties":{"personUniqueIdentifier":{"title":"Personuniqueidentifier","type":"string","description":"Person Unique Identifier (PUID) assigned to the staff identity","examples":["U.AB-12-CD"]},"odsCode":{"title":"Odscode","pattern":"^[A-Za-z0-9]{3,10}$","type":"string","description":"ODS (Organisation Data Service) code","examples":["RKE","7A4BV"]},"serviceLevelUserName":{"title":"Servicelevelusername","pattern":"^[0-9]{12}$","type":"string","description":"Service level user name (no spaces) (specific to CIM)","examples":["656036872984"]},"cimProfileType":{"$ref":"#/components/schemas/CimProfileType","examples":["Standard","TAC","RPA"],"description":"Variant type"},"displayName":{"title":"Displayname","type":"string","description":"TBC","nullable":true},"employeeNumber":{"title":"Employeenumber","type":"string","description":"Employee number","nullable":true,"examples":["123456"]},"jobTitle":{"title":"Jobtitle","type":"string","description":"TBC","nullable":true},"professionalCategory":{"title":"Professionalcategory","type":"string","description":"TBC","nullable":true},"employmentType":{"title":"Employmenttype","type":"string","description":"TBC","nullable":true},"isEnabled":{"title":"Isenabled","type":"boolean","description":"Indicates whether the account is active or closed"}},"additionalProperties":false,"description":"Request model for creating a new staff identity record with validation.\nThis follows the logical data model (see linked MSI Data attributes table for details of mandatory/optional fields)\nhttps://nhsd-confluence.digital.nhs.uk/spaces/MSI/pages/1177387364/Logical+Data+Model\nValidation logic is currently following the CIM API\nhttps://nhsd-confluence.digital.nhs.uk/spaces/CIS/pages/456434755/CIM+-+API+-+Create+User#:~:text=%2C%20None%2C%20%22%22-,givenName,-String"},"ServicePersonResponse":{"title":"ServicePersonResponse","required":["personUniqueIdentifier","odsCode","jobTitle","serviceLevelUserName","cimProfileType","displayName","employeeNumber","professionalCategory","employmentType","serviceAccounts"],"type":"object","properties":{"personUniqueIdentifier":{"title":"Personuniqueidentifier","type":"string"},"odsCode":{"title":"Odscode","type":"string"},"jobTitle":{"title":"Jobtitle","type":"string","nullable":true},"serviceLevelUserName":{"title":"Servicelevelusername","type":"string","nullable":true},"cimProfileType":{"title":"Cimprofiletype","type":"string","nullable":true},"displayName":{"title":"Displayname","type":"string","nullable":true},"employeeNumber":{"title":"Employeenumber","type":"string","nullable":true},"professionalCategory":{"title":"Professionalcategory","type":"string","nullable":true},"employmentType":{"title":"Employmenttype","type":"string","nullable":true},"serviceAccounts":{"title":"Serviceaccounts","type":"array","items":{"$ref":"#/components/schemas/ServiceAccounts"},"description":"Unsorted list of service accounts associated with the service person."}}},"Title":{"title":"Title","enum":["Mr","Mrs","Ms","Miss","Dr","Nurse","Sister","Brother","Sir","Canon","Dame","Father","Imam","Lady","Lord","Major","Rabbi","Right Reverend Monsigneur","Reverend","Professor","Baron","Baroness","Mx"],"type":"string","description":"Valid title values for a person."},"UnprocessableEntityResponse":{"title":"UnprocessableEntityResponse","required":["message"],"type":"object","properties":{"message":{"title":"Message","type":"string"},"detail":{"title":"Detail","type":"array","items":{"type":"object","additionalProperties":true},"nullable":true}}},"ValidationError":{"title":"ValidationError","required":["loc","msg","type"],"type":"object","properties":{"loc":{"title":"Location","type":"array","items":{"anyOf":[{"type":"string"},{"type":"integer"}]}},"type":{"title":"Error Type","type":"string"}}},"ResponseValidationError":{"title":"ResponseValidationError","type":"object","properties":{"detail":{"title":"Detail","type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}}},"securitySchemes":{"app-level3":{"$ref":"https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level3"}}},"security":[{"app-level3":[]}],"tags":[{"name":"Health"},{"name":"Person"},{"name":"Service Person"}]}