Skip to main content

​
API updates, fixes and improvements

​

​
Bulk create and update on the MCP

The MCP now creates and updates people, companies and objects in bulk, so an agent acts on many records in one tool call instead of one call per record. Each record takes the same fields as the matching single-record tool, and is processed on its own: one that fails, for instance because a text value holds a NUL character or an unpaired surrogate such as \ud800, does not prevent the others from being written, and its error names the field at fault.As on the REST batch endpoints, a call accepts at most 100 records: a larger call is rejected as a whole, asking to split the records into several calls. Unlike them, results are minimal: one result per record, in request order, with only its id, status and error. Use the matching get tool for a full record.In folk_create_companies, a record naming an existing company returns that company, as folk_create_company does: its fields are kept, but the record’s groups and custom field values are added to it. Unlike POST /v1/companies/batch/create, the result does not say whether the company was created or already existed.In folk_update_people and folk_update_companies, several records may update the same person or company: they apply in order, and every add* and remove* operation is kept.Records cannot be deleted through the MCP, one by one or in bulk.
​

​
Bulk update companies and objects

POST /v1/companies/batch/update and POST /v1/groups/{groupId}/{objectType}/batch/update update up to 100 existing companies, or deals and objects of any other type in one group, in one request. Each record is identified by its id and takes the same fields as single update. Each record is updated on its own: one that fails, for instance because its id matches nothing you can access, does not prevent the others from being updated. The response gives one result per record, in request order, with the full updated record.groups replaces the groups of the company, and is destructive, as single update already does: each result lists the groups it removed in removedGroups. On objects, people and companies replace the linked people and companies.A company name stays unique: a record renaming a company to the name of another company fails, as on single update, and so do all the records renaming different companies to the same new name. The records of one company, by its id or a merged id, or of one object, are merged into one update in request order, validated as a whole.On an object type that does not exist in the group, batch update fails the whole request with a 404 listing the object types of the group, as batch create and delete do.Single update now runs through the same path, which changes two things:
  • A company name, description or industry holding a NUL character, and a deal name over 500 characters or holding a NUL character, fail with a 422 naming the value instead of a 500. So does any text value holding an unpaired surrogate such as \ud800.
  • PATCH /v1/groups/{groupId}/{objectType}/{objectId} on an object of another type in the group now answers 404, as GET and DELETE do, instead of updating it.
  • Changing the emails of a company now fires the company.updated webhook, as changing its addresses, urls or phones already did.
  • Update companies in batch
  • Update deals in batch
  • Update objects in batch
​

​
Bulk create objects

POST /v1/groups/{groupId}/{objectType}/batch/create creates up to 100 deals, or objects of any other type, in one group in one request, with the same fields as single create. Each record is created on its own: one that fails, for instance because of an unknown custom field, does not prevent the others from being created. Every result carries the full object.Objects are never matched with existing ones, so a retried batch creates every object again: send an Idempotency-Key header to make retries safe. People and companies are given by ID and must already be in the group.An object type that does not exist in the group now fails the whole request with a 404 on batch create and batch delete, an empty batch included, instead of failing every record as not found. On every object endpoint, the message of that 404 lists the object types of the group, and differs from the 404 of an unknown object ID.An object is now created together with its people and companies, on single create too: if linking them fails, the request fails and creates nothing, where it used to create the object with a warning.A text value that is not valid Unicode, because it holds an unpaired surrogate such as \ud800, now fails only its own record with a 422 naming each such value, on single and batch create of people, companies and objects. It used to fail every record of the batch.
​

​
Bulk create companies

POST /v1/companies/batch/create creates up to 100 companies in one request, with the same fields as single create. As with POST /v1/companies, a record whose name matches an existing company updates that company instead of creating a new one, and records of one request sharing a name end up as one company. Every result says which happened, with operation set to created or updated, and carries the full company. Each record is processed on its own: one that fails, for instance because it names a group you cannot access, does not prevent the others from being created.
​

​
Bulk update people

POST /v1/people/batch/update updates up to 100 existing people in one request, each identified by its id and taking the same fields as single update, native fields and custom field values alike. Each record is updated on its own: one that fails, for instance because its id matches no person you can access, does not prevent the others from being updated. The response gives one result per record, in request order, with the full updated person.groups replaces the groups of the person, and is destructive. A group you can access that is missing from groups is removed from the person, together with its custom field values in that group, as single update already does. Bulk create treats the same groups as additive, so the same payload adds groups on create and removes them on update. Each result lists the groups it removed in removedGroups.The records of one person, by its id or a merged id, are merged into one update in request order: the last value given for a field wins, and customFieldValues are merged group by group. The merged update is validated as a whole: if it is invalid, every record of that person fails with that error. Each record gets the final person.
​

​
Bulk create people

POST /v1/people/batch/create creates up to 100 people in one request, with the same fields as single create. Each record is created on its own: one that fails, for instance because it names a group you cannot access, does not prevent the others from being created. The response gives one result per record, in request order, with the full created person. A record that succeeds with something left out, such as a group it could not be added to, carries its own warnings.Batch results can now carry warnings, described in batch requests.
​

​
Bulk delete companies and objects

POST /v1/companies/batch/delete and POST /v1/groups/{groupId}/{objectType}/batch/delete delete up to 100 companies, or up to 100 objects of one type in one group, in one request. They share the batch requests format of bulk delete people: each record is deleted on its own, and the response gives one result per record, in request order.DELETE /v1/groups/{groupId}/{objectType}/{objectId} now only deletes an object of the type given in the path: an object of another type in the same group returns 404, as it already did for get and update.
​

​
Bulk delete people

