Every business has different data needs, and folk is designed to be flexible in supporting any kind of data model.
Custom fields are used to add additional information to people and companies inside a group. They are group specific, and their name must be unique within the group. For instance, you can have a custom field called “Status” in the “Clients” group and another field called “Status” in the “Partners” group.

​
Field types

folk supports the following types of custom fields:

  • textField: Used for short descriptions or names.
  • numericField: Used for numbers, optionally formatted with a currency symbol.
  • dateField: Used for calendar dates.
  • singleSelect: Used for a single value from a predefined list of options.
  • multipleSelect: Used for multiple values from a predefined list of options.
  • contactField: Used to store a reference to other contacts in the same workspace.
  • userField: Used to store a reference to a workspace member.
  • magicField: Used to generate data based on the contact’s information.
  • objectField: Used to link deals to a contact.

​
Custom field format in the API

Since custom fields are always group specific, when retrieving or setting their values on people or companies, their values are always grouped by their group ID.

When retrieving a person or a company through the API, the response will contain a customFieldValues object with the group ID as the key and the custom field value as the value.
For instance, the response for a person inside a group called “Clients” with id grp_79b6ed73-9939-4118-ba65-7f8cdf401052 and a custom field called “Status” of type select will look like this:

{
  "data": {
    "id": "per_e2cbb1e5-c8b2-4f7b-8588-5952d6cc4acd",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "description": "",
    "birthday": null,
    "jobTitle": "",
    "groups": [
      {
        "id": "grp_79b6ed73-9939-4118-ba65-7f8cdf401052",
        "name": "Clients"
      }
    ],
    "companies": [],
    "addresses": [],
    "emails": ["john.doe@example.com"],
    "phones": [],
    "urls": [],
    "customFieldValues": {
      "grp_79b6ed73-9939-4118-ba65-7f8cdf401052": {
        "Status": "Active"
      }
    }
  }
}

In case the person is part of multiple groups, each with multiple custom fields, the customFieldValues object will contain all the custom fields grouped by their group ID:

{
  "data": {
    "id": "per_e2cbb1e5-c8b2-4f7b-8588-5952d6cc4acd",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "description": "",
    "birthday": null,
    "jobTitle": "",
    "groups": [
      {
        "id": "grp_79b6ed73-9939-4118-ba65-7f8cdf401052",
        "name": "Clients"
      },
      {
        "id": "grp_39828bcf-97f4-407e-866e-a99e6242ccb8",
        "name": "Partners"
      }
    ],
    "companies": [],
    "addresses": [],
    "emails": ["john.doe@example.com"],
    "phones": [],
    "urls": [],
    "customFieldValues": {
      "grp_79b6ed73-9939-4118-ba65-7f8cdf401052": {
        "Status": "Active",
        "Proposal sent at": "2024-01-01"
      },
      "grp_39828bcf-97f4-407e-866e-a99e6242ccb8": {
        "Status": "In progress",
        "Estimated revenue": 100000,
        "Tags": ["VIP", "New"]
      }
    }
  }
}

If the group defines custom fields, but the person or company does not have a value set for a custom field, the customFieldValues object will contain the custom field key with a null value.

{
  "data": {
    "id": "per_e2cbb1e5-c8b2-4f7b-8588-5952d6cc4acd",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "description": "",
    "birthday": null,
    "jobTitle": "",
    "groups": [
      {
        "id": "grp_79b6ed73-9939-4118-ba65-7f8cdf401052",
        "name": "Clients"
      },
      {
        "id": "grp_39828bcf-97f4-407e-866e-a99e6242ccb8",
        "name": "Partners"
      }
    ],
    "companies": [],
    "addresses": [],
    "emails": ["john.doe@example.com"],
    "phones": [],
    "urls": [],
    "customFieldValues": {
      "grp_79b6ed73-9939-4118-ba65-7f8cdf401052": {
        "Status": null,
        "Proposal sent at": null
      },
      "grp_39828bcf-97f4-407e-866e-a99e6242ccb8": {
        "Status": null,
        "Estimated revenue": null,
        "Tags": null
      }
    }
  }
}

When working with custom fields, it’s important to always know the group ID you are working with. You can use the list groups endpoint to get the list of groups and their IDs.

When removing a person from a group, the corresponding custom field values will be removed as well.