folk CRM

Log a past interaction (a recorded touchpoint such as a call, meeting, or message) with a person or company. Use for: - recording that a conversation or meeting happened (e.g. "Had a coffee with John Doe") Only manually logged interactions can be created here. Imported interactions (email, calendar, WhatsApp, calls) sync automatically from connected sources and cannot be created with this tool. Required: - entity.id — the person (`per_<uuid>`) or company (`com_<uuid>`) the interaction is linked to - dateTime — when the interaction happened, as an ISO 8601 timestamp (e.g. "2025-07-17T09:00:00.000Z") - title — short summary of the interaction - content — the multi-line body of the interaction - activityType — the kind of interaction: a predefined activity (call, meeting, message, coffee, lunch, event, drink), a messaging app (slack, whatsapp, linkedin, telegram, etc.), or a single emoji Returns the full created logged interaction.

folk_create_interaction

Deprecated: use folk_create_objects. Removed on 2027-04-16. Create a new object (e.g. deal) within a specific group and object type in the folk workspace. Deals, opportunities, projects, partnerships, job applications… are all custom objects: records of an object type defined in a group. When the user talks about "deals" (or "opportunities", "partnerships"…), they mean the objects of the matching object type in a group. The object type name is chosen by each workspace and is case-sensitive: it can be "Deals", "deals", "Opportunities" or anything else. Never assume "Deals": use the exact name found in the group. An object type that does not exist in the group fails the call, and the error lists the object types of the group. Use folk_get_workspace_structure first to discover available groupIds and object types. If the object type does not exist yet, create it first with folk_create_group_custom_field (type `objectField`). Provide name, and optionally link people and companies by their folk IDs. People and companies must already be in the group of the object: an unknown id, or one not in the group, is silently ignored. Check the people and companies of the object afterwards to know which ones were linked. customFieldValues is a flat record keyed by field name (e.g. `{ "Status": "Active" }`) — no group nesting needed. A name that is not a custom field of the object type fails the call. Returns the full created object.

folk_create_object

Create several new companies in the folk workspace in one call, each record with at least a name. Multi-value fields (emails, phones, addresses, urls) accept plain arrays — the first element becomes the primary value. customFieldValues are keyed by group id then field name — every group id used there must also be present in the record's groups. A record naming an existing company, or a company named by an earlier record of the call, returns that company's id: its fields are kept, but the record's groups and custom field values are added to it. Accepts at most 100 records per call: split a larger set into several calls, or narrow it down first. Each record is processed on its own: one that fails does not prevent the others from being written. Returns one result per record, in the order of records, with only its id, status and error: call the matching get tool for a full record. Records cannot be deleted through the folk MCP.

folk_create_companies

Create several new objects (e.g. deals) of one object type within one group in one call: groupId and objectType are given once for the call. Deals, opportunities, projects, partnerships, job applications… are all custom objects: records of an object type defined in a group. When the user talks about "deals" (or "opportunities", "partnerships"…), they mean the objects of the matching object type in a group. The object type name is chosen by each workspace and is case-sensitive: it can be "Deals", "deals", "Opportunities" or anything else. Never assume "Deals": use the exact name found in the group. An object type that does not exist in the group fails the call, and the error lists the object types of the group. Each record takes a name, and optionally people and companies linked by their folk IDs. People and companies must already be in the group of the object: an unknown id, or one not in the group, is silently ignored. Check the people and companies of the object afterwards to know which ones were linked. customFieldValues is a flat record keyed by field name (e.g. `{ "Status": "Active" }`) — no group nesting needed. Use folk_get_workspace_structure first to discover available groupIds and object types. An object type that does not exist in the group fails the whole call: create it first with folk_create_group_custom_field (type `objectField`). Accepts at most 100 records per call: split a larger set into several calls, or narrow it down first. Each record is processed on its own: one that fails does not prevent the others from being written. Returns one result per record, in the order of records, with only its id, status and error: call the matching get tool for a full record. Records cannot be deleted through the folk MCP.

folk_create_objects

Create several new people in the folk workspace in one call. Each record needs at least a name (fullName, or firstName/lastName) or at least one email. For every multi-value field (emails, phones, addresses, urls), the first element is treated as the primary value. companies links the person to companies, each given as { id } or { name } (a company named that is created if it does not exist); the first one is the primary company. groups adds the person to groups, each given as { id }. customFieldValues are keyed by group id, then by field name. Accepts at most 100 records per call: split a larger set into several calls, or narrow it down first. Each record is processed on its own: one that fails does not prevent the others from being written. Returns one result per record, in the order of records, with only its id, status and error: call the matching get tool for a full record. Records cannot be deleted through the folk MCP.

folk_create_people

Delete a campaign that is a draft or in review, with its messages. Other campaigns cannot be deleted. Confirm with the user first: this cannot be undone.

