Integration API (People)

Please note: the Integration API (People) is still in development. If you would like more information about it, please contact your Account Manager

Base URLs

Integration API:

https://integration-api.rotamasterweb.co.uk

Data API:

https://data-api.rotamasterweb.co.uk

Authentication

All requests to our APIs must be authenticated using a JWT (JSON Web Token). To obtain a JWT, you must first call the Authentication Endpoint with your credentials.

Authentication Endpoint

POST /api/Authentication

API keys are specific to your organisation and will be provided by RotaMaster. Please contact your Account Manager if you do not already have them.

Request Payload

{ "apiKey": "string-value-provided-by-account-manager", "accessKey": "string-value-provided-by-account-manager", "entId": numeric-value-provided-by-account-manager }

Example Request

{ "apiKey": "ExampleApiKeyExampleApiKeyExampleApiKey", "accessKey": "ExampleAccessKeyExampleAccessKey", "entId": 999 }

Response (200)

{ "your-jwt-token" }

Example Response

{ "eyJhbEXAMPLEkpXVCJ9.eyJDdXN0b2EXAMPLEdGFtYXN0ZXJ3ZrLyJ9.FUjEXAMPLEt1I" }

Include the JWT in the Authorization header of all subsequent requests:

Authorization: Bearer <your-jwt-token>

Data Submission to RotaMaster

When you send data to be created in RotaMaster, it will not be processed immediately. Instead, it will be queued and processed by a background job that runs every 10 minutes.

New Personnel

POST /api/People

Fields

Field Name	Field Type	Mandatory	Additional Notes
referenceId	string	Y	3rd party system ID
titleId	string	Y	See Data required from DAPI section
firstName	string	Y
middleName	string	N
surname	string	Y
knownAs	string	N
previousSurname	string	N
dateOfBirth	DateTime	N	Accepts "yyyy-MM-dd" and "yyyy-MM-ddTHH:mm:ss.fff" ISO 8601 formats
genderId	string	N	See Data required from DAPI section
startDate	DateTime	Y	Accepts "yyyy-MM-dd" and "yyyy-MM-ddTHH:mm:ss.fff" ISO 8601 formats
continuousServiceDate	DateTime	Y	Accepts "yyyy-MM-dd" and "yyyy-MM-ddTHH:mm:ss.fff" ISO 8601 formats. Must be on or before startDate.
primaryRotaGroupId	string	Y	See Data required from DAPI section
secondaryRotaGroupIds	string[array]	N	See Data required from DAPI section
teamId	string	Y	See Data required from DAPI section
leaveYearStartDate	DateTime	N	Accepts "yyyy-MM-dd" and "yyyy-MM-ddTHH:mm:ss.fff" ISO 8601 formats. Defaults to Primary Rota Group leave year start if not provided.
payrollId	string	N	See Errors and Validation section
nationalInsuranceNumber	string	N	See Errors and Validation section

Errors and Validation

Field Name	Validation
referenceId	Required
referenceId	Maximum length of 50 characters
titleId	Required
titleId	Title must exist
firstName	Required
surname	Required
startDate	Required
startDate	Must be valid date format
continuousServiceDate	Required
continuousServiceDate	Must be valid date format
continuousServiceDate	Must be on or before startDate
primaryRotaGroupId	Required
primaryRotaGroupId	Rota group must exist
primaryRotaGroupId	Rota group must not be hidden
secondaryRotaGroupID	Rota group must exist
secondaryRotaGroupID	Rota group must not be hidden
teamId	Required
teamId	Team must exist
dateOfBirth	Must be valid date format
genderId	Gender must exist
leaveYearStartDate	Must be valid date format
payrollId	Must be unique
nationalInsuranceNumber	Valid NI number in string format - "AA000000A" where A = letter, 0 = digit

Example Request Payload

[ { "referenceId": "string", "titleId": "string", "firstName": "string", "middleName": "string", "surname": "string", "knownAs": "string", "previousSurname": "string", "dateOfBirth": "2025-10-01T15:19:55.388Z", "genderId": "string", "startDate": "2025-10-01T15:19:55.388Z", "continuousServiceDate": "2025-10-01T15:19:55.388Z", "primaryRotaGroupId": "string", "secondaryRotaGroupIds": ["string"], "teamId": "string", "leaveYearStartDate": "2025-10-01T15:19:55.388Z", "payrollId": "string", "nationalInsuranceNumber": "string" } ]

Data Required from DAPI

For the following fields, utilise the relevant externalId in the response when creating your request with the Integration API.

titleId — GET /api/Title

