VX Agents

OpenAPI Marketplace · CRM & Sales

folk CRM People, Companies & Deals

v1.0.0 · 21 endpoints · 0 connections · shared by vx.ai

After a client call, find the contact in folk, log the interaction, add a note and set a follow-up task, then move the deal forward in its group. Covers people, companies, deals, notes, tasks and interactions, with folk's field filters (email domain, group, last interaction date).

Connect this API to an AI agent Browse all specs

What you can do with folk CRM People, Companies & Deals via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /v1/users/me getCurrentUser Get the folk user the API key belongs to
GET /v1/groups listGroups List the workspace's groups (pipelines and lists)
GET /v1/people listPeople List or filter contacts (by name, email, group, company...)
POST /v1/people createPerson Add a new contact
GET /v1/people/{personId} getPerson Get a contact with emails, phones, companies and custom fields
PATCH /v1/people/{personId} updatePerson Update a contact's details, groups or custom fields
GET /v1/companies listCompanies List or filter companies
POST /v1/companies createCompany Add a new company
GET /v1/companies/{companyId} getCompany Get a company
PATCH /v1/companies/{companyId} updateCompany Update a company's details or custom fields
GET /v1/groups/{groupId}/{objectType} listDeals List deals of one type in a group
POST /v1/groups/{groupId}/{objectType} createDeal Create a deal in a group
GET /v1/groups/{groupId}/{objectType}/{objectId} getDeal Get a deal with its people, companies and custom fields
PATCH /v1/groups/{groupId}/{objectType}/{objectId} updateDeal Update a deal: name, linked people and companies, custom fields such as status
GET /v1/notes listNotes List notes, optionally for one contact, company or deal
POST /v1/notes createNote Add a note to a contact, company or deal
GET /v1/tasks listTasks List tasks, optionally filtered
POST /v1/tasks createTask Create a follow-up task on a contact, company or deal
POST /v1/tasks/{taskId}/mark-as-done markTaskAsDone Mark a task as done
GET /v1/interactions listInteractions List past or upcoming interactions with a contact or company (beta)
POST /v1/interactions createInteraction Log a call, meeting or message with a contact or company

Authentication

bearerApiKeyAuth

Bearer token — sent as Authorization: Bearer <token>

folk API key, sent as Authorization: Bearer <key>.

How to get a credential

  1. Sign in to folk and open Settings > API (https://app.folk.app/apps/contacts/network/settings/api-keys).
  2. Click Generate a new API key, give it a name and copy it; it is shown once.
  3. The key acts as you: it sees the groups and records your folk user can see.

Permissions used

Access Operations
Your workspace user (read) getCurrentUser, listGroups, listPeople, getPerson, listCompanies, getCompany, listDeals, getDeal, listNotes, listTasks, listInteractions
Your workspace user (write) createPerson, updatePerson, createCompany, updateCompany, createDeal, updateDeal, createNote, createTask, markTaskAsDone, createInteraction

Common errors

  • 401 Unauthorized: missing or revoked API key. Generate a new one.
  • 403 Forbidden: your user has no access to that group or record.
  • 404 Not Found: wrong id, or the deal objectType does not match the group's deal type name.
  • 400/422: invalid body or filter (ids are 40 characters, e.g. per_..., com_..., grp_...).
  • 429 Too Many Requests: limits are 600 requests per minute and 20 per 2 seconds per user. Wait for Retry-After.

Store the key as a bearer credential in VX Agents; never paste it into chat.

Usage guide

Setup

  • Credential: a folk API key (Settings > API), stored as a bearer credential. It acts as the folk user who created it.
  • Worth pinning: the groupId of your main pipeline group and its deal objectType (the deal type name shown in that group, e.g. Deals), so deal tools need no lookup.

After a client call

  1. getCurrentUser once to know who "me" is.
  2. Find the contact: listPeople with a filter, e.g. filter[fullName][eq]=Jane Doe, filter[emails][like][email protected], or filter[companies][in][id]=com_.... Then getPerson for full details. Companies work the same way with listCompanies / getCompany.
  3. Not there yet? Confirm with the user, then createPerson (names, emails, phones, jobTitle, companies, groups).
  4. Log what happened: createInteraction with entity { "id": "per_..." }, dateTime (ISO-8601), title, content and activityType (call, meeting, message, coffee, lunch...).
  5. Add context with createNote (entity, visibility public or private, content in markdown).
  6. Set the follow-up: createTask with entity, title and dueAt (date), optionally assignedUsers. Close it later with markTaskAsDone.
  7. Move the deal: listGroups -> listDeals (groupId, objectType) -> getDeal -> updateDeal with new customFieldValues (e.g. the status field) or linked people / companies. Create one with createDeal.

Good to know

  • Confirm with the user before any create or update; they change shared CRM data.
  • Ids are 40 characters with a prefix: per_ person, com_ company, grp_ group, obj_ deal.
  • Custom fields: on people and companies they are keyed by group id then field name ({ "grp_...": { "Status": "Won" } }); on deals directly by field name ({ "Status": "Won" }).
  • Filters: filter[<field>][<op>]=value with ops such as eq, like, in, empty, gt; combine with combinator=and|or.
  • Lists return up to 100 items per page (limit); to continue, take the cursor value from the response's pagination.nextLink.
  • listInteractions (beta) needs entity.id and timeframe past or upcoming.
  • Rate limits: 600 requests/minute and 20 per 2 seconds per user; on 429 wait for Retry-After.
  • Source: folk API reference (https://developer.folk.app/api-reference/overview), checked 2026-10-16.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “folk CRM People, Companies & Deals” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • Pipedrive Deals & Pipeline — For sales teams on Pipedrive: find a deal or contact in seconds, see which pipeline stage it sits in, move it forward o…
  • Attio CRM — Lets an agent find, read, create and update Attio records (people, companies, deals and custom objects), work with list…
  • HubSpot CRM Companies — Find, read, create and update companies in HubSpot CRM: search by domain, name, industry or any property, read companie…
  • HubSpot CRM Deals — Track the sales pipeline in HubSpot CRM: search deals by stage, owner, amount or close date, read deals with their asso…
  • HubSpot CRM Contacts — Find, read, create and update contacts in HubSpot CRM: search by email, name or any property, read contacts with their …