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 Outlooks used in Goal progress updates
Retrieve a list of your Goal Categories
Updating a Goal's progress
Creating a Goal

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.

Note: 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

Provides the ability to retrieve all goals for the purposes of storage or understanding what the current state of a goal is before updating progress or attributes for the goal.

Results are ordered by Active, Complete, and then Archived status. Within each status results are ordered by Name and Due Date to facilitate identifying each employee's most relevant goals that have upcoming due dates.

Please keep in mind that a goal's description will be delivered with escape characters for proper formatting in your database of choice.

HTTP GET

https://api.talent.performyard.com/v1/goals

Query Params	Type	Description	Default	Example
Limit	number	The number of goals to be returned	200	50
Offset	number	Skips into the list of goals and, when combined with the limit parameter, can be used to paginate longer results.	0	5

CURL Example

curl --location -X GET "https://api.staging.talent.performyard.com/v1/goals?limit=50&offset=5" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'

Response:

200 OK

Body:

{
    "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": 100,
            "name": "<string>",
            "description": "<string>",
            "value": 20,
            "assignee": [
                {
                    "_id": "<employee_id>",
                    "email": "<string>",
                    "name": "<string>"
                }
            ],
            "units": "<string>",
            "status": "active",
            "end_date": "<YYYY-MM-DDTHH:MM:SSZ>",
            "outlook": <string>,
            "goal_weight": <string>,
            "checklist": [
                {
                    "_id": "<string>",
                    "text": "<string>",
                    "checked": false
                },
                {
                    "_id": "<string>",
                    "text": "<string>",
                    "checked": true
                }
            ]
        },
	...
    ]
}

Retrieve Goals by ID

Provides the ability to retrieve one to many active, completed, or archived goals by their unique ID.

Please keep in mind that a goal's description will be delivered with escape characters for proper formatting in your database of choice.

HTTP GET

https://api.talent.performyard.com/v1/goals/(goal_id)

Path Variables	Type	Description	Example
:id	string	The ID of the goal. Multiple goals can be retrieved by comma-separating each ID.	65149ccd4625ec565b6db831,65149ccd4625ec565b6db847

CURL Example

curl --location -X GET "https://api.staging.talent.performyard.com/v1/goal/(goal_id)" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'

Response:

200 OK

Body:

{
            "_id": "<goal_id>",
            "start_date": "<YYYY-MM-DDTHH:MM:SSZ>",
            "categories": [
                {
                    "_id": "<goal_category_id>",
                    "name": "<string>"
                }
            ],
            "transparency": "public",
            "sharers": [
                {
                    "_id": "<employee_id>",
                    "email": "<string>",
                    "name": "<string>"
                }
            ],
            "target": 100,
            "name": "<string>",
            "description": "<string>",
            "value": 20,
            "assignee": [
                {
                    "_id": "<employee_id>",
                    "email": "<string>",
                    "name": "<string>"
                }
            ],
            "units": "<string>",
            "status": "active",
            "end_date": "<YYYY-MM-DDTHH:MM:SSZ>",
            "outlook": <string>,
            "goal_weight": <string>,
            "checklist": [
                {
                    "_id": "<string>",
                    "text": "<string>",
                    "checked": false
                },
                {
                    "_id": "<string>",
                    "text": "<string>",
                    "checked": true
                }
            ]
        }

Retrieve Goal Categories

Provides the list of available goal categories and their IDs to be used when creating a new goal or updating an existing goal.

HTTP GET

https://api.talent.performyard.com/v1/goal-categories

Query Params	Type	Description	Default	Example
Limit	Number	The number of categories to be returned.	200	50
Offset	Number	Skips into the list of categories and, when combined with the limit parameter, can be used to paginate longer results.	0	5

CURL Example

curl --location -X GET "https://api.staging.talent.performyard.com/v1/goal/goal-categories" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'

Response:

200 OK

Body:

[
    {
        "_id": "<string>",
        "name": "<string>"
    },
    {
        "_id": "<string>",
        "name": "<string>"
    }
]

Retrieve Goal Outlooks

Provides a list of available outlooks and their IDs to use when updating a goal's progress.

HTTP GET

https://api.talent.performyard.com/v1/goal-outlooks

Query Params	Type	Description	Default	Example
Limit	Number	The number of outlooks to be returned.	200	50
Offset	Number	Skips into the list of outlooks and, when combined with the limit parameter, can be used to paginate longer results.	0	5