folk_delete_campaign

Start an enrichment of the emails and/or phones of up to 500 people, using third-party data providers. The data found is added to the people in folk. Enriching people is an asynchronous job: this tool returns right away with the enrichment and its id, usually "pending" (already "completed" when every id is skipped). Then: 1. Poll folk_get_person_enrichment with the enrichment id until its status is "completed" or "failed". An enrichment usually takes from a few seconds to a few minutes, depending on the number of people. 2. Do not request another enrichment of the same people while this one is running. 3. Once "completed", the enrichment holds a report for every person of the batch you can access: status, enrichedFields and missingInputs (see folk_get_person_enrichment). Before retrying people that were not (fully) enriched: a person's missingInputs lists the data the providers search with that the person was missing. As long as it is not fixed, a new enrichment would most likely give the same result and use credits for nothing. Add the missing data to the person first, then enrich only those people again: - "name", "linkedinUrl" (add a LinkedIn URL to urls) and "company" (link a company with companyIds): folk_update_people. - "companyWebsite" (a website on the person's primary company): folk_update_companies (urls). Credits: person_enrichment credits are charged per person and per field found: searching the emails of a person costs 1 credit, searching their phones costs 4 credits. The check needs the full cost upfront (every requested field for every person that can be enriched): if the workspace doesn't have enough credits, nothing is enriched and an "insufficient credits" error states the credits needed and left. Credits are reserved when the job starts and the fields not found are refunded when it finishes, so "used" in folk_get_credits looks higher while a job runs. Call folk_get_credits before a large enrichment. Large batches: only enrich the people missing the requested field, instead of a whole group for instance. Collect their IDs with folk_search_people, idsOnly: true and an "empty" filter on the field, e.g. to enrich the emails of a group: `{ "filter": { "groups": { "in": { "id": ["grp_<uuid>"] } }, "emails": { "empty": "" } }, "idsOnly": true, "limit": 500 }`. Collect every page first (follow nextCursor until there is none), then start one enrichment per page of up to 500 ids. ids: person ids (`per_<uuid>`), from folk_search_people (with idsOnly: true). Duplicates are enriched once. Ids that don't match a person you can access and edit (enriching needs the contributor role or above on one of the person's groups) are not rejected: they are reported with the "skipped" status. Returns the enrichment, usually with status "pending".

folk_enrich_people

Fetch a single campaign by its id, with its steps by position: sender, subject, body, cc, bcc, delay and whether it is sent in the same thread. Each step has its own sender; a sender deleted since has id null and keeps the address the step was set up with. Subjects are plain text and bodies are HTML, with variables written `{{key}}` (for example `{{firstName}}`, or `{{customFieldValues.grp_<uuid>.<field name>}}` for a group custom field). A signed body ends with `<p>{{signature}}</p>`, which stands for the sender's signature; an unsubscribe link is `<a href="{{unsubscribeLink}}">`. To see what each recipient receives, use folk_list_campaign_messages.

folk_get_campaign

Fetch a single company by companyId. Use when you already have a companyId from a previous search_companies call or from another tool response. Do not use to find or look up a company by name, domain, or other attribute — use search_companies instead. Returns the full company object: native fields (name, description, industry, foundationYear, fundingRaised, lastFundingDate, employeeRange), group memberships, and custom field values per group.

folk_get_company

Fetch a single group custom field by group, entity type, and custom field name. Returns the detailed custom field definition (name, type, options, config) for that entity type. Use folk_list_group_custom_fields if the custom field name isn't already known.

folk_get_group_custom_field

Fetch a single person by their folk person id and return the full person payload (names, emails, phones, addresses, urls, companies, groups, custom field values, interaction metadata). Use this only when you already have the person id (e.g. from folk_search_people or a previous folk_create_people). Do not use it to look up a person by name or email — that is what folk_search_people is for.

folk_get_person

Fetch a single task by its ID. Use when you already have a taskId from a previous folk_search_tasks or folk_create_task call. Do not use to find or look up a task by title, due date, or other attribute — use folk_search_tasks instead. Returns the full task object: title, description, entity, dueAt, dueTime, completedAt, recurrenceFrequency, isPublic, assignedUsers, and createdBy.

folk_get_task

Returns a view of a group the user can access, with its settings. A view shows the entities of a group with its own settings: `filter`, `visibleFields`, and `sort` for table views or `groupBy` and `columns` for kanban views. - `groupId`: the group of the view, `null` for a personal view, which belongs to no group. It never changes. - `entityType`: `person`, `company` or the name of an object type, as in folk_get_workspace_structure. It never changes. - `type`: `table` or `kanban`. It never changes. - `position`: `{ after: <viewId> | null }`, the view just before this one in its group, `null` for the first one.

folk_get_view

Get an enrichment of people by its id, from folk_enrich_people or folk_list_person_enrichments. Use it to follow an enrichment: enriching people is asynchronous, so poll this tool until status is "completed" or "failed". Wait a few seconds between calls. - "pending": not started yet. "in_progress": running. Keep polling. - "failed": the enrichment couldn't run, see errorReason. "insufficient_credits": nothing was enriched. "internal_error": some people may already have been enriched, so check them (e.g. with folk_search_people) before enriching again. - "completed": over. summary counts the people per result, and items holds a report for every person of the batch you can access. Each item of a completed enrichment: - status: "enriched" (every requested field found), "partially_enriched" (some found), "not_enriched" (searched, nothing found), "skipped" (the id doesn't match a person you can access and edit, not searched), "error" (the providers were unavailable, can be retried later). - enrichedFields: the requested fields found during this enrichment. - missingInputs: the data the providers search with that the person was missing: "name" (a first or last name), "company" (a company linked to the person), "companyWebsite" (a website on the person's primary company), "linkedinUrl" (a LinkedIn profile URL in the person's URLs). Adding it may improve a new enrichment, with no guarantee. Don't enrich a "not_enriched" or "partially_enriched" person again until its missingInputs are fixed: the result would most likely be the same and use credits for nothing. New values may be added in the future: handle unknown values gracefully.

