# List all people

You can fetch a list of all people.
You can optionally specify a limit to control the number of results returned, and an offset to skip a specified number of entries from the start.

Endpoint: GET /people/v2
Version: v1
Security: basicAuth

## Security:

  - `basicAuth` (unknown)
    http basic

## Query parameters:

  - `contractTypes` (array)
    Comma-separated list of contract type UUIDs used to filter people by contract types.

  - `positions` (array)
    Comma-separated list of position IDs used to filter people by positions.

  - `teams` (array)
    Comma-separated list of team IDs used to filter people by team membership.

  - `archived` (boolean)
    Filter by archived status. Set to `true` to return only archived people, or `false` to return only active people.

  - `projection` (string)
    Defines the projection strategy used for the response. 
- `FULL` (default): returns all available fields. 
- `BASIC`: returns a minimal subset of fields. 
- `CUSTOM`: returns only the fields specified in the `fields` parameter. When `CUSTOM` is used, the `fields` parameter is required.

Note: Regardless of projection type, the response always includes `id`, `legacyId` and `archived` fields.

  - `fields` (string)
    Comma-separated list of field names to include in the response. Only applicable when `projection=CUSTOM`.

Note: Regardless of the list, the fields `id`, `legacyId` and `archived` are always returned.

  - `limit` (integer)
    The maximum number of items to return. Must be greater than or equal to 1. Default is 100.

  - `offset` (integer)
    The number of items to skip before returning the results. Must be greater than or equal to 0. Default is 0.

  - `sort` (array)
    Sorting criteria in the format `field,ASC` or `field,DESC`. Can be repeated to apply multi-level sorting.

  - `nullOrdering` (string)
    Specifies how NULL values are sorted. Options: `NULLS_FIRST` or `NULLS_LAST`. Default is `NULLS_FIRST`.

## Response 200:

  - `200` (unknown)
    The request was successful. A list of people matching the specified criteria is returned.

## Response 200 fields (application/json):

  - `data` (array, required)
    List of people returned in the current page.

  - `data.id` (string, required)
    Unique identifier (UUID format).
    Example: 52601c08-b7e5-4c60-a57f-2b1d74942543

  - `data.legacyId` (integer)
    Legacy numerical identifier.
    Example: 1337

  - `data.firstName` (any)
    The first name of the person.

  - `data.middleName` (any)
    The middle name of the person.

  - `data.lastName` (any)
    The last name of the person.

  - `data.email` (any)
    Primary business email address.

  - `data.roles` (any)
    System roles assigned to this person.

  - `data.archived` (boolean | null)

  - `data.archivedDate` (any)
    Archiving timestamp in ISO-8601 format.

  - `data.position` (any)
    Current position held by the person.

  - `data.position.id` (integer | null)

  - `data.position.name` (string | null)

  - `data.birthdate` (any)

  - `data.businessContact` (any)

  - `data.businessContact.phone` (any)

  - `data.personalContact` (any)

  - `data.personalContact.phone` (any)

  - `data.personalContact.email` (any)

  - `data.address` (any)

  - `data.address.street` (any)

  - `data.address.number` (any)

  - `data.address.city` (any)

  - `data.address.provinceState` (any)

  - `data.address.postalCode` (any)

  - `data.address.country` (any)

  - `data.sex` (string | null)
    Sex.
    Enum: "MALE", "FEMALE", "OTHER", null

  - `data.maritalStatus` (string | null)
    Martial status.
    Enum: "SINGLE", "MARRIED", "WIDOWED", "SEPARATED", "DIVORCED", "DOMESTIC_PARTNERSHIP", "COMMON_LAW", "OTHER", "NOT_SET", null

  - `data.hireDate` (any)

  - `data.probationEndDate` (any)

  - `data.terminationDate` (any)

  - `data.seniorityBeforeHire` (any)

  - `data.externalNumber` (any)

  - `data.symfoniaGuid` (any)

  - `data.customNote` (any)

  - `data.emergencyContact` (any)

  - `data.emergencyContact.name` (any)

  - `data.emergencyContact.relationship` (any)

  - `data.emergencyContact.phone` (any)

  - `data.approvalFlow` (any)

  - `data.approvalFlow.id` (any)

  - `data.approvalFlow.name` (any)

  - `data.contractType` (any)

  - `data.contractType.id` (any)

  - `data.contractType.name` (any)

  - `data.holidaysCalendar` (any)

  - `data.holidaysCalendar.id` (any)

  - `data.holidaysCalendar.name` (any)

  - `data.workSchedule` (any)

  - `data.workSchedule.id` (any)

  - `data.workSchedule.name` (any)

  - `data.teams` (any)

  - `data.teams.id` (any)

  - `data.teams.name` (any)

  - `data.directManager` (any)

  - `data.directManager.id` (any)

  - `data.directManager.legacyId` (any)

  - `data.directManager.firstName` (any)
    The first name of the person.

  - `data.directManager.lastName` (any)
    The last name of the person.

  - `data.directManager.email` (any)

  - `data.bankAccountNumber` (any)

  - `data.shirtSize` (any)

  - `data.contractorDetails` (any)

  - `data.contractorDetails.taxNumber` (any)

  - `data.contractorDetails.companyName` (any)

  - `data.contractorDetails.companyAddress` (any)

  - `data.children` (array | null)

  - `data.children.id` (string, required)
    Example: 52601c08-b7e5-4c60-a57f-2b1d74942543

  - `data.children.firstName` (any)

  - `data.children.lastName` (any)

  - `data.children.birthdate` (any)

  - `data.children.parent` (any)

  - `data.customFields` (any)

  - `data.customFields.id` (string, required)
    Example: 52601c08-b7e5-4c60-a57f-2b1d74942543

  - `data.customFields.type` (any, required)
    Custom field type.

  - `data.customFields.name` (string, required)

  - `data.customFields.qualifiedName` (string, required)

  - `data.customFields.value` (string, required)

  - `data.timeZone` (any)

  - `meta` (object, required)

  - `meta.limit` (integer)

  - `meta.offset` (integer)

  - `meta.total` (integer)

