Table of contents
Migration from Analytics API to Performance and Talent Reporting API
General Notes
The purpose of this guide is to support migration of the legacy Analytics API to the new Performance and Talent Reporting API released in September 2024.
It will cover off the key differences for each endpoint, we would recommend you migrate to the new version at your earliest convenience.
For further information on the End of Life of the Clear Review Analytics API please see here
Base URLs
Old API: https://api.clearreview.com/analytics/data
New API: https://api.clearreview.com/reporting/data/api/v1
Swaggerhub Documentation
Respective Swaggerhub pages are available for full detailed comparison of the query parameters and response format between the old and new API at the URLs below. This also provides an opportunity to experiment with the new API.
Legacy Analytics API https://app.swaggerhub.com/apis-docs/AdvancedComputerSoft/ClearReview_OpenAPI/1.1.5#/
New Performance and Talent Reporting API https://app.swaggerhub.com/apis-docs/AdvancedComputerSoft/performance-and-talent-reporting-api/
Limit/Throttling
The API query rate is now specifically limited to 100/minute, 1000/hour & 10000/day. If you exceed these limits, you will receive a ‘429’ error response (too many requests).
Pagination
All of the new API endpoints which have a response output consisting of a list of multiple data items now involve mandatory pagination, which comprises most endpoints. The default number of returned data items per page is 10, and the maximum you can request is 100 items per page. You can request a specific page by passing the page query parameter. The “pagination” data block, at the end of each response from such endpoints, incorporates full pagination details for the query made, as follows:
"page": The page number of the current response
"perPage": The number of per-page items for the query
"totalPageCount" The total number of response pages available for the query
"totalResultCount": The total number of data items available for the query
We have also removed “next” and “previous” cursor-based pagination (which comprised of API query URLs corresponding to the “Next” and “previous” page of results, relative to the page of the response containing them).
Date/Time formats in queries and response data
American-style date formats - MM/DD/YYYY - are no longer used in queries, and have been fully replaced by international date formats in the form YYYY-MM-DD.
In addition, it is possible to query in the form of an international full ‘datetime’ string (YYYY-MM-DDTHH:MM:SSZ) for some query parameters where relevant, more specifically the timestamp of when a data item was created or modified, e.g. 2023-07-19T00:00:00Z.
However it’s still possible to pass only a date i.e. YYYY-MM-DD in which case an ‘updated’ time of 00:00:00Z will be assumed.
Dates (or datetimes where applicable) in international format, as already described above, are included within the response data. Times are always in UTC zone.
Some practical date/time examples:
When you use date-only filters (without time):
createdAtGTE: This filter includes records from the specified date at 00:00:00Z onwards. For example, 2024-01-01 will include all records from January 1st, 2024, including those at 00:00:00Z.
createdAtLTE: This filter includes records until the specified date at 00:00:00Z. For example, 2024-01-31 will include all records up to January 31st, 2024, 00:00:00Z. So, records on January 31st itself are excluded.
To include data corresponding to an entire month:
For createdAtGTE: Use the first day of the month with 00:00:00Z. For January 2024, this would be 2024-01-01T00:00:00Z.
For createdAtLTE: Use the last day of the month with 23:59:59Z. For January 2024, this would be 2024-01-31T23:59:59Z.
Date-only filters are convenient for month-level filtering, but they exclude records on the end date itself if you don't specify the time. For precise time-based filtering within a day, use full datetime formats with T separating date and time (e.g., 2024-01-31T12:00:00Z).
New Fields, Field Name Changes/Standardisation
Many of the field names in both the query parameters and the response data have been changed. New fields have been added both for the query and the response data to enable improved filtering in queries and more detail in responses.
For full details, please review the query parameters and the detailed response schemas on the various endpoints within the swaggerhub page of the new API: https://app.swaggerhub.com/apis/AdvancedComputerSoft/performance-and-talent-reporting-api/
NB: A basic example response can be found within each API endpoint section when expanding the endpoint within swaggerhub, but the full detailed response schemas are found in a separate section at the bottom of the swaggerhub page.
We have also better standardised the field naming conventions in the new API. We previously used multiple different field names for the unique IDs of response records, but with the new API, all response records now use the main ID field name “Id” throughout, regardless of the type of data being returned. Field names have also been set according to camelCase principles. Date- & time-related field names have been standardised such that date-only fields will be <attributeName>On and datetime fields will be <attributeName>At – e.g. createdOn & createdAt.
New /healthcheck endpoint
A new ‘healthcheck’ endpoint is provided to enable confirmation of system availability status via the API. If the system is available, the ‘status’ will show as “OK” in the response.
Accounts: User, Organisation and Login data Endpoints
Old endpoints:
/logins
/users
/orgunits
New endpoints:
/users
/users/{userId}
/org-units
Comparison
Last-login timestamps by user are now incorporated into the data against users in the response output of the new /users endpoint ; the /logins endpoint is not available as part of the new API.
There is no longer a detailed=”true” query option within the new /users endpoint. The new /users endpoint now includes by default much more detailed information about each user, with the exception of approvers. Approvers can be identified via the new /users/{userId} endpoint which includes all the user data as returned by /users, with an additional nested list of all approvers (managers) assigned to the user, together with full user details of each approver listed.
The new /org-units endpoint is similar to the old /orgunits endpoint, except that it’s now possible to query (and therefore filter) by an organisation unit name, or a part of it. The new response data also now includes a count value against each returned org unit to indicate number of users assigned to the org unit.
Objectives Endpoints
Old endpoints:
/objectives/performance
/v2/objectives/performance
/objectives/development
New endpoints:
/performance-objectives
/performance-objectives/{objectiveId}/deliverables
/development-objectives
Comparison
Old endpoints /objectives/performance and /v2/objectives/performance have been replaced by new endpoint /performance-objectives, and /objectives/development replaced by /development-objectives.
The new /performance-objectives endpoint offers an additional field containing a rich text (formatted) version of the organisational goal (alongside the raw text version).
In contrast to the old endpoint /v2/objectives/performance, deliverables within performance objectives are now available via a separate new endpoint /performance-objectives/{objectiveId}/deliverable, where {objectiveId} is the ID of the performance objective for which the deliverables are to be retrieved. The deliverables returned include a new field for due dates, containing data where applicable.
For the new /development-objectives endpoint there is little difference in the response output data compared with the old one (except for the changes to field names and date/time formats, as is the case for all other new endpoints).
Feedback Endpoints
Old endpoints:
/feedback/feedback
/feedback/request
/feedback/ignore
/feedback/thanks
/v2/feedback/
/v2/feedback/requests
New endpoints:
/feedbacks
/feedback-internal-requests
Comparison
Old API endpoints /feedback/feedback and /v2/feedback/ have been replaced with new endpoint /feedbacks. The feedback records returned in the response now include more detail: such as whether feedback was given from an external source, whether a voice note was attached, and when the recipient replied with a “thank you” and any accompanying message (see also below).
Old API endpoints /feedback/request and /v2/feedback/requests have been replaced with new endpoint /feedback-internal-requests. Again the new API has more detail in the response, including associated Objective IDs, and a lifecycle/workflow status (see also below). The response for the new endpoint /feedback-internal-requests now more clearly identifies all parties involved in feedback requests, via the following fields in the response: -- "authorId": the person for whom feedback is being requested (new field not available in old API) -- "requestedById": the person who requested the feedback, which may be the prospective recipient of the feedback itself, or their manager -- "recipientId": the recipient of the feedback request itself
Old endpoints /feedback/ignore and /feedback/thanks have been retired as separate endpoints and the data they return is now rolled up into the new endpoints, more specifically:
- Whether a feedback request has been ignored (old endpoint /feedback/ignore) can now be ascertained via new endpoint /feedback-internal-requests by checking the “status” field for the “IGNORED” value, within records returned in the response
- Details of any ‘thank yous’ made by a feedback recipient (old endpoint /feedback/thanks), together with any text that is provided alongside the ‘thank you’, is returned as part of the new endpoint /feedbacks, by means of the contents of the “hasReplied” field (values “true” or “false”), and the “repliedMessage” field, within the response records
The status of feedback requests is now broken down in much more detail in new endpoint /feedback-internal-requests – as well as “IGNORED”, there are now also values “REQUESTED”, “RESPONDED” and “RETRACTED” in the “status” field. This enables a full determination of where a feedback request sits in terms of its life cycle. It is also possible to filter /feedback-internal-requests via the “status” field in the API query.
Conversations Endpoints
Old endpoints:
/conversations/conversation
/conversations/comments
New endpoints:
/conversations
/conversations/{conversationId}/notes
Comparison
The new /conversations endpoint includes more detail in the response data, specifically whether a conversations is part of a recurring series, whether it is booked as an ‘online’ i.e. Teams meeting (depending on whether you have enabled the Outlook/Teams calendar integration), and the description text of the conversation type.
The new /conversations/{conversationId}/notes endpoint works differently from the old /conversations/comments one, in that instead of a list of Meeting Notes being returned for various conversations, the query is submitted for an individual conversation ID (using the “Id” value as determined from the output of /conversations), with the response records for /conversations/{conversationId}/notes comprising a full list of Meeting Notes associated with the conversation ID being queried. Additional detail is provided in the response: full details of any OneDrive attachments added to the notes, and a rich-text (formatted) version of the text of the note itself (alongside the raw-text version).
Actions Endpoints
Old endpoints: /actions
New endpoints: /actions
Comparison
In the new /actions endpoint, it is now possible to query additional parameters; namely the objective ID or conversation ID to which actions may be associated. There is little difference in the response output data (except for the changes to field names and date/time formats, as is the case for all other new endpoints).
Talent Snapshots Endpoints
Old endpoints:
/talentsnapshots/rounddetails/
/talentsnapshots/questions/
/talentsnapshots/answers/
/talentsnapshots/participants/
New endpoints:
/talent-snapshots/rounds
/talent-snapshots/rounds/{roundId}/summary
/talent-snapshots/rounds/{roundId}/questions
/talent-snapshots/rounds/{roundId}/participants
/talent-snapshots/rounds/{roundId}/responses
Comparison
A principle change is that the new endpoints for talent snapshots (except for /talent-snapshots/rounds) have been restructured such that the round ID is inserted into the main query URL as denoted by {roundId} in the new endpoint URLs, instead of within the query parameter string. This also effectively makes the round ID a mandatory field (which wasn’t the case with the old endpoints, where it was possible to retrieve data aggregated from multiple rounds ). The round ID is accordingly no longer returned in the response records, as the round ID is implicit in the query used to retrieve the records.
The round ID is obtained by first querying /talent-snapshots/rounds – the round ID of interest can be identified and then used to query the other 4 talent snapshot endpoints.
Approximately speaking:
- /talentsnapshots/rounddetails/ is replaced by a combination of /talent-snapshots/rounds and /talent-snapshots/rounds/{roundId}/summary
- /talentsnapshots/questions/ is replaced by /talent-snapshots/rounds/{roundId}/questions/
- talentsnapshots/answers/ is replaced by /talent-snapshots/rounds/{roundId}/responses
- /talentsnapshots/participants/ is replaced by /talent-snapshots/rounds/{roundId}/participants
Expanding further on the changes:
New endpoint /talent-snapshots/rounds can be queried more flexibly on the round start and end dates, using LTE/GTE-style filters (i.e. less-than-or-equal-to, and greater-than-or-equal-to), as opposed to exactly matching a particular specific date. Additionally the ‘roundName’ query filter of old endpoint /talentsnapshots/rounddetails/, which required an exact match with the round name including identical capitalisation, has been replaced with a more flexible ‘search’ option in the new endpoint /talent-snapshots/rounds, which matches both the round name (and also the description, if any); it is also case-insensitive.
In the new API, once the round ID(s) of interest has been identified from the response from /talent-snapshots/rounds, the ID(s) can then be used to query /talent-snapshots/rounds/{roundId}/summary which returns much more detail about the round than in the old API, including round description (if any), whether the round participants involve managers and/or employees answering questions, whether the option for automatic sharing of manager(s) answers is enabled, an employee/manager breakdown of participant counts and % completion progress, and a count of the quantity of questions associated with it.
The data returned by new endpoint /talent-snapshots/rounds/{roundId}/participants differs from the old endpoint /talentsnapshots/participants/ as follows: -- in the old endpoint, the data is the response comprises records for each employee participant, with information on employee & manager completion both rolled up into each employee participant record -- in the new endpoint, the response data is broken down into separate response records for each of whether it’s the employee answering questions or the manager answering questions, and in the case of employees having multiple managers, is further broken down into separate records for each of those multiple managers
The old and new API for the endpoints concerning the questions and answers are largely similar (except for the changes to field names and date/time formats, as is the case more generally for the new endpoints).