folk_get_person_enrichment

Fetch a single interaction by its id, including the full email or calendar body, or the call transcript, when interaction privacy rules allow it. Use this when you already have an interactionId (e.g. from folk_list_interactions) and need its full details. To find an interaction in the first place, use folk_list_interactions instead. Both interactionId and entityId are required, and the entityId must match the entity the interaction is linked to.

folk_get_interaction

Fetch a single object (e.g. deal) by its ID within a specific group and object type. Deals, opportunities, projects, partnerships, job applications… are all custom objects: records of an object type defined in a group. When the user talks about "deals" (or "opportunities", "partnerships"…), they mean the objects of the matching object type in a group. The object type name is chosen by each workspace and is case-sensitive: it can be "Deals", "deals", "Opportunities" or anything else. Never assume "Deals": use the exact name found in the group. An object type that does not exist in the group fails the call, and the error lists the object types of the group. Use when you already have an objectId from a previous folk_search_objects or folk_create_objects call. Returns the full object: name, people, companies, createdAt, createdBy, customFieldValues.

folk_get_object

Get the credits used and available for each metered feature of the workspace in the current period. Credits reset at the end of the period (periodEnd). Use before a large enrichment with folk_enrich_people: person_enrichment credits are charged per person and per field found. If the workspace doesn't have enough credits, folk_enrich_people returns an insufficient credits error stating the credits needed and left. For each feature: - scope: "workspace" when the whole workspace shares the credits, "user" when each member has their own. - used: the credits consumed in the current period. Can exceed limit if the limit was lowered during the period. - limit: the credits available per period. null means unlimited, 0 means the feature is not available. New features and values may be added in the future: handle unknown values gracefully.

folk_get_credits

Returns the identity of the authenticated folk user for this MCP session: their id, email, and fullName. Call once per session when you need to attribute an action to the current user (e.g. assigning a task, filtering by owner). Do not call to look up other workspace members — use the members array from folk_get_workspace_structure instead. Does not return role, permissions, or plan information.

folk_get_current_user

Retrieves the complete structure of the folk workspace: groups, entity types per group, native fields (person/company/object filter keys), custom field definitions (names, types, allowed values), pipeline views, and workspace members. Call at the start of every fresh session before reading or writing any workspace data — the schema may have changed since the last session (new groups, renamed fields, updated pipeline stages). Do not call again within the same session unless the user explicitly changes the workspace structure. Does not return contact data, notes, or interaction history. Native fields (personNativeFields, companyNativeFields, objectNativeFields) are the keys accepted in the filter of folk_search_people, folk_search_companies and folk_search_objects. personNativeFields includes the `company.<key>` fields, which filter people on their primary company. Custom field keys are built from customFieldsByEntityType: `customFieldValues.<groupId>.<fieldName>` for people and companies, `company.customFieldValues.<groupId>.<fieldName>` for the custom fields of a person's primary company, `customFieldValues.<fieldName>` for objects. Object types (custom objects): Deals, opportunities, projects, partnerships, job applications… are all custom objects: records of an object type defined in a group. When the user talks about "deals" (or "opportunities", "partnerships"…), they mean the objects of the matching object type in a group. The object type name is chosen by each workspace and is case-sensitive: it can be "Deals", "deals", "Opportunities" or anything else. Never assume "Deals": use the exact name found in the group. An object type that does not exist in the group fails the call, and the error lists the object types of the group. The object types of a group are its `objectField` custom fields, listed under `person` and `company` in customFieldsByEntityType: the name of the field is the object type to pass as objectType. Each object type of a group also appears under its own name in entityTypes and customFieldsByEntityType (with the custom fields of its objects), and in the entityType of its pipelines. Use that name as objectType in the object tools, and as entityType in the custom field tools. An object type named `person` or `company` is not listed under its own name, as these names always mean the native entity types here.