[ { "externalId": "72f184ce-6686-42af-a9e3-09fd31e14b5b", "name": "Mr" }, { "externalId": "4179378f-5be3-4be0-8ec5-5c0e662cfc90", "name": "Mrs" }, { "externalId": "faf0921d-32e7-42d5-90ab-6d9102b29cf0", "name": "Miss" }, { "externalId": "19007846-dc41-4fec-a243-96abdbe120d6", "name": "Ms" }, { "externalId": "3b587a2a-3e2f-445d-a0a4-3489b7dcb88b", "name": "Dr" }, { "externalId": "dec7efe5-6f87-46cc-966e-24b556d05158", "name": "Rev" } ]

genderId — GET /api/Gender

[ { "externalId": "b2996e75-4ff3-4a7f-a774-bb81f6a3101d", "name": "Male" }, { "externalId": "a0c17e1a-8b22-4eef-828c-72ff6df29048", "name": "Female" }, { "externalId": "41d99d3e-6d9e-4b2f-8279-13a982d3dad8", "name": "Unknown" }, { "externalId": "5d2db3d0-e5d4-4132-9127-b65eb76d6e76", "name": "Transgender" }, { "externalId": "0f5d80b3-902d-429a-a6d8-b634b234d18e", "name": "Fluid" } ]

primaryRotaGroupId / secondaryRotaGroupIds — GET /api/RotaGroup

[ { "id": 70, "externalId": "b280e96f-56b7-4d3d-b3a5-67fcce9b3d6d", "name": "2022 Summer Cover" }, { "id": 20, "externalId": "e8d87927-1a3e-4f9c-abc5-3ef4e2c007d2", "name": "A+E Hub" }, { "id": 12, "externalId": "e4b0fc14-220c-41b0-aec0-60b38082e550", "name": "Access Anywhere" } ]

teamId — GET /api/Team

[ { "externalId": "c035bd5f-c488-4cdb-b170-292b0334fdc0", "name": "1.Blue Team AUX", "rotaGroup": { "id": 14, "externalId": "6a2593bc-e2eb-47c3-8d31-4133a8f97e7f", "name": "Walk In Centre" } }, { "externalId": "ad3ba557-cdb2-43d7-a21c-90856a285999", "name": "1.Blue Team S/N", "rotaGroup": { "id": 14, "externalId": "6a2593bc-e2eb-47c3-8d31-4133a8f97e7f", "name": "Walk In Centre" } } ]

Locations of References in RotaMaster

Field Name	Where data will be put in RotaMaster
titleId	Personnel Record > Personal Details
firstName	Personnel Record > Personal Details
middleName	Personnel Record > Personal Details
surname	Personnel Record > Personal Details
knownAs	Personnel Record > Personal Details
previousSurname	Personnel Record > Personal Details
dateOfBirth	Personnel Record > Personal Details
genderId	Personnel Record > Personal Details
startDate	Personnel Record > Employment Details
continuousServiceDate	Personnel Record > Employment Details
primaryRotaGroupId	Personnel Record > Multi Rota Group
secondaryRotaGroupIds	Personnel Record > Multi Rota Group
teamId	Personnel Record > Rota Group > Team
leaveYearStartDate	Personnel Record > Absences > Leave Settings
payrollId	Personnel Record > Personal > Finance References
nationalInsuranceNumber	Personnel Record > Finance References

Update Personnel

PUT /api/People/{ExternalId}

Fields

Field Name	Field Type	Mandatory	Additional Notes
referenceId	string	Y	Third party ID
titleId	string	Y	See Data required from DAPI section
firstName	string	Y
middleName	string	N
surname	string	Y
knownAs	string	N
previousSurname	string	N
dateOfBirth	DateTime	N	ISO 8601 formats accepted
genderId	string	N	See Data required from DAPI section
startDate	DateTime	Y	ISO 8601 formats accepted
continuousServiceDate	DateTime	Y	Must be on or before startDate
primaryRotaGroupId	string	Y	See Data required from DAPI section
secondaryRotaGroupIds	string[]	N	See Data required from DAPI section
teamId	string	Y	See Data required from DAPI section
leaveYearStartDate	DateTime	N	Defaults to Primary Rota Group leave year start if not provided
payrollId	string	N	See Errors and Validation section
nationalInsuranceNumber	string	N	See Errors and Validation section

Errors and Validation

