List upcoming interactions
curl --request GET \
--url https://api.folk.app/v1/interactions/upcoming \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.folk.app/v1/interactions/upcoming', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/interactions/upcoming"
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/interactions/upcoming")
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_bodypackage main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/interactions/upcoming"
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/interactions/upcoming",
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": "lit_b049db09-c03d-4f32-96d6-d314760add5d",
"interactionType": "logged",
"from": {
"type": "user",
"value": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
"name": "John Doe"
},
"to": {
"type": "person",
"value": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"name": "John Doe"
},
"entity": {
"id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"entityType": "person",
"fullName": "John Doe"
},
"dateTime": "2025-07-17T09:00:00.000Z",
"privacyLevel": "sharedFull",
"title": "Coffee with John Doe",
"content": "Had a coffee with John Doe\nDiscussed the new project.",
"type": "coffee",
"activityType": "coffee"
}
],
"pagination": {
"nextLink": "https://api.folk.app/v1/interactions/upcoming?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b&cursor=eyJmb28iOiJiYXIifQ%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": "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"
}
}Interactions
(Beta) List upcoming interactions
deprecated
Retrieves paginated upcoming interactions linked to a person, company, or object.
This endpoint is currently in open beta. The API surface may change as we iterate based on feedback.
This endpoint is deprecated since September 29, 2026 and will be removed on March 29, 2027. Please use the List interactions endpoint instead.
GET
/
v1
/
interactions
/
upcoming
List upcoming interactions
curl --request GET \
--url https://api.folk.app/v1/interactions/upcoming \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.folk.app/v1/interactions/upcoming', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.folk.app/v1/interactions/upcoming"
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/interactions/upcoming")
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_bodypackage main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.folk.app/v1/interactions/upcoming"
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/interactions/upcoming",
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": "lit_b049db09-c03d-4f32-96d6-d314760add5d",
"interactionType": "logged",
"from": {
"type": "user",
"value": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
"name": "John Doe"
},
"to": {
"type": "person",
"value": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"name": "John Doe"
},
"entity": {
"id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"entityType": "person",
"fullName": "John Doe"
},
"dateTime": "2025-07-17T09:00:00.000Z",
"privacyLevel": "sharedFull",
"title": "Coffee with John Doe",
"content": "Had a coffee with John Doe\nDiscussed the new project.",
"type": "coffee",
"activityType": "coffee"
}
],
"pagination": {
"nextLink": "https://api.folk.app/v1/interactions/upcoming?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b&cursor=eyJmb28iOiJiYXIifQ%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": "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
Query Parameters
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:
512The person, company, or object linked to interactions.
Required string length:
40Response
A paginated list of upcoming interactions with optional pagination link.
Show child attributes
Show child attributes
Example:
{
"items": [
{
"id": "lit_b049db09-c03d-4f32-96d6-d314760add5d",
"interactionType": "logged",
"from": {
"type": "user",
"value": "usr_14c18444-a0c7-459a-86b0-ccd70ebcd65c",
"name": "John Doe"
},
"to": {
"type": "person",
"value": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"name": "John Doe"
},
"entity": {
"id": "per_55175e81-9a52-4ac3-930e-82792c23499b",
"entityType": "person",
"fullName": "John Doe"
},
"dateTime": "2025-07-17T09:00:00.000Z",
"privacyLevel": "sharedFull",
"title": "Coffee with John Doe",
"content": "Had a coffee with John Doe\nDiscussed the new project.",
"type": "coffee",
"activityType": "coffee"
}
],
"pagination": {
"nextLink": "https://api.folk.app/v1/interactions/upcoming?entity.id=per_55175e81-9a52-4ac3-930e-82792c23499b&cursor=eyJmb28iOiJiYXIifQ%3D%3D"
}
}
Example:
["This field is deprecated"]