folk_get_workspace_structure

Send a campaign in review now, or schedule it at scheduledAt (an ISO date and time with a timezone offset or `Z`, at least a minute ahead). This sends emails that cannot be unsent. Before launching, show the user the campaign (its recipients, steps and when it sends) and get their explicit approval in the chat. Never launch on your own initiative. The campaign becomes `sending`, or `scheduled` until scheduledAt; its steps read `scheduled` until they send. Track delivery with folk_get_campaign and folk_list_campaign_messages. The launch runs the app's checks: the messages left on the plan, the daily quota of a Gmail sender, and every step's sender, which the user must be allowed to send from. A failed check leaves the campaign in review, with the reason in the error. Once launched, a campaign flagged as spam goes back to `in_review` with error "spam_detected". Only a campaign `in_review` can be launched: create one with folk_create_campaign (target "review") or folk_review_campaign. To change a scheduled campaign before it sends, cancel its schedule with folk_cancel_campaign_schedule; to stop a scheduled or sending campaign for good, use folk_stop_campaign.

folk_launch_campaign

List the email campaigns the user can access, newest first. A campaign is one or more emails (steps), sent to people or companies. Each recipient gets one message per step, with the step's variables filled in. Use for: - finding a campaign's id to pass to folk_get_campaign or folk_list_campaign_messages - checking the status of recent campaigns (draft, processing, in_review, scheduled, sending, finished, cancelled, failed) Pass groupId to keep only the campaigns of one group. Campaigns created from a selection of contacts have groupId null. Subjects are plain text and bodies are HTML, with variables written `{{key}}` (for example `{{firstName}}`, or `{{customFieldValues.grp_<uuid>.<field name>}}` for a group custom field). A signed body ends with `<p>{{signature}}</p>`, which stands for the sender's signature; an unsubscribe link is `<a href="{{unsubscribeLink}}">`. The response includes nextCursor when more results are available; pass it back as cursor to fetch the next page.

folk_list_campaigns

List the enrichments of people of the workspace, most recent first, paginated via cursor. Use to find an enrichment without its id, e.g. the enrichments still running before requesting a new one. Use folk_get_person_enrichment if the enrichment id is already known. Filter shape: `{ "<attribute>": { "<operator>": <operand> } }` | Attribute | Operators | Values | |------------|--------------------------|----------------------------------------------------------------| | status | eq, not_eq, in, not_in | one or more of: pending, in_progress, completed, failed | | createdAt | gt, lt | one date string "YYYY-MM-DD" | | finishedAt | empty, not_empty, gt, lt | empty/not_empty take no value; gt/lt take one date "YYYY-MM-DD" | Examples: - running enrichments: `{ "status": { "in": ["pending", "in_progress"] } }` - finished enrichments: `{ "finishedAt": { "not_empty": "" } }` - requested after a date: `{ "createdAt": { "gt": "2026-09-01" } }` Use combinator to control AND/OR logic across filters. Omit filter to list every enrichment. Returns up to `limit` enrichments (default and max 10), each with its report once completed (see folk_get_person_enrichment). The response includes nextCursor when more results are available; pass it back as cursor to get the next page.

folk_list_person_enrichments

Returns the list of the group's custom fields for an entity type. The object types of a group are its `objectField` custom fields on `person` (or `company`, which returns the same ones): find them with folk_get_workspace_structure or folk_list_group_custom_fields. The name of the field is the object type to pass as objectType. To create an object type, call folk_create_group_custom_field with type `objectField`. To list the custom fields of the objects of an object type, pass the name of the object type as entityType.

folk_list_group_custom_fields

List the members of a group, paginated. For a public group, this returns every workspace member as they are all members of the group — role defaults to admin unless the member has an explicit role in the group.

folk_list_group_members

List the groups in the folk workspace that the caller can access. Use for: - listing the workspace's groups (no filters needed) - retrieving group ids to use with other endpoints, such as listing a group's custom fields. Parameters: - limit / cursor: pagination. Returns paginated group objects (id, name, visibility, createdBy, emoji) with nextCursor when more pages exist. emoji is a native emoji, or null when the group has none. Group ids are formatted `grp_<uuid>`.

folk_list_groups

List past or upcoming interactions for a single person, company, or object. Use for: - reviewing the recent communication history with a contact (timeframe "past") - checking what meetings or events are scheduled with a contact (timeframe "upcoming") - finding an interaction's id to pass to folk_get_interaction or folk_update_interaction Provide entityId to scope results (this tool always targets one entity — it cannot search across the whole workspace). Returns both imported interactions (email, calendar, WhatsApp, calls) and manually logged ones. Pass importedTypes to keep only some imported types, and userIds to keep only the interactions of some workspace members. Some content may be hidden depending on the workspace's interaction privacy rules. The response includes nextCursor when more results are available; pass it back as cursor to fetch the next page.