POST /v1/people/batch/delete deletes up to 100 people in one request. Each record is deleted on its own: one that is not found or not permitted does not prevent the others from being deleted. The response gives one result per record, in request order.This is the first batch endpoint. Bulk create, update and delete for the other record types will share its request and response format, described in batch requests.
​

​
Burst rate limit visibility

On top of the 600 requests per minute limit, the API applies a burst limit of 20 requests per 2 seconds. Both limits are now documented, and every response describes them with the standard IETF RateLimit-Policy and RateLimit headers. The X-RateLimit-*-Burst headers are documented alongside the existing X-RateLimit-* headers.A 429 response now reports the limit that was actually exceeded: details gains policy, windowSeconds and a policies list, and limit, remaining and retryAfter describe the exceeded policy. Previously they always described the per-minute limit, even when the burst limit was hit.
​

​
List interactions

One endpoint now lists past and upcoming interactions. Pass timeframe=past or timeframe=upcoming, keep only some imported types with importedTypes (email, calendar, whatsapp, call), and keep only some workspace members with user.id. Repeat importedTypes or user.id to pass several values. Without importedTypes, every imported type is returned, calls included. Logged interactions are always returned.The MCP tool folk_list_interactions takes the same filters and replaces folk_list_past_interactions and folk_list_upcoming_interactions, which are removed.
  • List interactions (MCP): an empty importedTypes (importedTypes= on the REST API, [] on the MCP) returns logged interactions only.
  • List past interactions and List upcoming interactions are deprecated, now return Deprecation/Sunset headers and will be removed on March 29, 2027.
  • Interaction participants (from, to and call transcript speakers) now always carry a resolved name, omitted only for a deleted member or a missing person on logged interactions, plus picture and, when they match a workspace member, userId (usr_…).
​

​
Call status

Call interactions now carry a content.status: ongoing, processing, completed, missed or failed. Calls appear as soon as they are dialled, so use the status to tell a finished call from one that is still ringing, being summarized, or never connected.
​

​
Call interactions

Phone calls recorded from the folk mobile app now appear as call interactions on the REST API and the MCP, next to emails, calendar events and WhatsApp messages. A call carries its duration in seconds and, when the recording was processed, its summary. Getting a single call returns its diarized transcript, one segment per speaker, when the workspace’s interaction privacy rules allow it.A new interaction type is an additive change: make sure your integration handles interactions whose interactionType it does not know.
​

​
Custom objects documentation

Groups can contain any object type you define, not just deals. The object endpoints are now documented type-agnostically under Custom objects, alongside the existing Deals pages — same endpoints, same behavior, no API change.
​

​
Interactions API in open beta

The interactions endpoints are now available in open beta for all API keys — no special access required. You can list past and upcoming interactions, and get, update, or delete logged interactions.These endpoints may continue to evolve based on feedback while in open beta.
​

​
Tasks API released, Reminders deprecated

Tasks are now generally available on the REST API and MCP. Reminders are deprecated in favor of Tasks — see the migration guide.
​

​
folk API improvements and additions

​
folk MCP tools update

We’ve added a new set of tools for managing your contacts and workspace, including:
​

​
Add gender support to people entity

  • Allowing to filter and edit gender from the api
​

​
Folk remote MCP server in open beta

The folk remote MCP server is now available in open beta. You can connect and test it today — it exposes all the operations already available in the REST API, so you can manage your workspace from AI assistants with the same capabilities as the API.
​

​
Fix clearing birthday field

  • Clearing the ‘birthday’ field of a person is now possible by passing null or an empty string.
​

​
Notes search and date filters

  • Add query parameter to List notes to search notes by full-text content.
  • Add createdAfter and createdBefore parameters to List notes to filter notes by creation date.
​

​
Interactions endpoints

Add support for listing, retrieving, updating, and deleting interactions in the API. Past and upcoming interactions can be listed for a person, company, or object, and logged interactions can be updated or deleted.
​

​
magicField custom field type deprecated

  • The magicField custom field type has been deprecated and existing fields have been migrated to textField with AI settings.
​

​
Add new all filter to people, companies and deals

  • Add all filter on multi reference fields to get entities matching all listed references.
​

​
Add new fields to companies

  • Add fundingRaised, lastFundingDate, industry, foundationYear and employeeRange, with filtering capabilities.
​

​
Webhooks endpoints

Add support for webhooks in the API, allowing you to retrieve, create, update, and delete webhooks within your workspace.
​

​
Notes endpoint

  • Add support for notes created by assistants
  • Fix issue with notes created by users that are no longer part of the workspace
​

​
Add createdAt and createdBy fields to people, companies, deals, notes and reminders

  • Add createdAt and createdBy fields to people, companies and deals, with filtering capabilities.
  • Add createdAt field to notes.
  • Add createdAt and createdBy fields to reminders.
​

​
Interaction endpoint

Add endpoint to create interactions on people and companies.
​

​
Notes endpoints

Add support for notes in the API, allowing you to retrieve, create, update, and delete notes within your workspace.
​

​
Reminders endpoints

Add support for reminders in the API, allowing you to retrieve, create, update, and delete reminders within your workspace.
​

​
Deal management endpoints

Add support for deals in the API, allowing you to create, update, retrieve, and delete deals within your workspace.
​

​
Deal field support in contact custom fields

Add support for deals in contact custom field values. You can now retrieve, updated deals, and filter contacts by the deal custom fields.
​

​
Delete people and companies

Introduced new endpoints that allow you to delete people and companies from your workspace.
​

​
Listing and filtering of people and companies

Introduced new endpoints that allow you to list all people and companies in your workspace, with filtering capabilities.
​

​
Added companies endpoints

Introduced the following company endpoints:
​

​
Initial release of the API.

The public API is available at https://api.folk.app with the following endpoints: