---
updatedAt: 2026-04-27T23:21:35.000Z
agentTools:
  projectIndex: https://developer.runn.io/llms.txt
---

# Create a person

Also creates a new contract for the person

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Runn API",
    "version": "1.0.0",
    "description": "<p>See <a target=\"_blank\" href=\"https://help.runn.io/en/articles/8579592-api-v1-beta\" title=\"Runn API full documentation\">the full documentation and guide</a> to using the Runn API.</p><p>The domain for your API endpoint can be found in <strong>Accounts > Settings > API</strong> in your Runn application</p>"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "BadRequest": {
        "type": "object",
        "required": [
          "error",
          "message",
          "statusCode"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "Bad Request"
            ]
          },
          "message": {
            "type": "string"
          },
          "statusCode": {
            "type": "number",
            "enum": [
              400
            ]
          }
        }
      },
      "Person": {
        "type": "object",
        "required": [
          "id",
          "firstName",
          "lastName",
          "email",
          "isArchived",
          "references",
          "notes",
          "teamId",
          "tags",
          "skills",
          "holidaysGroupId",
          "customFields",
          "managers",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "isArchived": {
            "type": "boolean"
          },
          "references": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Reference"
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "note",
                "createdBy"
              ],
              "properties": {
                "id": {
                  "type": "integer"
                },
                "note": {
                  "type": "string"
                },
                "createdBy": {
                  "type": "string"
                }
              }
            }
          },
          "teamId": {
            "type": [
              "integer",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tag"
            }
          },
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "level"
              ],
              "properties": {
                "id": {
                  "type": "integer"
                },
                "level": {
                  "type": "integer",
                  "nullable": true
                }
              }
            }
          },
          "holidaysGroupId": {
            "type": "integer",
            "nullable": true
          },
          "customFields": {
            "type": "object",
            "required": [
              "select",
              "text",
              "checkbox",
              "date"
            ],
            "properties": {
              "select": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "values"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "values": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "name",
                          "id"
                        ],
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "id": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "text": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "value"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  }
                }
              },
              "checkbox": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "value"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "value": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "date": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "value"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "value": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date",
                      "description": "Format: YYYY-MM-DD"
                    }
                  }
                }
              }
            }
          },
          "managers": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id"
              ],
              "properties": {
                "id": {
                  "description": "The ID referencing the user managing the person.",
                  "type": "integer"
                }
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the object was created."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of when the object was last updated."
          }
        }
      },
      "Reference": {
        "type": "object",
        "required": [
          "referenceName",
          "externalId"
        ],
        "properties": {
          "referenceName": {
            "minLength": 1,
            "type": "string"
          },
          "externalId": {
            "minLength": 1,
            "type": "string"
          }
        }
      },
      "Tag": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "Unauthorized": {
        "type": "object",
        "required": [
          "error",
          "message",
          "statusCode"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "Unauthorized"
            ]
          },
          "message": {
            "type": "string",
            "enum": [
              "Unauthorized"
            ]
          },
          "statusCode": {
            "type": "number",
            "enum": [
              401
            ]
          }
        }
      }
    }
  },
  "paths": {
    "/people/": {
      "post": {
        "operationId": "createPerson",
        "summary": "Create a person",
        "description": "Also creates a new contract for the person",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "firstName",
                  "lastName",
                  "roleId"
                ],
                "properties": {
                  "firstName": {
                    "minLength": 1,
                    "maxLength": 100,
                    "type": "string"
                  },
                  "lastName": {
                    "minLength": 1,
                    "maxLength": 100,
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "teamId": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "holidaysGroupId": {
                    "type": "integer"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "id"
                      ],
                      "properties": {
                        "id": {
                          "type": "integer"
                        }
                      }
                    }
                  },
                  "references": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Reference"
                    }
                  },
                  "managers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "userId"
                      ],
                      "properties": {
                        "userId": {
                          "type": "integer"
                        }
                      }
                    }
                  },
                  "roleId": {
                    "type": "integer"
                  },
                  "startDate": {
                    "type": "string",
                    "format": "date",
                    "description": "Defaults to today. Format: YYYY-MM-DD"
                  },
                  "endDate": {
                    "type": "string",
                    "format": "date",
                    "description": "Format: YYYY-MM-DD"
                  },
                  "employmentType": {
                    "type": "string",
                    "enum": [
                      "employee",
                      "contractor"
                    ],
                    "description": "The type of employment for the contract.",
                    "default": "employee"
                  },
                  "costPerHour": {
                    "description": "Defaults to the role's cost per hour",
                    "type": "number"
                  },
                  "minutesPerDay": {
                    "minimum": 1,
                    "description": "Defaults to the account's default minutes per day",
                    "type": "number"
                  },
                  "rosteredDays": {
                    "description": "Every value must be the same as minutesPerDay or 0.",
                    "type": "object",
                    "required": [
                      "monday",
                      "tuesday",
                      "wednesday",
                      "thursday",
                      "friday"
                    ],
                    "properties": {
                      "monday": {
                        "type": "number"
                      },
                      "tuesday": {
                        "type": "number"
                      },
                      "wednesday": {
                        "type": "number"
                      },
                      "thursday": {
                        "type": "number"
                      },
                      "friday": {
                        "type": "number"
                      }
                    }
                  },
                  "jobTitle": {
                    "description": "This feature is currently hidden, and can not be seen in the app",
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "default": "1.0.0",
              "enum": [
                "1.0.0"
              ]
            },
            "in": "header",
            "name": "accept-version",
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                }
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.runn.io",
      "description": "EU Server"
    },
    {
      "url": "https://api.us.runn.io",
      "description": "US Server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-readme": {
    "proxy-enabled": false
  }
}
```