folk_list_interactions

List the email addresses the user can send campaigns from, last used first. Senders still waiting for verification are left out. Use for: - choosing which sender a campaign or a step sends from - checking whether a sender can send follow-up steps (supportsSequences) or an unsubscribe link (provider "custom_domain") signature is the sender's signature as HTML, or null when they have none. It is what `{{signature}}` inserts on a new step or message: end a body with `<p>{{signature}}</p>` to sign it, rather than writing the signature yourself. The response includes nextCursor when more results are available; pass it back as cursor to fetch the next page.

folk_list_message_senders

List the messages of a campaign: one per recipient and per step, ordered by step, with their final subject and body. Use for: - reviewing what each recipient receives - finding which messages were not sent, and why (status "not_sent" and notSentReason) Filter with step (1-based position), recipientId (a person or company id) and status (draft, sent, not_sent). Known notSentReason values: no_recipient, recipient_not_found, recipient_deleted, recipient_no_email, recipient_invalid_email, too_many_copies, invalid_sender, stopped, stopped_after_reply, previous_messages_not_sent, dropped_unsubscribed_address, dropped_bounced_address, dropped_spam_reporting_address, dropped_spam_content, dropped_invalid, bounce_invalid_address, bounce_technical, bounce_content, bounce_reputation, bounce_frequency_or_volume_too_high, bounce_mailbox_unavailable, bounce_unclassified, send_failed. Treat unknown ones as send_failed. A message to a contact deleted since has recipient.contact null. A message's sender is the address sending used once it was attempted, and its step's sender before that. The response includes nextCursor when more results are available; pass it back as cursor to fetch the next page.

folk_list_campaign_messages

List the `{{variables}}` the subjects and bodies of a campaign can use: the fields of its people or companies, the text and numeric custom fields of its group, `{{unsubscribeLink}}` and `{{signature}}`. Write each variable's token exactly as given: custom field names are escaped where needed. A variable without a value for a recipient is removed from their message. `{{unsubscribeLink}}` is only valid as the whole href of a link in a body, `<a href="{{unsubscribeLink}}">`, with a custom_domain sender. `{{signature}}` is only valid alone in the last paragraph of a body, `<p>{{signature}}</p>`. It inserts the sender's signature on a new step or message (see folk_list_message_senders): end a body with it to sign it, rather than writing the signature yourself. The response includes nextCursor when more results are available; pass it back as cursor to fetch the next page.

folk_list_campaign_variables

Returns the views of the groups the user can access, in the order of the app's sidebar: by group, then by position in the group. Pass groupId to list the views of a single group. Paginated: pass the nextCursor of a page as cursor to get the next one. A view shows the entities of a group with its own settings: `filter`, `visibleFields`, and `sort` for table views or `groupBy` and `columns` for kanban views. - `groupId`: the group of the view, `null` for a personal view, which belongs to no group. It never changes. - `entityType`: `person`, `company` or the name of an object type, as in folk_get_workspace_structure. It never changes. - `type`: `table` or `kanban`. It never changes. - `position`: `{ after: <viewId> | null }`, the view just before this one in its group, `null` for the first one.

folk_list_views

Mark a task as done or todo. Pass a completedAt datetime to mark as done, or null to mark as todo. Returns the taskId. Call folk_get_task to retrieve the full updated task.

folk_update_task_todo_or_done

Remove a member from a group. Fails on a public group, when the target is not a member, or when the target is the group owner.

folk_remove_group_member

Remove a person or company from a draft or in_review campaign, with their messages. The campaign returned has its recipientCount updated. A contact that is not a recipient is not found. A campaign still processing its messages cannot change yet: retry in a few seconds. A scheduled or sending campaign cannot lose recipients: stop them with folk_stop_campaign instead.

folk_remove_campaign_recipient

Generate the messages of a draft campaign, one per recipient and per step, so they can be read and edited before launch, as the app does when a campaign goes to review. The campaign is `processing` for a few seconds, then `in_review`: check with folk_get_campaign before reading its messages with folk_list_campaign_messages. If generation fails, it is `in_review` with an `error`. Edit single messages with folk_update_campaign_message, remove recipients with folk_remove_campaign_recipient, or take it back to draft with folk_draft_campaign to edit its steps. Launch it with folk_launch_campaign once the user approves. Every step needs a sender, a subject (apart from follow-ups sent in the same thread) and a body. To review a campaign as you create it, pass target "review" to folk_create_campaign instead.

folk_review_campaign

