> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/folk.md).

# folk

Create and manage people, companies, and groups in folk CRM.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| folk      | API Key        |

#### folk

Connect to folk to create and manage people, companies, and groups.

**Set up in folk**

1. Prepare the folk account or service that the workflow will access. Grant access to the required resources and operations.
2. **API Key:** Create an API key in folk under Settings, API, then paste it here.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **folk**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                        |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes      | Create an API key in folk under Settings, API, then paste it here. [Provider instructions](https://developer.folk.app/api-reference/authentication). |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **folk** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Person

Create a person in folk after acknowledging that an exact first-name, last-name, and email, phone, or personal social-profile match may trigger a background merge that overwrites existing data.

**Inputs**

| Field                       | Type            | Required | Description                                                                                                                                                                                    |
| --------------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| First name                  | string          | Yes      | The person's first name.                                                                                                                                                                       |
| Last name                   | string          | Yes      | The person's last name.                                                                                                                                                                        |
| Acknowledge automatic merge | boolean         | Yes      | Confirm that folk may background-merge an exact first-name, last-name, and email, phone, or personal social-profile match into an existing record and overwrite existing data. Default: false. |
| Primary email               | string          | No       | The person's primary email address; adding it can trigger automatic duplicate merging.                                                                                                         |
| Primary phone               | string          | No       | The person's primary phone number; adding it can trigger automatic duplicate merging.                                                                                                          |
| Personal social profile URL | string          | No       | A personal LinkedIn, Instagram, Facebook, or X profile URL; adding it can trigger automatic duplicate merging.                                                                                 |
| Job title                   | string          | No       | The person's role or job title.                                                                                                                                                                |
| Company name                | string          | No       | The person's primary company; folk creates the company if it does not exist.                                                                                                                   |
| Group                       | select (string) | No       | Optionally place the new person in a folk group. Options load from the selected connection.                                                                                                    |
| Description                 | textarea        | No       | Notes or context about the person.                                                                                                                                                             |

**Outputs**

| Field         | Type   | Description                                                        |
| ------------- | ------ | ------------------------------------------------------------------ |
| Person ID     | string | The folk person identifier returned immediately after creation.    |
| Full name     | string | The person's returned full name.                                   |
| Merge warning | string | A reminder that folk may still merge the record in the background. |

#### Create company

Create or return a company in folk using its workspace-unique name.

**Inputs**

| Field           | Type            | Required | Description                                                                                                                   |
| --------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Company name    | string          | Yes      | The company's workspace-unique name.                                                                                          |
| Description     | textarea        | No       | A short description of the company.                                                                                           |
| Industry        | string          | No       | The company's industry.                                                                                                       |
| Foundation year | integer         | No       | The four-digit year the company was founded.                                                                                  |
| Employee range  | select (string) | No       | The approximate number of employees. Available values: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10000+. |
| Primary website | string          | No       | The company's primary website URL.                                                                                            |
| Group           | select (string) | No       | Optionally place the company in a folk group. Options load from the selected connection.                                      |

**Outputs**

| Field        | Type   | Description                                      |
| ------------ | ------ | ------------------------------------------------ |
| Company ID   | string | The created or existing folk company identifier. |
| Company name | string | The returned company name.                       |

#### List people

List folk people with optional name, email, company, or group filters.

**Inputs**

| Field           | Type            | Required | Description                                                                                                            |
| --------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| Full name       | string          | No       | Only return people matching this full name.                                                                            |
| Email           | string          | No       | Only return people matching this email address.                                                                        |
| Company name    | string          | No       | Only return people associated with this company name.                                                                  |
| Group           | select (string) | No       | Only return people in this folk group. Options load from the selected connection.                                      |
| Filter matching | select (string) | No       | Require all filters or allow any filter to match. Available values: Match all filters, Match any filter. Default: and. |
| Maximum people  | integer         | No       | The maximum number of people to return in this call. Default: 100.                                                     |
| Cursor          | string          | No       | Continue from a cursor returned by an earlier call.                                                                    |

**Outputs**

| Field       | Type          | Description                                                   |
| ----------- | ------------- | ------------------------------------------------------------- |
| People      | object\_array | The typed list of matching folk people.                       |
| Next cursor | string        | The opaque cursor for the next page, when more people remain. |

#### List groups

List folk groups so people and companies can be assigned by group ID.

**Inputs**

| Field          | Type    | Required | Description                                           |
| -------------- | ------- | -------- | ----------------------------------------------------- |
| Maximum groups | integer | No       | The maximum number of groups to return. Default: 100. |
| Cursor         | string  | No       | Continue from a cursor returned by an earlier call.   |

**Outputs**

| Field       | Type          | Description                                                   |
| ----------- | ------------- | ------------------------------------------------------------- |
| Groups      | object\_array | The typed list of folk groups.                                |
| Next cursor | string        | The opaque cursor for the next page, when more groups remain. |

#### Add person to group

Add a person to a folk group while preserving current memberships. A concurrent group change can race because folk replaces the complete group list.

**Inputs**

| Field  | Type            | Required | Description                                                                                     |
| ------ | --------------- | -------- | ----------------------------------------------------------------------------------------------- |
| Person | select (string) | Yes      | The person to add to the group. Options load from the selected connection.                      |
| Group  | select (string) | Yes      | The group to add without removing other memberships. Options load from the selected connection. |

**Outputs**

| Field            | Type          | Description                                                 |
| ---------------- | ------------- | ----------------------------------------------------------- |
| Person ID        | string        | The updated folk person identifier.                         |
| Group IDs        | string\_array | All group memberships preserved on the person.              |
| Already a member | boolean       | Whether the person already belonged to the requested group. |

#### Update person

Update a person's scalar profile details in folk without replacing contact lists or group memberships.

**Inputs**

| Field       | Type            | Required | Description                                                                                   |
| ----------- | --------------- | -------- | --------------------------------------------------------------------------------------------- |
| Person      | select (string) | Yes      | The person to update. Options load from the selected connection.                              |
| First name  | string          | No       | A replacement first name; leave blank to keep it unchanged.                                   |
| Last name   | string          | No       | A replacement last name; leave blank to keep it unchanged.                                    |
| Job title   | string          | No       | A replacement job title; leave blank to keep it unchanged.                                    |
| Description | textarea        | No       | Replacement notes or context; leave blank to keep them unchanged.                             |
| Birthday    | date            | No       | A replacement birthday in YYYY-MM-DD format.                                                  |
| Gender      | select (string) | No       | A replacement gender value supported by folk. Available values: Male, Female, Unknown, Other. |

**Outputs**

| Field     | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| Person ID | string | The updated folk person identifier. |
| Full name | string | The person's updated full name.     |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/folk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
