---
title: "List people"
method: GET
path: "/v1/people"
tags: ["People"]
---

# List people

`GET /v1/people`

Retrieve a list of people in the workspace.

## Query parameters

- `limit` integer
- `cursor` string
- `combinator` 'and' | 'or'
- `filter` object

## Response `200`

A paginated list of people in the workspace.

- object
  - `data` object, required
    - `items` Person[], required
      - `id` string, required
      - `firstName` string, required — The first name of the person.
      - `lastName` string, required — The last name of the person.
      - `fullName` string, required — The full name of the person.
      - `description` string, required — A short description of the person.
      - `birthday` string, date, nullable, required — The birthday of the person, in ISO format. Deleted with null or empty string.
      - `gender` 'Male' | 'Female' | 'Unknown' | 'Other', nullable, required — The gender of the person. Authorized values are "Female", "Male", "Unknown", "Other" or null to delete it.
      - `jobTitle` string, required — The job title of the person.
      - `createdAt` string, nullable, required — The date and time the person was created, in ISO format.
      - `createdBy` User, required — A user in the workspace.
        - `id` string, required
        - `fullName` string, required
        - `email` string, required
      - `groups` object[], required — The groups associated with the person.
        - `id` string, required
        - `name` string, required
      - `companies` object[], required — The companies associated with the person. The first company in the list is the person's primary company.
        - `id` string, required — The id of the company.
        - `name` string, required — The name of the company.
      - `addresses` string[], required
      - `emails` string[], required
      - `phones` string[], required
      - `urls` string[], required
      - `customFieldValues` object, required
      - `interactionMetadata` InteractionMetadata, required — Metadata about interactions with the user and workspace.
        - `user` object, required
          - `approximateCount` integer, required — The approximate number of interactions between the current user and the contact.
          - `lastInteractedAt` string, date-time, nullable, required — The last interaction date between the current user and the contact.
        - `workspace` object, required
          - `approximateCount` integer, required — The approximate number of interactions of your workspace with the contact.
          - `lastInteractedAt` string, date-time, nullable, required — The last interaction date of your workspace with the contact.
          - `lastInteractedBy` User[], required — List of users in your workspace who last interacted with the contact.
            - `id` string, required
            - `fullName` string, required
            - `email` string, required
      - `strongestConnection` object — For each group the person is in, the workspace member with the strongest connection to the person. If the person has no strongest connection, this will be an empty object. Only the groups for which the person has a strongest connection will be included.
    - `pagination` object, required
      - `nextLink` string
  - `deprecations` string[]

## Other responses

- `400` — The request was unacceptable, often due to missing an invalid parameter.
- `401` — No valid API key provided.
- `403` — The API key doesn’t have permissions to perform the request.
- `404` — The requested resource doesn’t exist.
- `422` — The request was unacceptable, often due to missing or invalid parameters.
- `429` — Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
- `500` — Something went wrong on our end.
- `503` — The server is overloaded or down for maintenance.

---

[API](https://skmtc.dev/folk/apis/folk-external-api.md) · [All operations](https://skmtc.dev/folk/apis/folk-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/folk/folk-external-api/revisions/8ecbf0ccd00a/schema)