Field Name	Validation
externalId	Required
referenceId	Required
referenceId	Maximum length of 50 characters
referenceId	If the person has been previously created via IAPI this must equal the referenceId from the Create endpoint
titleId	Required
titleId	Title must exist
firstName	Required
surname	Required
startDate	Required
startDate	Must be valid date format
continuousServiceDate	Required
continuousServiceDate	Must be valid date format
continuousServiceDate	Must be on or before startDate
primaryRotaGroupId	Required
primaryRotaGroupId	Rota group must exist
teamId	Required
teamId	Team must exist
dateOfBirth	Must be valid date format
genderId	Gender must exist
leaveYearStartDate	Must be valid date format
payrollId	Must be unique
nationalInsuranceNumber	Valid NI number in string format - "AA000000A" where A = letter, 0 = digit

Example Request Payload

{ "referenceId": "string", "titleId": "string", "firstName": "string", "middleName": "string", "surname": "string", "knownAs": "string", "previousSurname": "string", "dateOfBirth": "2025-10-01T15:16:26.017Z", "genderId": "string", "startDate": "2025-10-01T15:16:26.017Z", "continuousServiceDate": "2025-10-01T15:16:26.017Z", "primaryRotaGroupId": "string", "secondaryRotaGroupIds": ["string"], "teamId": "string", "leaveYearStartDate": "2025-10-01T15:16:26.017Z", "payrollId": "string", "nationalInsuranceNumber": "string" }

Data Required from DAPI

externalId — GET /api/People/PersonIds

