Skip to main content
GET
/
v1
/
people
List people
curl --request GET \
  --url https://api.folk.app/v1/people \
  --header 'Authorization: Bearer <token>'
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.folk.app/v1/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
import requests

url = "https://api.folk.app/v1/people"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
require 'uri'
require 'net/http'

url = URI("https://api.folk.app/v1/people")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.folk.app/v1/people"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.folk.app/v1/people",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
{
  "data": {
    "items": [
      {
        "id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
        "firstName": "John",
        "lastName": "Doe",
        "fullName": "John Doe",
        "description": "John Doe is a software engineer at Tech Corp.",
        "birthday": "1980-06-15",
        "gender": "Female",
        "jobTitle": "Software Engineer",
        "createdAt": "2021-01-01T00:00:00.000Z",
        "createdBy": {
          "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
          "fullName": "John Doe",
          "email": "john.doe@example.com"
        },
        "groups": [
          {
            "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
            "name": "Engineering"
          }
        ],
        "companies": [
          {
            "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
            "name": "Tech Corp"
          }
        ],
        "addresses": [
          "123 Main St, Springfield, USA",
          "456 Main St, Springfield, USA"
        ],
        "emails": [
          "john@example.com",
          "john@techcorp.com"
        ],
        "phones": [
          "+1234567890",
          "+0987654321"
        ],
        "urls": [
          "https://example.com"
        ],
        "customFieldValues": {
          "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
            "Status": "Active",
            "Programming languages": [
              "Javascript",
              "Python"
            ],
            "Join date": "2021-01-01",
            "Relationships": [
              {
                "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f",
                "fullName": "Bob Smith",
                "entityType": "person"
              },
              {
                "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03",
                "fullName": "HR services",
                "entityType": "company"
              }
            ]
          },
          "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
            "Favorite color": "Blue",
            "Favorite number": "42",
            "Assignee": [
              {
                "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
                "fullName": "Jane Doe",
                "email": "jane@example.com"
              }
            ]
          }
        },
        "interactionMetadata": {
          "user": {
            "approximateCount": 21,
            "lastInteractedAt": "2025-05-01T00:00:00Z"
          },
          "workspace": {
            "approximateCount": 21,
            "lastInteractedAt": "2025-05-01T00:00:00Z",
            "lastInteractedBy": [
              {
                "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
                "fullName": "John Doe",
                "email": "john.doe@example.com"
              }
            ]
          }
        },
        "strongestConnection": {
          "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
            "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
            "fullName": "John Doe",
            "email": "john.doe@example.com"
          }
        }
      }
    ],
    "pagination": {
      "nextLink": "https://api.folk.app/v1/people?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D"
    }
  }
}
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request was invalid.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#bad-request",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No valid API key provided.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unauthorized",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "The API key doesn’t have permissions to perform the request.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#forbidden",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#not-found",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}
{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Invalid query parameters",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#unprocessable-entity",
    "details": {
      "issues": [
        {
          "code": "too_small",
          "minimum": 1,
          "type": "number",
          "inclusive": true,
          "exact": false,
          "message": "Number must be greater than or equal to 1",
          "path": [
            "limit"
          ]
        }
      ]
    },
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "The rate limit has been exceeded.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "retryAfter": "2025-10-01T12:00:00Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal server error occurred.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#internal-server-error",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is currently unavailable.",
    "documentationUrl": "https://developer.folk.app/api-reference/errors#service-unavailable",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2025-10-01T12:00:00Z"
  }
}

Authorizations

​
Authorization
string
header
required

API key for authentication

Query Parameters

​
limit
integer
default:20

The number of items to return.

Required range: 1 <= x <= 100
​
cursor
string

A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the pagination.nextLink value returned in a previous response to request subsequent results.

Maximum string length: 512
​
combinator
enum<string>
default:and

The logical operator to combine multiple filters.

Available options:
and,
or
​
filter
object

A record of filters to apply, following the format filter[attribute][operator]=value. The attribute is the name of the attribute to filter on, and the operator is one of the supported filter operators. Refer to Filterable fields to learn more about the supported attributes and operators.

Response

A paginated list of people in the workspace.

​
data
object
required
Example:
{
  "items": [
    {
      "id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "description": "John Doe is a software engineer at Tech Corp.",
      "birthday": "1980-06-15",
      "gender": "Female",
      "jobTitle": "Software Engineer",
      "createdAt": "2021-01-01T00:00:00.000Z",
      "createdBy": {
        "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
        "fullName": "John Doe",
        "email": "john.doe@example.com"
      },
      "groups": [
        {
          "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
          "name": "Engineering"
        }
      ],
      "companies": [
        {
          "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
          "name": "Tech Corp"
        }
      ],
      "addresses": [
        "123 Main St, Springfield, USA",
        "456 Main St, Springfield, USA"
      ],
      "emails": ["john@example.com", "john@techcorp.com"],
      "phones": ["+1234567890", "+0987654321"],
      "urls": ["https://example.com"],
      "customFieldValues": {
        "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
          "Status": "Active",
          "Programming languages": ["Javascript", "Python"],
          "Join date": "2021-01-01",
          "Relationships": [
            {
              "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f",
              "fullName": "Bob Smith",
              "entityType": "person"
            },
            {
              "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03",
              "fullName": "HR services",
              "entityType": "company"
            }
          ]
        },
        "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
          "Favorite color": "Blue",
          "Favorite number": "42",
          "Assignee": [
            {
              "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
              "fullName": "Jane Doe",
              "email": "jane@example.com"
            }
          ]
        }
      },
      "interactionMetadata": {
        "user": {
          "approximateCount": 21,
          "lastInteractedAt": "2025-05-01T00:00:00Z"
        },
        "workspace": {
          "approximateCount": 21,
          "lastInteractedAt": "2025-05-01T00:00:00Z",
          "lastInteractedBy": [
            {
              "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
              "fullName": "John Doe",
              "email": "john.doe@example.com"
            }
          ]
        }
      },
      "strongestConnection": {
        "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
          "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
          "fullName": "John Doe",
          "email": "john.doe@example.com"
        }
      }
    }
  ],
  "pagination": {
    "nextLink": "https://api.folk.app/v1/people?limit=20&cursor=eyJvZmZzZXQiOjIwfQ%3D%3D"
  }
}
​
deprecations
string[]
Example:
["This field is deprecated"]