Search companies in the folk workspace using one or more filters. Use for: - finding a specific company (e.g. "Acme Corp") - filtering companies by native fields, groups, creators, or custom fields Do not call with an empty filter. Filter shape: `{ "<fieldName>": { "<operator>": <operand> } }` Field categories: - Text fields (name, description, industry, emails, phones, urls, addresses, custom fields): operators: eq, not_eq, like, not_like, empty, not_empty - Numeric/date fields (fundingRaised, lastFundingDate, createdAt, custom fields): operators: eq, not_eq, gt, lt, empty, not_empty - Single and multi select fields (custom fields): operators: in, not_in, empty, not_empty - Multi-value reference fields (groups): operators: in, not_in, all, empty, not_empty - Single-value reference fields (createdBy): operators: in, not_in, empty, not_empty Important operand rules: - eq / like / gt / lt → operand is usually a plain string Example: `{ "name": { "eq": "John Doe" } }` - empty / not_empty → operand MUST be an empty string Example: `{ "industry": { "empty": "" } }` - in / not_in / all → operand MUST be an object with a single attribute being a single string or an array of string Example: `{ "createdBy": { "in": { "id": "usr_123" } } } OR { "groups": { "in": { "id": ["grp_123"] } } }` - SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object) Examples: `{ "customFieldValues.grp_xxx.Status": { "in": "Active" } }` `{ "customFieldValues.grp_xxx.Tags": { "in": ["B2C","B2B"] } }` - Relationships / Assign / Deals custom fields → operand MUST be an object with a single id being a single string or an array of string Examples: `{ "customFieldValues.grp_xxx.Relationships": { "in": { "id": "per_aaa" } } }` `{ "customFieldValues.grp_xxx.Owner": { "in": { "id": "usr_aaa" } } }` `{ "customFieldValues.grp_xxx.Deals": { "in": { "id": "obj_aaa" } } }` - Date fields → operand is a YYYY-MM-DD date or a relative date: "today", "yesterday", `"<n>-<unit>-ago"`, and on date custom fields only "tomorrow" and `"in-<n>-<unit>"` too (n from 0 to 99, unit: day(s), week(s), month(s), year(s)) Examples: `{ "lastFundingDate": { "gt": "6-months-ago" } }` `{ "customFieldValues.grp_xxx.Renewal": { "lt": "in-1-month" } }` Custom fields: Use key format `customFieldValues.<groupId>.<fieldLabel>` Example: `{ "customFieldValues.grp_xxx.Status": { "in": "Active" } }` Use combinator for AND/OR logic. Returns paginated company objects: up to `limit` companies (default 20, max 100). The response includes nextCursor when more results are available; pass it back as cursor, with the same filter and idsOnly, to get the next page. Acting on many companies: set idsOnly to true to get only the IDs of the matching companies (`com_<uuid>`) in ids, instead of full objects in companies: up to `limit` IDs per page (default 100, max 500). Use it before folk_update_companies, which takes up to 100 records per call (one per companyId; addGroupIds and add* / remove* need no current values). Collect every page before acting on the ids: updating the companies can change which ones match the filter and shift the next pages. Use folk_get_company if companyId is already known.

folk_search_companies

Search notes in the folk workspace. Use for: - listing recent notes across the workspace (no filters needed) - finding notes attached to a specific contact or company - filtering notes by creation date or content Parameters: - entityId (optional): filter by entity. Format `per_<uuid>` for a person, `com_<uuid>` for a company, `obj_<uuid>` for objects. - query (optional): full-text search against note content. - createdAfter (optional): ISO 8601 timestamp — return only notes created after this date. - createdBefore (optional): ISO 8601 timestamp — return only notes created before this date. - limit / cursor: pagination. Returns paginated note objects with nextCursor when more pages exist.

folk_search_notes

