Basic information about JoinedUp's public APIs can be found here. On that page you'll find the different URLs and parameters for our various APIs.
Timesheets API
The most commonly used API is the Timesheets API. If you want to request timesheets for the default week (the default week being the previous week) via API, you would use http://api.joinedup.com/v1/timesheets. This URL is entered into an application such as Postman, and you then enter the header. The header includes 'x-api-key', which indicates that the API key is coming, and then the value, which is the key itself, which looks like a long string of letters and numbers. It functions a bit like a password.
To request timesheets for a specific week, simply add the week and year to the end of the URL eg http://api.joinedup.com/v1/timesheets/09/2022.
If you're experiencing issues requesting data with this API please ensure that the header and value are correct: the header should be 'x-api-key' and the value should be the key itself.
API Response codes
Below are the various response codes for our public APIs. This may help identify the source of any issues you're having.
Command | API response | What this means |
GET /timesheets {isoWeek} / {lastModifiedDate} | 200 | The request to JoinedUp for the specified week or last modified date was completed successfully. |
GET /timesheets {isoWeek} / {lastModifiedDate} | 404 | The request to JoinedUp was 'not found' based on the parameters sent. This often indicates that there is something wrong with the parameters, or that the API is being called before there is any data for the week in question. |
GET /workers {JoinedUpId} | 200 | The request to JoinedUp for a specific worker ID was completed successfully. |
GET /workers {JoinedUpId} | 404 | The ID sent was not found on the JoinedUp side. |
GET /workers/ref_id/{refId} | 200 | The request to JoinedUp based on the agency's candidate ID was completed successfully. |
GET /workers/ref_id/{refId} | 400 | Invalid date. The worker is no longer linked to the agency's org. |
GET /workers/ref_id/{refId} | 404 | Not found. There's no match in JoinedUp for the agency's candidate ID sent. |
PUT /workers | 200 | The request sent to JoinedUp was successful - either completely or partially. If the request sends only the mandatory fields for JoinedUp, but not the optional ones, it will still save the worker. The API request will need to be checked if expected data was not received - it is likely the correct data was not included. |
PUT /workers | 400 | Invalid JSON input. One or more of the fields were not submitted to the API in the correct format. Check the API request. |
PUT /workers/attachments/{workerId} | 200 | The request to save a document or documents against a JoinedUp worker ID was successful. |
PUT /workers/attachments/{workerId} | 400 | Invalid input. The request to JoinedUp was not in the correct format. Check the API request. |
PUT /workers/attachments/{workerId} | 404 | Worker not found. There was no worker in JoinedUp matching the requested ID. |