---
updatedAt: 2026-04-22T14:03:15.000Z
agentTools:
  projectIndex: https://docs.performyard.com/llms.txt
---

# Create one or more employees

Creates one or more new employees to your PerformYard account.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "PerformYard API",
    "description": "The PerformYard API allows customers to programmatically retrieve and manage data related to their performance management processes.",
    "version": "0.1.0",
    "contact": {
      "name": "PerformYard",
      "url": "https://www.performyard.com/contact",
      "email": "info@performyard.com"
    }
  },
  "paths": {
    "/v2/employees": {
      "post": {
        "summary": "Create one or more employees",
        "tags": [
          "Employees"
        ],
        "description": "Creates one or more new employees to your PerformYard account.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "_id": {
                      "anyOf": [
                        {
                          "anyOf": [
                            {
                              "type": "string"
                            }
                          ]
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "first_name": {
                      "description": "The employee's legal first name.",
                      "type": "string"
                    },
                    "last_name": {
                      "description": "The employee's legal last name.",
                      "type": "string"
                    },
                    "nickname": {
                      "description": "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\".",
                      "type": "string"
                    },
                    "email": {
                      "description": "The employee's company or official email address. Must be a valid email format.",
                      "type": "string",
                      "minLength": 1
                    },
                    "phone": {
                      "description": "The employee's primary phone number. Dashes are optional.",
                      "type": "string"
                    },
                    "job_title": {
                      "description": "The employee's official job title or role within the company.",
                      "type": "string"
                    },
                    "hire_date": {
                      "description": "The date in which the employee was officially hired. Allowed Formats: YYYY-MM-DD, MM-DD-YYYY.",
                      "anyOf": [
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "termination_date": {
                      "description": "The date in which the employee's employment ended. Allowed Formats: YYYY-MM-DD, MM-DD-YYYY.",
                      "anyOf": [
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "group": {
                      "description": "The name of the group in which the employee belongs to. The group must exist in PerformYard.",
                      "type": "string"
                    },
                    "role": {
                      "description": "The name or 24-character hex id of the role assigned to the employee. The role must exist in PerformYard; write-only for now, GET requests do not return this field.",
                      "type": "string"
                    },
                    "employee_status": {
                      "description": "The current employment status of the employee.",
                      "type": "string",
                      "enum": [
                        "activated",
                        "deactivated"
                      ]
                    },
                    "manager": {
                      "description": "The email address of the employee's direct manager.",
                      "type": "string"
                    },
                    "contributors": {
                      "description": "The email address(es) of contributors to the employee.",
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "salary": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "number"
                        }
                      ]
                    },
                    "custom_fields": {
                      "description": "Used to update the employee data fields created by the company. Accepts an array of objects where each object includes field_name and field_value, both of which accept a single string value.",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field_name": {
                            "nullable": true,
                            "type": "string"
                          },
                          "field_value": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "string",
                                "format": "date-time"
                              },
                              {
                                "type": "number"
                              },
                              {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                  null
                                ]
                              },
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "array",
                                "items": {}
                              }
                            ]
                          }
                        },
                        "required": [
                          "field_value"
                        ]
                      }
                    }
                  },
                  "required": [
                    "email",
                    "employee_status"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "_id": {
                        "anyOf": [
                          {
                            "type": "string",
                            "minLength": 12,
                            "maxLength": 24
                          }
                        ]
                      },
                      "email": {
                        "nullable": true,
                        "type": "string"
                      }
                    },
                    "required": [
                      "_id"
                    ],
                    "additionalProperties": false
                  }
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "409": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.talent.performyard.com/"
    }
  ],
  "externalDocs": {
    "url": "https://support.performyard.com/article/183-api-reference",
    "description": "PerformYard API Reference"
  }
}
```