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

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.

Retrieving the List of Employees

Provide the ability to retrieve the list of all employees or a subset of all employees, including the ability to paginate, sort, and filter results.

HTTP GET

https://api.talent.performyard.com/v1/employees
Query Params Type Description Default Example
limit number The number of employee records to be returned. 200 50
offset number Skipping into the list of employees, when combined with the limit parameter, can be used to paginate longer results. 0 5
sort string The order in which employees are returned. Accepts "asc(FIELD_NAME)" and/or "desc(FIELD_NAME)". null asc(name),desc(type)
employeeStatus enum The status of the employees to be returned.  Allowed values: activated, deactivated null deactivated
permissionLevel enum The permission level of the employees.  Allowed values: billing admin, admin, basic admin, employee null employee
includeAllDataFields string The data fields are to be returned for each employee. Allowed values: true, false false true

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: 

HTTP 200 OK

Body:
{
  "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>"
    }, 
    ...
  ]
}
Headers
content-type application/json

Retrieve Employee Details

This API endpoint allows you to retrieve the details for an individual employee, optionally including all their data fields.  

HTTP GET

https://api.talent.performyard.com/v1/employees/:id
Query Params Type Description Default Example
includeAllDataFields string The data fields to be returned for each employee.  Available values: true, false
     false true
Path Variables Type Description Example
:id string The id of the employee. 642af7983586809245187b04

CURL Example

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

Response 

200 OK

Body
{
  "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>"
  }
}
Headers  
content-type application/json

Update Employee Details for Multiple Employees

This API endpoint allows you to update the details for one or more employees as a batch operation by passing an array of employee updates, optionally including their custom employee data fields.  

HTTP PATCH

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

Body

[
  {
    "_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": "<string>",
    "first_name": "<string>",
    "nickname": : "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "job_title": "<string>",
    "hire_date": "<dateTime>",
    "termination_date": "<dateTime>",
    "group": "<string>",
    "employee_status": "deactivated",
    "manager": "<string>",
    "contributors": [
      "<string>",
      "<string>"
    ],
    "custom_fields": [
      {
        "field_value": "<string>",
        "field_name": "<string>"
      },
      {
        "field_value": "<string>",
        "field_name": "<string>"
      }
    ]
  },
  ...
]'

Response

200 OK

Body
{ 
   "message": "<string>",
   "errors": [
     "<string>",
     "<string>",
     ...
   ]  
}
Headers
content-type application/json

Update Employee Details for an Individual Employee

This API endpoint allows you to update the details for one employee, optionally including their custom employee data fields.  

HTTP PATCH

https://api.talent.performyard.com/v1/employees/:id
Path Variables Type Description Example
:id text The id of the employee. 642af7983586809245187b04

Body

{
  "_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/:id' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-id: kuugklk2y1' \
--header 'x-api-key: {{' \
--data '{
  "_id": "<string>",
  "first_name": "<string>",
  "nickname": : "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "job_title": "<string>",
  "hire_date": "<dateTime>",
  "termination_date": "<dateTime>",
  "group": "<string>",
  "employee_status": "activated",
  "manager": "<string>",
  "contributors": [
    "<string>",
    "<string>"
  ],
  "custom_fields": [
    {
      "field_value": "<string>",
      "field_name": "<string>"
    },
    {
      "field_value": "<string>",
      "field_name": "<string>"
    }
  ]
}'

Response 

HTTP 200 OK

Body
{ 
   "message": "<string>",
   "errors": [
     "<string>",
     "<string>",
     ...
   ] 
}
Headers  
content-type application/json

Create one or more Employees 

This API endpoint allows you to create or provision one or more employees as a batch operation in PerformYard, optionally including their custom employee data fields.  

HTTP POST

https://api.talent.performyard.com/v1/employees
Body Params Type Description Default Example
first_name string The first name of the employee. Required Jenny
last_name string The last name of the employee.  Required Sherman
email string The email of the employee . Required jsherman@example.com
employee_status string The status of the employee's PerformYard account. Required activated

Body

[
  {
    "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 '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 '[
  {
    "email": "<string>",
    "employee_status": "activated",
    "first_name": "<string>",
    "last_name": "<string>",
    "phone": "<string>",
    "job_title": "<string>",
    "hire_date": "<dateTime>",
    "termination_date": "<dateTime>",
    "group": "<string>",
    "manager": "<string>",
    "contributors": [
      "<string>",
      "<string>"
    ],
    "custom_fields": [
      {
        "field_value": "<string>",
        "field_name": "<string>"
      },
      {
        "field_value": "<string>",
        "field_name": "<string>"
      }
    ]
  },
  ...
]'

Response 

HTTP 200 OK

Body
{ 
   "message": "<string>",
   "errors": [
       "<string>",
       "<string>",
       ...
   ]
}
Headers
content-type application/json

Related Articles