Search objects (e.g. deals) of one object type in a group using one or more filters. Deals, opportunities, projects, partnerships, job applications… are all custom objects: records of an object type defined in a group. When the user talks about "deals" (or "opportunities", "partnerships"…), they mean the objects of the matching object type in a group. The object type name is chosen by each workspace and is case-sensitive: it can be "Deals", "deals", "Opportunities" or anything else. Never assume "Deals": use the exact name found in the group. An object type that does not exist in the group fails the call, and the error lists the object types of the group. Use for: - finding a specific object (e.g. "Project Alpha") - filtering objects by name, linked people or companies, creation date, creator, or custom fields Do not call with an empty filter. Use folk_get_workspace_structure first to discover available groupIds and object types. Filter shape: `{ "<fieldName>": { "<operator>": <operand> } }` Field categories: - Text fields (name): operators: eq, not_eq, like, not_like, empty, not_empty - Date fields (createdAt): operators: eq, not_eq, gt, lt, empty, not_empty - Multi-value reference fields (people, companies): operators: in, not_in, all, empty, not_empty - Single-value reference fields (createdBy): operators: in, not_in, empty, not_empty Important operand rules: - eq / like / gt / lt → operand is usually a plain string Example: `{ "name": { "eq": "Project Alpha" } }` - empty / not_empty → operand MUST be an empty string Example: `{ "name": { "empty": "" } }` - in / not_in / all → operand MUST be an object with a single attribute being a single string or an array of string Examples: `{ "createdBy": { "in": { "id": "usr_123" } } }` `{ "companies": { "in": { "id": ["com_123", "com_456"] } } }` - SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object) Examples: `{ "customFieldValues.Status": { "in": "Active" } }` `{ "customFieldValues.Tags": { "in": ["B2C","B2B"] } }` - Assign (user) custom fields → operand MUST be an object with a single id being a single string or an array of string Example: `{ "customFieldValues.Owner": { "in": { "id": "usr_aaa" } } }` - Date fields → operand is a YYYY-MM-DD date or a relative date: "today", "yesterday", `"<n>-<unit>-ago"`, and on date custom fields only "tomorrow" and `"in-<n>-<unit>"` too (n from 0 to 99, unit: day(s), week(s), month(s), year(s)) Examples: `{ "createdAt": { "gt": "7-days-ago" } }` `{ "customFieldValues.Close date": { "lt": "in-1-month" } }` Custom fields: use the key format `customFieldValues.<fieldName>`, without group id: an object belongs to a single group. Example: `{ "customFieldValues.Status": { "in": "Active" } }` Use combinator for AND/OR logic. Returns paginated object payloads with name, people, companies, customFieldValues. Use folk_get_object if objectId is already known.

folk_search_objects

Search people in the folk workspace using one or more filters. Use for: - finding a specific person (e.g. "John Doe") - filtering people by native fields, groups, companies, creators, or custom fields Do not call with an empty filter. Filter shape: `{ "<fieldName>": { "<operator>": <operand> } }` Field categories: - Text fields (fullName, firstName, lastName, jobTitle, description, emails, phones, urls, addresses, custom fields): operators: eq, not_eq, like, not_like, empty, not_empty - Numeric/date fields (birthday, createdAt, addedToGroupAt, interactionMetadata.workspace.lastInteractedAt, interactionMetadata.user.lastInteractedAt, custom fields): operators: eq, not_eq, gt, lt, empty, not_empty - Enum fields (gender): operators: eq, not_eq, empty, not_empty Values: "Male", "Female", "Unknown", "Other" Example: `{ "gender": { "eq": "Female" } }` - SingleSelect/MultiSelect fields (custom fields): operators: in, not_in, empty, not_empty - Multi-value reference fields (groups, companies): operators: in, not_in, all, empty, not_empty - Single-value reference fields (createdBy, addedToGroupBy, strongestConnection): operators: in, not_in, empty, not_empty createdBy, addedToGroupBy and strongestConnection take workspace members: `{ "id": "usr_xxx" }` or `{ "email": "jane@example.com" }` Group-scoped fields (addedToGroupAt, addedToGroupBy, strongestConnection) hold when true in at least one group of the person: - the groups of a `groups` filter with "in" or "all", when the filters are combined with "and" - otherwise (no such groups filter, only "not_in", or combinator "or"), every group you can access Example: `{ "groups": { "in": { "id": "grp_123" } }, "addedToGroupAt": { "gt": "30-days-ago" } }` Important operand rules: - eq / like / gt / lt → operand is usually a plain string Example: `{ "fullName": { "eq": "John Doe" } }` - empty / not_empty → operand MUST be an empty string Example: `{ "jobTitle": { "empty": "" } }` - in / not_in / all → operand MUST be an object with a single attribute being a single string or an array of string Example: `{ "createdBy": { "in": { "id": "usr_123" } } } OR { "groups": { "in": { "id": ["grp_123"] } } }` - SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object) Examples: `{ "customFieldValues.grp_xxx.Status": { "in": "Active" } }` `{ "customFieldValues.grp_xxx.Tags": { "in": ["B2C","B2B"] } }` - Relationships / Assign / Deals custom fields → operand MUST be an object with a single id being a single string or an array of string Examples: `{ "customFieldValues.grp_xxx.Relationships": { "in": { "id": "per_aaa" } } }` `{ "customFieldValues.grp_xxx.Owner": { "in": { "id": "usr_aaa" } } }` `{ "customFieldValues.grp_xxx.Deals": { "in": { "id": "obj_aaa" } } }` - Date fields → operand is a YYYY-MM-DD date or a relative date: "today", "yesterday", `"<n>-<unit>-ago"`, and on date custom fields only "tomorrow" and `"in-<n>-<unit>"` too (n from 0 to 99, unit: day(s), week(s), month(s), year(s)) Examples: `{ "createdAt": { "gt": "7-days-ago" } }` `{ "customFieldValues.grp_xxx.Renewal": { "lt": "in-1-month" } }` Custom fields: Use key format `customFieldValues.<groupId>.<fieldLabel>` Example: `{ "customFieldValues.grp_xxx.Status": { "in": "Active" } }` Company fields: filter people on their primary company with the `company.` prefix. - Native fields: company.emails, company.phones, company.urls, company.industry, company.addresses, company.fundingRaised, company.lastFundingDate, company.foundationYear, company.employeeRange (same operators as on companies) - Custom fields: `company.customFieldValues.<groupId>.<fieldLabel>` Example: `{ "company.industry": { "eq": "Software" } }` Use combinator for AND/OR logic. Returns paginated person objects: up to `limit` people (default 20, max 100). The response includes nextCursor when more results are available; pass it back as cursor, with the same filter and idsOnly, to get the next page. Acting on many people: set idsOnly to true to get only the IDs of the matching people (`per_<uuid>`) in ids, instead of full objects in people: up to `limit` IDs per page (default 100, max 500). Use it before bulk tools: folk_enrich_people takes up to 500 ids per call, folk_update_people up to 100 records per call (one per personId; addGroupIds and addX / removeX need no current values). Collect every page before acting on the ids: updating the people can change which ones match the filter and shift the next pages. Use folk_get_person if personId is already known.

