Employee API Reference

Introduction

The PerformYard Employee API allows customers to programmatically retrieve and manage data related to users/employees defined in PerformYard. The API endpoints will let you:

Retrieve the list of employees with the ability to sort and paginate results.
Retrieve the definition of an employee
Create new employee
Update Employee details and fields
Delete (Deactivate) an Employee
Perform batch operations

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.

Retrieve All Employees

GET https://api.talent.performyard.com/v1/employees

Returns a list employees.

Query Parameters

limit integer

The number of employees to be returned in a single API Request.

Default: 200

Minimum: 5

Maximum: 200

offset integer

Used to paginate through the list of employees. 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.).

sort string

Order in which to return the list of employees.

Allowed Values: asc(FIELD_NAME) desc(FIELD_NAME)

Allowed Field Names: _id name email manager

employeeStatus enum

Filter the returned employees by a specific status.

Allowed Values: activated deactivated

Accepts only a single string value.

permissionLevel enum

Filter the returned employees by a specific permission level.

Allowed Values: billing admin admin basic admin employee

Accepts only a single string value.

includeAllDataFields boolean

Used to determine whether all data fields should be returned for each employee in the list.

Allowed Values: true false

Accepts only a single boolean value.

CURL Example

curl --location 'https://api.talent.performyard.com/v1/employees?limit=200&offset=0&employeeStatus=deactivated&permissionLevel=employee&includeAllDataFields=true' \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'

Response (200)

{
  "employees": [
    {
      "_id": "<string>",
      "name": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "job_title": "<string>",
      "manager": {
        "_id": "<string>",
        "name": "<string>",
        "email": "<string>"
      },
      "contributors": [
        {
          "_id": "<string>",
          "name": "<string>",
          "email": "<string>"
        },
        {
          "_id": "<string>",
          "name": "<string>",
          "email": "<string>"
        }
      ],
      "group": {
        "_id": "<string>",
        "name": "<string>"
      },
      "termination_date": "<string>",
      "permission_level": "employee",
      "employee_status": "deactivated",
      "custom_fields": [
        {
          "_id": "<string>",
          "field_value": "<string>",
          "field_name": "<string>"
        },
        {
          "_id": "<string>",
          "field_value": "<string>",
          "field_name": "<string>"
        }
      ],
      "hire_date": "<string>"
    }, 
    ...
  ]
}

Retrieve Employee By ID

GET https://api.talent.performyard.com/v1/employees/:employee_id

Returns an employee.

Path Parameters

employee_id string

The ID that uniquely identifies the employee to retrieve.

Query Parameters

includeAllDataFields boolean

Used to determine whether all data fields should be returned for each employee in the list.

Allowed Values: true false

Accepts only a single boolean value.

CURL Example

curl --location -X GET "https://api.talent.performyard.com/v1/employees/6734c08623dbbf142bb2f3de?includeAllDataFields=true" \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}'

Response (200)

{
  "employee": {
    "_id": "<string>",
    "name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "job_title": "<string>",
    "manager": {
      "_id": "<string>",
      "name": "<string>",
      "email": "<string>"
    },
    "contributors": [
      {
        "_id": "<string>",
        "name": "<string>",
        "email": "<string>"
      },
      {
        "_id": "<string>",
        "name": "<string>",
        "email": "<string>"
      }
    ],
    "group": {
      "_id": "<string>",
      "name": "<string>"
    },
    "termination_date": "<string>",
    "permission_level": "basic admin",
    "employee_status": "deactivated",
    "custom_fields": [
      {
        "_id": "<string>",
        "field_value": "<string>",
        "field_name": "<string>"
      },
      {
        "_id": "<string>",
        "field_value": "<string>",
        "field_name": "<string>"
      }
    ],
    "hire_date": "<string>"
  }
}

Update Multiple Employees

PATCH https://api.talent.performyard.com/v1/employees

Update the details for one or more employees, optionally including their custom employee data fields.

Request Body Parameters

Request Body

The request for this endpoint takes in an array of employees to be updated (objects). The following table explains the possible parameters that can be passed in for each employee to update and which are required.

_id string required

The ID that uniquely identifies the employee to update.

first_name string

The employee's legal first name.

nickname string

The employee's preferred or commonly used name.

When an employee has nickname set, the name property on GET requests will follow the format "nickname last_name".

last_name string

The employee's legal last name.

email string

The employee's company or official email address.

Must be a valid email format.

phone string

The employee's primary phone number.

Dashes are optional.

job_title string

The employee's official job title or role within the company.

hire_date string

The date in which the employee was officially hired.

Allowed Formats: YYYY-MM-DD MM-DD-YYYY

termination_date string

The date in which the employee's employment ended.

Allowed Formats: YYYY-MM-DD MM-DD-YYYY

group string

The group in which the employee belongs to. Learn more about groups here.

The group must exist in PerformYard. An employee can exist in more than one group.

employee_status enum

The current employment status of the employee.

Allowed Values: activated deactivated

manager string

The email address of the employee's direct manager.

contributors array

The email address(es) of contributors to the employee.

Accepts an array of 0 to any number of employee email addresses (strings).

custom_fields array

Used to update the employee data fields created by the company. Learn more about employee data fields here.

Accepts an array of object where each object includes field_name and field_value, both of which accept a single string value. Both are required in this action.

Request Body Format

[
  {
    "_id": "<string>",
    "first_name": "<string>",
    "nickname": : "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "job_title": "<string>",
    "hire_date": "<string>",
    "termination_date": "<string>",
    "group": "<string>",
    "employee_status": "activated",
    "manager": "<string>",
    "contributors": [
      "<string>"
    ],
    "custom_fields": [
      {
        "field_name": "<string>",
        "field_value": "<string>"
      }
    ]
  },
  ...
]

CURL Example

curl --location --request PATCH 'https://api.talent.performyard.com/v1/employees' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-id: {{X-API-ID}}' \
--header 'x-api-key: {{X-API-KEY}}' \
--data '[
  {
    "_id": "6734c08623dbbf142bb2f3df",
    "first_name": "Jenny",
    "nickname": : "Jen",
    "last_name": "Sherman",
    "job_title": "Sales, VP",
    "employee_status": "deactivated",
    "manager": "manager@company.com",
    "contributors": [
      "contributor1@company.com",
      "contributor2@company.com"
    ],
    "custom_fields": [
      {
        "field_name": "Location",
        "field_value": "Virginia"
      }
    ]
  },
  ...
]'

Response (200)

{ 
   "message": "Employee(s) updated or created"
}

Update Employee

PATCH https://api.talent.performyard.com/v1/employees/:employee_id

Update the details of a single.