Goals API Reference
Introduction
The PerformYard Goals API allows customers to programmatically retrieve and manage data related to Goals created in PerformYard. The API endpoints will let you:
- Retrieve a list of all Goals
- Retrieve a list of individual Goals by ID
- Retrieve a list of your Goal Categories
- Retrieve a list of your Outlooks used in Goal progress updates
- Create a Goal
- Edit an existing Goal
- Update a Goal's progress
Requirements
Calling these API endpoints requires an API Key and API ID. See Getting Started with PerformYard API for details on creating API keys and API Authentication for authentication flow.
Goals API
The Goals API can interact with both public and private goals. API users are assumed to have admin-level permissions and therefore have the same visibility permissions as your Billing Admin and Admin roles.
Retrieve All Goals
GET https://api.talent.performyard.com/v1/goals
Returns a list of all public and private goals, first ordered by status, and then ordered by name and due date.
Goal Description
A goal's description will be delivered with escape characters for proper formatting in your database of choice.
Query Parameters
| limit integer The number of goals to be returned in a single API Request. Default: 200 Minimum: 5 Maximum: 200 |
| offset integer Used to paginate through the list of goals. Can be combined with limit. Default: 0 Increment the value by one to fetch subsequent pages (1 for the second page, 2 for the third, etc.). |
CURL Example
curl --location -X GET "https://api.talent.performyard.com/v1/goals?limit=50&offset=0" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'
Response (200)
{
"goals": [
{
"_id": "<goal_id>",
"start_date": "<YYYY-MM-DDTHH:MM:SSZ>",
"categories": [
{
"_id": "<goal_category_id>",
"name": "<string>"
}
],
"transparency": "private",
"sharers": [
{
"_id": "<employee_id>",
"email": "<string>",
"name": "<string>"
}
],
"target": <integer>,
"name": "<string>",
"description": "<string>",
"value": <integer>,
"assignee": [
{
"_id": "<employee_id>",
"email": "<string>",
"name": "<string>"
}
],
"units": "<string>",
"status": "<string>",
"end_date": "<YYYY-MM-DDTHH:MM:SSZ>",
"outlook": <string>,
"goal_weight": <string>,
"checklist": [
{
"_id": "<string>",
"text": "<string>",
"checked": <boolean>
},
{
"_id": "<string>",
"text": "<string>",
"checked": <boolean>
}
]
},
...
]
}
Retrieve Goal By ID
GET https://api.talent.performyard.com/v1/goals/:goal_id
Returns a goal.
Goal Description
A goal's description will be delivered with escape characters for proper formatting in your database of choice.
Path Parameters
| goal_id string The ID that uniquely identifies the goal to retrieve. |
CURL Example
curl --location -X GET "https://api.talent.performyard.com/v1/goals/65149ccd4625ec565b6db831" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'
Response (200)
{
"_id": "<goal_id>",
"start_date": "<YYYY-MM-DDTHH:MM:SSZ>",
"categories": [
{
"_id": "<goal_category_id>",
"name": "<string>"
}
],
"transparency": "<string>",
"sharers": [
{
"_id": "<employee_id>",
"email": "<string>",
"name": "<string>"
}
],
"target": <integer>,
"name": "<string>",
"description": "<string>",
"value": <integer>,
"assignee": [
{
"_id": "<employee_id>",
"email": "<string>",
"name": "<string>"
}
],
"units": "<string>",
"status": "<string>",
"end_date": "<YYYY-MM-DDTHH:MM:SSZ>",
"outlook": <string>,
"goal_weight": <string>,
"checklist": [
{
"_id": "<string>",
"text": "<string>",
"checked": <boolean>
},
{
"_id": "<string>",
"text": "<string>",
"checked": <boolean>
}
]
}
Retrieve Goal Categories
GET https://api.talent.performyard.com/v1/goal-categories
Returns a list of available goal categories and their IDs.
Query Parameters
| limit integer The number of goal categories to be returned in a single API Request. Default: 200 Minimum: 5 Maximum: 200 |
| offset integer Used to paginate through the list of goal categories. Can be combined with limit. Default: 0 Increment the value by one to fetch subsequent pages (1 for the second page, 2 for the third, etc.). |
CURL Example
curl --location -X GET "https://api.talent.performyard.com/v1/goal-categories?limit=5&offset=0" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'
Response (200)
[
{
"_id": "<goal_category_id>",
"name": "<string>"
},
{
"_id": "<goal_category_id>",
"name": "<string>"
}
]
Retrieve Goal Outlooks
GET https://api.talent.performyard.com/v1/goal-outlooks
Returns a list of available goal outlooks and their IDs.
Query Parameters
| limit integer The number of goal outlooks to be returned in a single API Request. Default: 200 Minimum: 5 Maximum: 200 |
| offset integer Used to paginate through the list of goal outlooks. Can be combined with limit. Default: 0 Increment the value by one to fetch subsequent pages (1 for the second page, 2 for the third, etc.). |
CURL Example
curl --location -X GET "https://api.talent.performyard.com/v1/goal-outlooks?limit=10&offset=0" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'
Response (200)
[
{
"_id": "<goal_outlook_id>",
"color": "<string>",
"name": "<string>"
},
{
"_id": "<goal_outlook_id>",
"color": "<string>",
"name": "<string>"
}
]
Create A Goal
POST https://api.talent.performyard.com/v1/goals
Create a new goal for an employee.
Multiple Goal Assignees
Just like when creating a new goal in the PerformYard interface, adding multiple goal assignees will not assign multiple users to a single goal and will instead create one goal each for every assignee included.
Request Body Parameters
| name string required Name of the goal being created. |
| assignment array required The user ID(s) of the employee(s) that will be assigned the goal being created. Accepts an array of user IDs (strings). |
| transparency enum required Defines who can see the goal being created. Possible Values: private public |
| target integer required The value you want to hit for the goal being created. |
| start_date string required The start date of the goal. Format: YYYY-MM-DD |
| units string The type of units the goal being created will have for its target. Default: % |
| is_top_level boolean Defines whether the goal is a top level goal or not. Default: false |
| due_date string When the goal is due. Format: YYYY-MM-DD |
| goal_weight integer Defines the weight of the goal being created compared to other goals assigned to the same employee. Minimum: 0 |
| description string The details of the goal being created. |
| alignment string Defines the goal that the goal being created is aligned to. Must be a different goal's ID. Only a single goal ID is valid. |
| categories array Defines the category or categories that the goal being created belongs to. Accepts an array of goal category IDs (strings). Goal categories can be retrieved using the GET /v1/goal-categories endpoint. |
CURL Example
curl -X POST https://api.talent.performyard.com/v1/goals \
--header "Content-Type: application/json" \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'
--data '{
"name": "2025 Sales Goal",
"assignment": [
"<user_id>",
"<user_id>"
],
"transparency": "public",
"target": 200000,
"units": "$",
"start_date": "2025-01-01",
"due_date": "2025-12-31",
"goal_weight": "<string>",
"is_top_level": false,
"description": "This is your sales goal",
"alignment": "<goal_id>",
"categories": [
"<category_id>",
"<category_id>"
]
}'
Response (200)
{
"message": "Goal created",
"ids": [
"<goal_id>",
"<goal_id>"
]
}
Update A Goal's Details
PATCH https://api.talent.performyard.com/v1/goals/:goal_id
Update the details of an already created goal. Does not update the goal's progress. That can be done using the endpoint entitled "Update A Goal's Progress".
Updates Overwrite Existing Property Value
Updates to fields will also overwrite the current field value instead of appending new values to the existing field entry. For example, the description of a goal needs to be updated to include a link to outside documentation, the entire existing goal description in addition to the new link should be included in the PATCH request.
Activity Stream
Updates to Goal attributes will also be recorded in the Goal's activity history stream, where the label of the responsible API key will be displayed alongside the nature of the update.
Path Parameters
| goal_id string The ID that uniquely identifies the goal to retrieve. |
Request Body Parameters
| name string Name of the goal being created. |
| assignment array The user ID(s) of the employee(s) that will be assigned the goal being created. Accepts an array of user IDs (strings). |
| transparency enum Defines who can see the goal being created. Possible Values: private public |
| target integer The value you want to hit for the goal being created. |
| start_date string The start date of the goal. Format: YYYY-MM-DD |
| units string The type of units the goal being created will have for its target. |
| is_top_level boolean Defines whether the goal is a top level goal or not. |
| due_date string When the goal is due. Format: YYYY-MM-DD |
| goal_weight integer Defines the weight of the goal being created compared to other goals assigned to the same employee. Minimum: 0 |
| description string The details of the goal being created. |
| alignment string Defines the goal that the goal being created is aligned to. Must be a different goal's ID. Only a single goal ID is valid. |
| categories array Defines the category or categories that the goal being created belongs to. Accepts an array of goal category IDs (strings). Goal categories can be retrieved using the GET /v1/goal-categories endpoint. |
CURL Example
curl -X PATCH https://api.talent.performyard.com/v1/goals/65149ccd4625ec565b6db831 \
--header "Content-Type: application/json" \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'
--data '{
"name": "New goal name",
"target": 1000000,
"units": "$"
}'
Response (200)
{
"message": "Goal updated",
"id": "<goal_id>"
}
Update A Goal's Progress
PATCH https://api.talent.performyard.com/v1/goals/:goal_id/update-progress
Update the progress of a goal.
Activity Stream
Progress updates made to a goal via the API will be recorded in the Activity Stream and Goal Progress side panel just as they would be if made via the PerformYard interface. Updates will also be associated with the name of the API key that was responsible for providing the update.
Archived or Completed Goals
Just as in the PerformYard interface, archived or completed goals cannot have their progress updated. Users attempting to update these goals will receive an error message indicating their status as an archived or completed goal.
Path Parameters
| goal_id string The ID that uniquely identifies the goal to retrieve. |
Request Body Parameters
| value integer required The value of this goal's progress. |
| update_type enum required Set how to alter the current goal progress value Possible Values: absolute incremental absolute - Overwrites the current goal progress value with the value passed in for value incremental - Adds the passed in value to the current goal progress value |
| as_of_date string required The progress of this goal as of a certain date. Format: YYYY-MM-DD |
| message string Text to be added to the goal being updated activity stream on update. |
| outlook string The ID that uniquely identifies the current outlook of the goal being updated. Accepts a single string value. Goal outlooks can be retrieved using the GET /v1/goal-outlooks endpoint. |
CURL Example
curl --location -X PATCH "https://api.talent.performyard.com/v1/goals/65149ccd4625ec565b6db831/update-progress" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'
--data '{
"value": 20,
"update_type": "incremental",
"as_of_date": "2025-01-09"
}'
Response (200)
{
"message": "Goal progress updated",
"id": "<goal_id>"
}