Create a view
curl --request POST \
--url https://api.folk.app/v1/views \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"groupId": "grp_92ab3f1c-0386-434d-82d7-a91eb6badd71",
"name": "Hot leads",
"entityType": "person",
"type": "table",
"filter": {
"combinator": "and",
"conditions": [
{
"field": "jobTitle",
"operator": "like",
"value": "engineer"
}
]
},
"visibleFields": [
"jobTitle",
"companies",
"emails"
],
"position": {
"after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
groupId: 'grp_92ab3f1c-0386-434d-82d7-a91eb6badd71',
name: 'Hot leads',
entityType: 'person',
type: 'table',
filter: {
combinator: 'and',
conditions: [{field: 'jobTitle', operator: 'like', value: 'engineer'}]
},
visibleFields: ['jobTitle', 'companies', 'emails'],
position: {after: 'viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71'}
})
};
fetch('https://api.folk.app/v1/views', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/views"
payload = {
"groupId": "grp_92ab3f1c-0386-434d-82d7-a91eb6badd71",
"name": "Hot leads",
"entityType": "person",
"type": "table",
"filter": {
"combinator": "and",
"conditions": [
{
"field": "jobTitle",
"operator": "like",
"value": "engineer"
}
]
},
"visibleFields": ["jobTitle", "companies", "emails"],
"position": { "after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)require 'uri'
require 'net/http'
url = URI("https://api.folk.app/v1/views")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"groupId\": \"grp_92ab3f1c-0386-434d-82d7-a91eb6badd71\",\n \"name\": \"Hot leads\",\n \"entityType\": \"person\",\n \"type\": \"table\",\n \"filter\": {\n \"combinator\": \"and\",\n \"conditions\": [\n {\n \"field\": \"jobTitle\",\n \"operator\": \"like\",\n \"value\": \"engineer\"\n }\n ]\n },\n \"visibleFields\": [\n \"jobTitle\",\n \"companies\",\n \"emails\"\n ],\n \"position\": {\n \"after\": \"viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71\"\n }\n}"
response = http.request(request)
puts response.read_bodypackage main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/views"
payload := strings.NewReader("{\n \"groupId\": \"grp_92ab3f1c-0386-434d-82d7-a91eb6badd71\",\n \"name\": \"Hot leads\",\n \"entityType\": \"person\",\n \"type\": \"table\",\n \"filter\": {\n \"combinator\": \"and\",\n \"conditions\": [\n {\n \"field\": \"jobTitle\",\n \"operator\": \"like\",\n \"value\": \"engineer\"\n }\n ]\n },\n \"visibleFields\": [\n \"jobTitle\",\n \"companies\",\n \"emails\"\n ],\n \"position\": {\n \"after\": \"viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
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/views",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'groupId' => 'grp_92ab3f1c-0386-434d-82d7-a91eb6badd71',
'name' => 'Hot leads',
'entityType' => 'person',
'type' => 'table',
'filter' => [
'combinator' => 'and',
'conditions' => [
[
'field' => 'jobTitle',
'operator' => 'like',
'value' => 'engineer'
]
]
],
'visibleFields' => [
'jobTitle',
'companies',
'emails'
],
'position' => [
'after' => 'viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"data": {
"id": "viw_3f1c9a2e-0386-434d-82d7-a91eb6badd71",
"groupId": "grp_92ab3f1c-0386-434d-82d7-a91eb6badd71",
"name": "Hot leads",
"entityType": "person",
"filter": {
"combinator": "and",
"conditions": [
{
"field": "interactionMetadata.workspace.lastInteractedAt",
"operator": "gt",
"value": "30-days-ago"
}
]
},
"visibleFields": [
"jobTitle",
"companies",
"emails"
],
"position": {
"after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71"
},
"createdAt": "2025-07-17T09:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"type": "table",
"sort": {
"field": "interactionMetadata.user.lastInteractedAt",
"direction": "desc"
}
}
}{
"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": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "A request with the same Idempotency-Key is still being processed. Retry once it has completed.",
"documentationUrl": "https://developer.folk.app/api-reference/idempotency#errors",
"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": "TOO_MANY_REQUESTS",
"message": "You have exceeded your rate limit.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z",
"details": {
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z",
"policies": [
{
"policy": "default",
"limit": 600,
"remaining": 412,
"windowSeconds": 60,
"retryAfter": "2025-10-01T12:01:00.000Z"
},
{
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z"
}
]
}
}
}{
"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"
}
}Views
Create a view
Create a view in a group: a table view, or a kanban view grouped by a single select field. The settings that aren’t sent get the defaults of the entity type and the view type.
POST
/
v1
/
views
Create a view
curl --request POST \
--url https://api.folk.app/v1/views \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"groupId": "grp_92ab3f1c-0386-434d-82d7-a91eb6badd71",
"name": "Hot leads",
"entityType": "person",
"type": "table",
"filter": {
"combinator": "and",
"conditions": [
{
"field": "jobTitle",
"operator": "like",
"value": "engineer"
}
]
},
"visibleFields": [
"jobTitle",
"companies",
"emails"
],
"position": {
"after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
groupId: 'grp_92ab3f1c-0386-434d-82d7-a91eb6badd71',
name: 'Hot leads',
entityType: 'person',
type: 'table',
filter: {
combinator: 'and',
conditions: [{field: 'jobTitle', operator: 'like', value: 'engineer'}]
},
visibleFields: ['jobTitle', 'companies', 'emails'],
position: {after: 'viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71'}
})
};
fetch('https://api.folk.app/v1/views', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/views"
payload = {
"groupId": "grp_92ab3f1c-0386-434d-82d7-a91eb6badd71",
"name": "Hot leads",
"entityType": "person",
"type": "table",
"filter": {
"combinator": "and",
"conditions": [
{
"field": "jobTitle",
"operator": "like",
"value": "engineer"
}
]
},
"visibleFields": ["jobTitle", "companies", "emails"],
"position": { "after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)require 'uri'
require 'net/http'
url = URI("https://api.folk.app/v1/views")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"groupId\": \"grp_92ab3f1c-0386-434d-82d7-a91eb6badd71\",\n \"name\": \"Hot leads\",\n \"entityType\": \"person\",\n \"type\": \"table\",\n \"filter\": {\n \"combinator\": \"and\",\n \"conditions\": [\n {\n \"field\": \"jobTitle\",\n \"operator\": \"like\",\n \"value\": \"engineer\"\n }\n ]\n },\n \"visibleFields\": [\n \"jobTitle\",\n \"companies\",\n \"emails\"\n ],\n \"position\": {\n \"after\": \"viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71\"\n }\n}"
response = http.request(request)
puts response.read_bodypackage main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/views"
payload := strings.NewReader("{\n \"groupId\": \"grp_92ab3f1c-0386-434d-82d7-a91eb6badd71\",\n \"name\": \"Hot leads\",\n \"entityType\": \"person\",\n \"type\": \"table\",\n \"filter\": {\n \"combinator\": \"and\",\n \"conditions\": [\n {\n \"field\": \"jobTitle\",\n \"operator\": \"like\",\n \"value\": \"engineer\"\n }\n ]\n },\n \"visibleFields\": [\n \"jobTitle\",\n \"companies\",\n \"emails\"\n ],\n \"position\": {\n \"after\": \"viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
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/views",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'groupId' => 'grp_92ab3f1c-0386-434d-82d7-a91eb6badd71',
'name' => 'Hot leads',
'entityType' => 'person',
'type' => 'table',
'filter' => [
'combinator' => 'and',
'conditions' => [
[
'field' => 'jobTitle',
'operator' => 'like',
'value' => 'engineer'
]
]
],
'visibleFields' => [
'jobTitle',
'companies',
'emails'
],
'position' => [
'after' => 'viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"data": {
"id": "viw_3f1c9a2e-0386-434d-82d7-a91eb6badd71",
"groupId": "grp_92ab3f1c-0386-434d-82d7-a91eb6badd71",
"name": "Hot leads",
"entityType": "person",
"filter": {
"combinator": "and",
"conditions": [
{
"field": "interactionMetadata.workspace.lastInteractedAt",
"operator": "gt",
"value": "30-days-ago"
}
]
},
"visibleFields": [
"jobTitle",
"companies",
"emails"
],
"position": {
"after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71"
},
"createdAt": "2025-07-17T09:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"type": "table",
"sort": {
"field": "interactionMetadata.user.lastInteractedAt",
"direction": "desc"
}
}
}{
"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": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "A request with the same Idempotency-Key is still being processed. Retry once it has completed.",
"documentationUrl": "https://developer.folk.app/api-reference/idempotency#errors",
"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": "TOO_MANY_REQUESTS",
"message": "You have exceeded your rate limit.",
"documentationUrl": "https://developer.folk.app/api-reference/errors#rate-limiting",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"timestamp": "2025-10-01T12:00:00Z",
"details": {
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z",
"policies": [
{
"policy": "default",
"limit": 600,
"remaining": 412,
"windowSeconds": 60,
"retryAfter": "2025-10-01T12:01:00.000Z"
},
{
"policy": "burst",
"limit": 20,
"remaining": 0,
"windowSeconds": 2,
"retryAfter": "2025-10-01T12:00:02.000Z"
}
]
}
}
}{
"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
API key for authentication
Headers
A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.
Maximum string length:
255Example:
"8e03978e-40d5-43e8-bc93-6894a57f9324"
Body
application/json
- Option 1
- Option 2
A view of a group. Its settings depend on its type: sort for table views, groupBy and columns for kanban views.
The group the view belongs to.
Required string length:
40Example:
"grp_92ab3f1c-0386-434d-82d7-a91eb6badd71"
The name of the view, as shown in the app.
Required string length:
1 - 500Example:
"Hot leads"
The entity type of the view: person, company, or the name of an object type of the group.
Maximum string length:
500Example:
"person"
Available options:
table The filter of the view, null or absent for no filter. Unlike the search endpoints, the filter is a list of conditions.
Show child attributes
Show child attributes
The fields shown by the view, in display order, with the same keys as the filter, at most 100. The name column is always shown and is never listed.
Maximum array length:
100Maximum string length:
1000Example:
["jobTitle", "companies", "emails"]
Where the view goes among the views of its group: { "after": <viewId> }, { "before": <viewId> }, { "after": null } for the first position or { "before": null } for the last one. Last by default.
- Option 1
- Option 2
Show child attributes
Show child attributes
Example:
{
"after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71"
}
The sort of the view. When the sorted field no longer exists, the default sort of the entity type is returned.
Show child attributes
Show child attributes
Response
The created view.
A view of a group. Its settings depend on its type: sort for table views, groupBy and columns for kanban views.
- Option 1
- Option 2
Show child attributes
Show child attributes
Example:
{
"id": "viw_3f1c9a2e-0386-434d-82d7-a91eb6badd71",
"groupId": "grp_92ab3f1c-0386-434d-82d7-a91eb6badd71",
"name": "Hot leads",
"entityType": "person",
"filter": {
"combinator": "and",
"conditions": [
{
"field": "interactionMetadata.workspace.lastInteractedAt",
"operator": "gt",
"value": "30-days-ago"
}
]
},
"visibleFields": ["jobTitle", "companies", "emails"],
"position": {
"after": "viw_1b2c3d4e-0386-434d-82d7-a91eb6badd71"
},
"createdAt": "2025-07-17T09:00:00.000Z",
"createdBy": {
"id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
"fullName": "John Doe",
"email": "john.doe@example.com"
},
"type": "table",
"sort": {
"field": "interactionMetadata.user.lastInteractedAt",
"direction": "desc"
}
}
Example:
["This field is deprecated"]