> ## Documentation Index
> Fetch the complete documentation index at: https://lava.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Folk
> People-first CRM API for managing contacts, companies, deals, and notes across customizable pipelines.
People-first CRM API for managing contacts, companies, deals, and notes across customizable pipelines. Best for agents that need to sync contacts, log meeting notes, or manage deal flow in a lightweight CRM. Unlike HubSpot or Salesforce, Folk is designed for small teams with a flat data model and one-click enrichment.
12 example endpoints available through Lava's AI Gateway. See the [Folk API docs](https://developer.folk.app/api-reference/overview) for full documentation.
This provider requires your own credentials — connect your API key or OAuth account before use.
This is a **catch-all provider** — any valid URL under `https://api.folk.app` is supported. Folk CRM API. Base: [https://api.folk.app](https://api.folk.app), all paths under /v1/. Auth: Bearer token (generate at app.folk.app settings > API keys). Rate limit: 600 req/min. Resources: /v1/people, /v1/companies, /v1/notes, /v1/groups, /v1/users, /v1/webhooks, /v1/reminders, /v1/interactions. Deals are group sub-resources: POST /v1/groups/\{groupId}/\{objectType} — get groupId and objectType from GET /v1/groups and GET /v1/groups/custom-fields first. Cursor pagination: pass cursor + limit params, follow pagination.nextLink in response. Requires Folk Premium plan or higher. See [https://developer.folk.app/api-reference/overview](https://developer.folk.app/api-reference/overview) for full reference. The endpoints below are curated examples.
## Endpoints
### Get the current authenticated user. Use as an auth check after connecting a Folk API key.
**GET** `https://api.folk.app/v1/users/me` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/users/me', { method: 'GET' });
```
```bash theme={null}
curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fusers%2Fme" \
-H "Authorization: Bearer $LAVA_SECRET_KEY"
```
### List contacts with cursor-based pagination. Supports cursor and limit query params.
**GET** `https://api.folk.app/v1/people?limit=50` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/people?limit=50', { method: 'GET' });
```
```bash theme={null}
curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fpeople%3Flimit%3D50" \
-H "Authorization: Bearer $LAVA_SECRET_KEY"
```
### Create a new contact. Supports firstName, lastName, emails, phones, jobTitle, companies, and custom fields.
**POST** `https://api.folk.app/v1/people` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/people', {
body: {
"firstName": "Jane",
"lastName": "Smith",
"emails": [
"jane@example.com"
],
"jobTitle": "CEO"
},
});
```
```bash theme={null}
curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fpeople" \
-H "Authorization: Bearer $LAVA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"firstName":"Jane","lastName":"Smith","emails":["jane@example.com"],"jobTitle":"CEO"}'
```
### Update an existing contact by ID. Send only the fields to change.
**PATCH** `https://api.folk.app/v1/people/per_55175e81-9a52-4ac3-930e-82792c23499b` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/people/per_55175e81-9a52-4ac3-930e-82792c23499b', { method: 'PATCH', body: {"jobTitle":"CTO","phones":["+1234567890"]} });
```
```bash theme={null}
curl -X PATCH "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fpeople%2Fper_55175e81-9a52-4ac3-930e-82792c23499b" \
-H "Authorization: Bearer $LAVA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"jobTitle":"CTO","phones":["+1234567890"]}'
```
### Delete a contact by ID. This action is irreversible and removes all associated data including custom fields, notes, and relationships.
**DELETE** `https://api.folk.app/v1/people/per_55175e81-9a52-4ac3-930e-82792c23499b` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/people/per_55175e81-9a52-4ac3-930e-82792c23499b', { method: 'DELETE' });
```
```bash theme={null}
curl -X DELETE "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fpeople%2Fper_55175e81-9a52-4ac3-930e-82792c23499b" \
-H "Authorization: Bearer $LAVA_SECRET_KEY" \
-H "Content-Type: application/json"
```
### List companies with cursor-based pagination.
**GET** `https://api.folk.app/v1/companies?limit=50` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/companies?limit=50', { method: 'GET' });
```
```bash theme={null}
curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fcompanies%3Flimit%3D50" \
-H "Authorization: Bearer $LAVA_SECRET_KEY"
```
### Create a new company. Supports name, description, industry, emails, urls, and custom fields.
**POST** `https://api.folk.app/v1/companies` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/companies', {
body: {
"name": "Acme Corp",
"industry": "Technology",
"urls": [
"https://acme.com"
]
},
});
```
```bash theme={null}
curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fcompanies" \
-H "Authorization: Bearer $LAVA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Acme Corp","industry":"Technology","urls":["https://acme.com"]}'
```
### Create a note attached to a person or company. Content supports markdown.
**POST** `https://api.folk.app/v1/notes` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/notes', {
body: {
"entity": {
"id": "per_55175e81-9a52-4ac3-930e-82792c23499b"
},
"visibility": "public",
"content": "Follow-up meeting scheduled for next week."
},
});
```
```bash theme={null}
curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fnotes" \
-H "Authorization: Bearer $LAVA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"entity":{"id":"per_55175e81-9a52-4ac3-930e-82792c23499b"},"visibility":"public","content":"Follow-up meeting scheduled for next week."}'
```
### List all groups (segments/lists) in the workspace. Groups organize contacts into pipelines and lists.
**GET** `https://api.folk.app/v1/groups` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/groups', { method: 'GET' });
```
```bash theme={null}
curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fgroups" \
-H "Authorization: Bearer $LAVA_SECRET_KEY"
```
### List custom field definitions. Use for schema discovery before writing records with custom fields.
**GET** `https://api.folk.app/v1/groups/custom-fields` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/groups/custom-fields', { method: 'GET' });
```
```bash theme={null}
curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fgroups%2Fcustom-fields" \
-H "Authorization: Bearer $LAVA_SECRET_KEY"
```
### Record an interaction (call, meeting, email, coffee, etc.) against a person or company. Append-only log for agent attribution.
**POST** `https://api.folk.app/v1/interactions` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/interactions', {
body: {
"entity": {
"id": "per_55175e81-9a52-4ac3-930e-82792c23499b"
},
"dateTime": "2026-04-15T14:00:00.000Z",
"title": "Intro call with Jane Smith",
"content": "Discussed partnership opportunity.",
"type": "call"
},
});
```
```bash theme={null}
curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Finteractions" \
-H "Authorization: Bearer $LAVA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"entity":{"id":"per_55175e81-9a52-4ac3-930e-82792c23499b"},"dateTime":"2026-04-15T14:00:00.000Z","title":"Intro call with Jane Smith","content":"Discussed partnership opportunity.","type":"call"}'
```
### Register a webhook to receive notifications when contacts, companies, or other records change in Folk.
**POST** `https://api.folk.app/v1/webhooks` — Free
```typescript theme={null}
const data = await lava.gateway('https://api.folk.app/v1/webhooks', {
body: {
"name": "Contact sync",
"targetUrl": "https://example.com/folk-webhook",
"subscribedEvents": [
{
"eventType": "person.created"
}
]
},
});
```
```bash theme={null}
curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fapi.folk.app%2Fv1%2Fwebhooks" \
-H "Authorization: Bearer $LAVA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Contact sync","targetUrl":"https://example.com/folk-webhook","subscribedEvents":[{"eventType":"person.created"}]}'
```
## Next Steps
Browse all supported AI providers
Learn how to construct proxy URLs and authenticate requests