folk_search_people

Search tasks in the folk workspace with optional attribute filters, paginated via cursor. Use for: - listing tasks, optionally filtered by completion state, due date, or attributes - finding tasks assigned to specific users, or linked to specific people, companies, or objects - finding tasks created, due, or completed within a date range Filter shape: `{ "<fieldName>": { "<operator>": <operand> } }` Attribute → operator → value table: | Attribute | Operators | Values | |-------------------|-----------------------------|------------------------------------------| | dueAt | eq, not_eq, gt, lt | one date string "YYYY-MM-DD" | | createdAt | gt, lt | one date string "YYYY-MM-DD" | | completedAt | empty, not_empty, gt, lt | empty/not_empty take no value; gt/lt take one ISO 8601 datetime string | | assigneeUserId | in, not_in | one or more folk-prefixed user ids | | entity | in, not_in | one or more folk-prefixed entity ids | Operand-shape rules: - dueAt / createdAt → operand is a plain date string. Example: `{ "dueAt": { "gt": "2025-01-01" } }` - completedAt → empty/not_empty take no operand (task not yet completed / already completed). gt/lt take an ISO 8601 datetime string. Example: `{ "completedAt": { "not_empty": "" } }` Example: `{ "completedAt": { "gt": "2025-01-01T00:00:00.000Z" } }` - assigneeUserId → operand is one or more folk-prefixed user ids (`usr_...`). Obtain ids from folk_get_workspace_structure. Example: `{ "assigneeUserId": { "in": "usr_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf" } }` Example (exclude): `{ "assigneeUserId": { "not_in": "usr_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf" } }` - entity → operand is one or more folk-prefixed ids, all of the SAME entity type (`per_...` for people, `com_...` for companies, `obj_...` for objects — do not mix types in one filter). Obtain ids from folk_search_people, folk_search_companies, or folk_search_objects. Example: `{ "entity": { "in": ["per_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf"] } }` Example (exclude): `{ "entity": { "not_in": ["per_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf"] } }` Use combinator to control AND/OR logic across multiple filter entries. Omit filter entirely to return every task. onlyAssignedToMe (optional): when true, restricts results to tasks assigned to the current user, combined with any other filters. Returns paginated full task objects: up to `limit` tasks (default 20, max 100). The response includes nextCursor when more results are available; pass it back as cursor to get the next page. Use folk_get_task if taskId is already known.

folk_search_tasks

Stop a scheduled or sending campaign, or only some of its recipients. Messages already sent stay sent; the others are not sent (status "not_sent", notSentReason "stopped"). This cannot be undone. Use for: - stopping a campaign scheduled or launched by mistake - stopping the next steps for recipients who replied elsewhere To edit a scheduled campaign and launch it again instead, cancel its schedule with folk_cancel_campaign_schedule. Without recipientIds, the whole campaign becomes cancelled. Stopping a cancelled campaign again changes nothing. A campaign whose last step is already sending can only be stopped for some recipients. With recipientIds, the other recipients still receive their messages; once no recipient is left to send to, the campaign becomes cancelled, unless its last step is already sending: that step then ends with the messages already sent. Ids that are not recipients, or have nothing left to send, are listed in warnings. A campaign still processing its messages cannot be stopped yet: retry in a few seconds. A draft or in_review campaign has not been launched: there is nothing to stop. Remove recipients from it with folk_remove_campaign_recipient, or delete it with folk_delete_campaign.

folk_stop_campaign