## Response 400:

  - `400` (unknown)
    The request parameters are invalid. Check filters, pagination or projection options.

## Response 400 fields (application/json):

  - `title` (string, required)
    General title of error
    Example: Bad Request

  - `detail` (string | null)
    Detailed error message explaining the issue
    Example: Invalid parameter value

## Response 401:

  - `401` (unknown)
    Authorization error - e.g. invalid server url, no Authorization header, wrong user / API key

## Response 401 fields (application/problem+json):

  - `title` (string, required)
    Type of error
    Example: Authentication failure

  - `status` (string, required)
    HTTP status code
    Example: 401

  - `detail` (string, required)
    Detailed error message explaining the issue.
    Example: Please check if valid API key was provided

## Response 403:

  - `403` (unknown)
    You do not have permission to access this resource.

## Response 403 fields (application/json):

  - `title` (string, required)
    General title of error
    Example: Forbidden

  - `detail` (string | null)
    Detailed error message explaining the issue
    Example: Token does not have the required scope

## Response 429:

  - `429` (unknown)
    Maximum number of requests was exceeded - either per second, hour or day.

## Response 429 fields (application/problem+json):

  - `title` (string, required)
    Type of error
    Example: Request quota exceeded

  - `status` (string, required)
    HTTP status code
    Example: 429

  - `detail` (string, required)
    Detailed error message explaining the issue.
    Example: Your current usage is 101/day, 10/hour, 1/sec
Your current limits 100/day, 10/hour, 1/sec.

## Response 500:

  - `500` (unknown)
    Internal server error - something went wrong!

## Response 500 fields (application/problem+json):

  - `title` (string, required)
    Type of error
    Example: Internal server error.

  - `status` (string, required)
    HTTP status code
    Example: 500

  - `detail` (string, required)
    Detailed error message explaining the issue.
    Example: Please try again later. If the issue persists, don't hesitate to reach to our Support via team@calamari.io

## Response 504:

  - `504` (unknown)
    Gateway timeout - call to downstream service exceeded maximum configured amount of time

## Response 504 fields (application/problem+json):

  - `title` (string, required)
    Type of error
    Example: Public API call exceeded timeout.

  - `status` (string, required)
    HTTP status code
    Example: 504

  - `detail` (string, required)
    Detailed error message explaining the issue.
    Example: Please try again later. If the issue persists, don't hesitate to reach to our Support via team@calamari.io