# 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

## Query parameters:

  - `contractTypes` (array)
    Comma-separated list of contract type UUIDs used to filter people by contract types.
    Example: "41d2e841-7f1f-4545-be09-8a17606f0228,31d2e841-7f1f-4545-be09-8a17606f0228"

  - `positions` (array)
    Comma-separated list of position IDs used to filter people by positions.
    Example: "1,2,3,4"

  - `teams` (array)
    Comma-separated list of team IDs used to filter people by team membership.
    Example: "1,2,3,7,8"

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

  - `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.
    Enum: "FULL", "BASIC", "CUSTOM"

  - `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.
    Example: "firstName,lastName,email"

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

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

  - `sort` (array)
    Sorting criteria in the format field,ASC or field,DESC. Can be repeated to apply multi-level sorting.
    Example: ["id,DESC","name,ASC"]

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

## Response 200 fields (application/json):

  - `data` (array, required)
    Collection of items.

  - `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.birthdate` (any)

  - `data.businessContact` (any)

  - `data.personalContact` (any)

  - `data.address` (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.approvalFlow` (any)

  - `data.contractType` (any)

  - `data.holidaysCalendar` (any)

  - `data.workSchedule` (any)

  - `data.teams` (any)

  - `data.directManager` (any)

  - `data.bankAccountNumber` (any)

  - `data.shirtSize` (any)

  - `data.contractorDetails` (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.sex` (string,null)
    Sex.
    Enum: "MALE", "FEMALE", "OTHER", null

  - `data.children.parent` (any)

  - `data.customFields` (any)

  - `data.timeZone` (any)

  - `meta` (object, required)
    Collection of items.

  - `meta.limit` (integer)
    Current limit
    Example: 1

  - `meta.offset` (integer)
    Current offset
    Example: 10

  - `meta.total` (integer)
    Total items
    Example: 100

## 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 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 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 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\nYour current limits 100/day, 10/hour, 1/sec."

## 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 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"