[ { "personId": 0, "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "string" } ]

(titleId, genderId, primaryRotaGroupId, secondaryRotaGroupIds, teamId — same endpoints as New Personnel above)

Locations of References in RotaMaster

Field Name	Where data will be put in RotaMaster
titleId	Personnel Record > Personal Details
firstName	Personnel Record > Personal Details
middleName	Personnel Record > Personal Details
surname	Personnel Record > Personal Details
knownAs	Personnel Record > Personal Details
previousSurname	Personnel Record > Personal Details
dateOfBirth	Personnel Record > Personal Details
genderId	Personnel Record > Personal Details
startDate	Personnel Record > Employment Details
continuousServiceDate	Personnel Record > Employment Details
primaryRotaGroupId	Personnel Record > Multi Rota Group
secondaryRotaGroupIds	Personnel Record > Multi Rota Group
teamId	Personnel Record > Rota Group > Team
leaveYearStartDate	Personnel Record > Absences > Leave Settings
payrollId	Personnel Record > Personal > Finance References
nationalInsuranceNumber	Personnel Record > Finance References

Assign Post

POST /api/People/{PersonExternalId}/Post

Fields

Field Name	Field Type	Mandatory	Additional Notes
postId	string	Y	See Data required from DAPI section
postStartDate	DateTime	Y	ISO 8601 formats accepted. Start date must be before End Date.
postEndDate	DateTime	N	ISO 8601 formats accepted. End date must be after Start date.
contractedHours	Number	N	Defaults to contracted hours from main Post contract if not provided
customPostName	string	N
isPrimaryPost	Boolean	N	Defaults to true

Errors and Validation

Field Name	Validation
personExternalId	Required
personExternalId	Person exists
personExternalId	Person has required skills for the post
postId	Required
postId	Post is not already assigned to a person
postId	Post exists
postId	Post has enough empty spaces
postStartDate	Required
postStartDate	Start Date is before End Date
postEndDate	End Date is after Start Date

Example Request Payload

[ { "postId": "string", "postStartDate": "2025-07-31T14:18:25.324Z", "postEndDate": "2025-07-31T14:18:25.324Z", "contractedHours": 0, "customPostName": "string", "isPrimaryPost": true } ]

Data Required from DAPI

personExternalId — GET /api/People/PersonIds

[ { "personId": 0, "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "string" } ]

postId — GET /api/Post

[ { "externalId": "22550d88-e6f2-4c54-9c67-a627937c91f7", "postReference": "100000", "internalReference": "test333", "postName": "Bank Doctor", "validFromDate": "2017-10-01T00:00:00", "validToDate": null, "postHours": 12, "noPositions": 1000 }, { "externalId": "713e9a13-968d-4875-9683-1b430b22da8e", "postReference": "100001", "postName": "Doctor", "validFromDate": "2013-09-01T00:00:00", "postHours": 37.5, "noPositions": 2000 } ]

Locations of References in RotaMaster

Field Name	Where data will be put in RotaMaster
postName	Personnel Record > Posts
postStartDate	Personnel Record > Posts > Details > Dates > Commence
postEndDate	Personnel Record > Posts > Details > Dates > End
contractedHours	Personnel Record > Posts > Contract > Contract Hours
customPostName	Personnel Record > Posts > Details > Post Name

Create Post

POST /api/Post

Fields

Field Name	Field Type	Mandatory	Additional Notes
referenceId	string	Y	Third party ID. Must be unique, max 50 characters.
postName	string	Y	Must be unique
locationId	string	Y	See Data required from DAPI section
startDate	DateTime	Y	ISO 8601 formats accepted

Errors and Validation

Field Name	Validation
referenceId	Required
referenceId	Must be unique
referenceId	Maximum length of 50 characters
postName	Required
postName	Must be unique
locationId	Required
locationId	Location must exist
startDate	Required

Example Request Payload

[ { "referenceId": "string", "postName": "string", "locationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "startDate": "2025-10-01T15:22:57.308Z" } ]

Data Required from DAPI

locationId — GET /api/Location

[ { "externalId": "453221ce-d9a4-46c9-8f04-4f8293800a80", "name": "Usual Place of Work", "locationType": { "externalId": "01ad45fa-617d-4660-8b71-9ee1d74f181e", "name": "Usual Place of Work" } }, { "externalId": "4ccf990e-add9-44b0-957c-25446c65d691", "name": "3 South View Road", "locationType": { "externalId": "4c286564-11f9-4e1f-a815-7558b269456d", "name": "Work from Home" } } ]

Locations of References in RotaMaster

Field Name	Where data will be put in RotaMaster
postName	Personnel > Post Manager
locationId	Personnel > Post Manager > Post > Location
startDate	Personnel > Post Manager > Post > Start Date

Create Role

POST /api/Role

Fields

Field Name	Field Type	Mandatory	Additional Notes
referenceId	string	Y	Third Party ID. Max 50 characters.
roleName	string	Y	Unique name, max 255 characters
nominalCode	string	N	Unique if provided, max 10 characters

Errors and Validation

Field Name	Validation
referenceId	Required
referenceId	Maximum length 50 characters
roleName	Required
roleName	Unique name
roleName	Name less than or equal to 255 characters
nominalCode	Unique if provided
nominalCode	Nominal code less than or equal to 10 characters

Example Request Payload

[ { "referenceId": "string", "roleName": "string", "nominalCode": "string" } ]

Checking Processing Status and Error Details

To check whether your data was successfully processed or encountered an error, use the Errors Endpoint with the GUID returned from the submission endpoint.

For example, if you called POST /api/Role and received:

{ "data": "4d743f26-e74a-4e84-8e80-15ab575b806a", "errors": [], "message": "Data created successfully", "statusCode": 201 }

Take the GUID from the data field and use it as {id} in the Errors endpoint below.

Errors Endpoint

GET /api/Integration/Batch/{id}/Errors

Example Processing Pending Response (200)

{ "data": [ { "integrationId": "ABC1234", "entityType": "Person", "errorCode": "Pending", "errorMessage": "This entity is pending processing so has not been actioned yet." } ], "errors": [], "message": "Data retrieved successfully", "statusCode": 200 }

Example Processing Success Response (200)

{ "data": [], "errors": [], "message": "Data retrieved successfully", "statusCode": 200 }

Example Processing Error Response (200)

{ "data": [ { "integrationId": "ABC1234", "entityType": "Person", "errorCode": "REF001", "errorMessage": "Create error: Reference Id for Gender does not exist." } ], "errors": [], "message": "Data retrieved successfully", "statusCode": 200 }

Example Error Response (400)

{ "data": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": ["RequestAudit cannot be found"], "message": null, "statusCode": 400 }

Processing Notes

The background processing job runs every 10 minutes.
Data submitted will appear as "queued" initially.
Use the GUID to poll the status endpoint until the result is available.
Error details are available only if the final result is "error".

Integration API (People)

This document provides detailed instructions for integrating with the RotaMaster application via RESTful APIs. It outlines how to authenticate, interact with the available endpoints, and understand the processing lifecycle for data submitted to the RotaMaster system.

Contents:

Base URLs

Authentication

Authentication Endpoint

New Personnel

Fields

Errors and Validation

Example Request Payload

Data Required from DAPI

Locations of References in RotaMaster

Update Personnel

Fields

Errors and Validation

Example Request Payload

Data Required from DAPI

Locations of References in RotaMaster

Assign Post

Fields

Errors and Validation

Example Request Payload

Data Required from DAPI

Locations of References in RotaMaster

Create Post

Fields

Errors and Validation

Example Request Payload

Data Required from DAPI

Locations of References in RotaMaster

Create Role

Fields

Errors and Validation

Example Request Payload

Checking Processing Status and Error Details

Errors Endpoint

Example Processing Pending Response (200)

Example Processing Success Response (200)

Example Processing Error Response (200)

Example Error Response (400)

Processing Notes