CURL Example

curl --location -X GET "https://api.staging.talent.performyard.com/v1/goal-outlooks" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'

Response:

200 OK

Body:

[
    {
        "_id": "<string>",
        "color": "<string>",
        "name": "<string>"
    },
    {
        "_id": "<string>",
        "color": "<string>",
        "name": "<string>"
    },
    {
        "_id": "<string>",
        "color": "<string>",
        "name": "<string>"
    }
]

Update Goal Progress

Updates a goal's progress, with options for providing incremental or absolute updates as well as the ability to update the goal's outlook. 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.

When determining your update type, "absolute" or "incremental" are the only allowed strings. These update types work exactly as they would when updating a goal via the UI, where an Incremental update adds the number entered in the value field to the existing goal progress value and an Absolute update overwrites the current goal progress value with the new value you provide in the value field.

Please note: 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.

HTTP PATCH

https://api.talent.performyard.com/v1/goals/(goal_id)/update-progress

Path Variables	Type	Description	Example
goal_id	text	The id of the goal associated with the progress update.	15d211ff7ad03d38b334716o

Request Example

{
    "value": <number>,
    "update_type": "<string>",
    "as_of_date": "<string>",
    "message": "<string>",
    "outlook": "<outlook_id>"
}

CURL Example

curl --location -X PATCH "https://api.talent.performyard.com/v1/goals/(goal_id)/update-progress" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'

Response:

200 OK

Response Body:

{
    "message": "Goal progress updated",
    "id": "<goal_id>"
}

Create Goals

This API endpoint allows you to create a goal and define the various attributes of the goal to be created. Please keep in mind that, 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. The maximum number of assignees per request to create a goal has been capped at 50 to preserve speed and ease of troubleshooting validation errors, so please keep in mind that you will need to sequence your assignees in batches of 50 if you would like to create more than 50 goals with the same attributes and assign them in bulk.

HTTP POST

https://api.talent.performyard.com/v1/goals/

Body Params	Type	Description	Default	Example
name	string	The title of the goal being created	Required	Complete new customer onboarding planning.
assignment	string	The ID of the employee(s) that will be assigned a goal.	Required	642af7983586809245187b04
transparency	string	Defines whether the goal will be public or private.	Required	public
target	string	Defines the target value of the goal.	Required	100
units	string	Defines the type of units the goal target will have.	Required	%
is_top_level	string	Defines whether the goal is a top level goal or not.	Required	false
start_date	string	Defines the start date of the goal. Must be in YYYY-MM-DD format.	Required	2024-11-05
due_date	string	Defines the due date of the goal. Must be in YYYY-MM-DD format.	Optional	2024-12-30
goal_weight	string	Defines the weight of a goal compared to others assigned to the same employee.	Optional	1
description	string	The details of the specific goal.	Optional	Using our company OKRs and customer retention goals, define a template project...
alignment	string	Defines a goal's alignment using another goal's ID.	Optional	441af7183586808817187o61
categories	string	Defines a goal's categories using the IDs delivered via the /goal-categories/ endpoint	Optional	851m77cc9aadf5f375f181a5

Body

{
    "name":"<string>",
    "assignment": [       
        "<user_id>",
        "<user_id>"
    ],
    "transparency": "<string>",
    "target": <string>,
    "units": "<string>",
    "start_date": "<YYYY-MM-DD>",
    "due_date": "<YYYY-MM-DD>",
    "goal_weight": <string>,
    "is_top_level": <string>,
    "description": "<string>",
    "alignment": "<goal_id>",
    "categories": "<category_id>"
}

CURL Example

curl -X POST <API_URL> \
--header "Content-Type: application/json" \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'
--data '{
    "name": "<string>",
    "assignment": [       
        "<user_id>",
        "<user_id>"
    ],
    "transparency": "<string>",
    "target": "<string>",
    "units": "<string>",
    "start_date": "<YYYY-MM-DD>",
    "due_date": "<YYYY-MM-DD>",
    "goal_weight": "<string>",
    "is_top_level": "<string>",
    "description": "<string>",
    "alignment": "<goal_id>",
    "categories": "<category_id>"
}'

Response

200 OK

Body

{
    "message": "Goal created",
    "ids": [
        "<string>",
        "<string>"
    ]
}