Skip to main content
PATCH
/
v1
/
people
/
{personId}
Update a person
curl --request PATCH \
  --url https://api.folk.app/v1/people/{personId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "description": "A brief description of the person.",
  "birthday": "1990-01-01",
  "jobTitle": "Software Engineer",
  "groups": [
    {
      "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
    }
  ],
  "companies": [
    {
      "name": "Tech Corp"
    },
    {
      "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
    }
  ],
  "addresses": [
    "123 Main St, Springfield, USA",
    "456 Main St, Springfield, USA"
  ],
  "emails": [
    "john@example.com",
    "john@techcorp.com"
  ],
  "phones": [
    "+1234567890",
    "+0987654321"
  ],
  "urls": [
    "https://example.com",
    "https://example.com/about"
  ],
  "customFieldValues": {
    "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
      "Status": "Active",
      "Programming languages": [
        "Javascript",
        "Python"
      ],
      "Join date": "2021-01-01",
      "Relationships": [
        {
          "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f"
        },
        {
          "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03"
        }
      ]
    },
    "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
      "Favorite color": "Blue",
      "Favorite number": 42,
      "Assignee": [
        {
          "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
        },
        {
          "email": "jane@example.com"
        }
      ]
    }
  }
}'
{
  "data": {
    "id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "description": "John Doe is a software engineer at Tech Corp.",
    "birthday": "1980-06-15",
    "jobTitle": "Software Engineer",
    "createdAt": "2021-01-01T00:00:00.000Z",
    "createdBy": {
      "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
      "fullName": "John Doe",
      "email": "john.doe@example.com"
    },
    "groups": [
      {
        "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
        "name": "Engineering"
      }
    ],
    "companies": [
      {
        "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
        "name": "Tech Corp"
      }
    ],
    "addresses": [
      "123 Main St, Springfield, USA",
      "456 Main St, Springfield, USA"
    ],
    "emails": [
      "john@example.com",
      "john@techcorp.com"
    ],
    "phones": [
      "+1234567890",
      "+0987654321"
    ],
    "urls": [
      "https://example.com"
    ],
    "customFieldValues": {
      "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
        "Status": "Active",
        "Programming languages": [
          "Javascript",
          "Python"
        ],
        "Join date": "2021-01-01",
        "Relationships": [
          {
            "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f",
            "fullName": "Bob Smith",
            "entityType": "person"
          },
          {
            "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03",
            "fullName": "HR services",
            "entityType": "company"
          }
        ]
      },
      "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
        "Favorite color": "Blue",
        "Favorite number": "42",
        "Assignee": [
          {
            "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
            "fullName": "Jane Doe",
            "email": "jane@example.com"
          }
        ]
      }
    },
    "interactionMetadata": {
      "user": {
        "approximateCount": 21,
        "lastInteractedAt": "2025-05-01T00:00:00Z"
      },
      "workspace": {
        "approximateCount": 21,
        "lastInteractedAt": "2025-05-01T00:00:00Z",
        "lastInteractedBy": [
          {
            "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
            "fullName": "John Doe",
            "email": "john.doe@example.com"
          }
        ]
      }
    }
  }
}
Update an existing person in the workspace, updating only the provided fields and leaving the rest of the person’s data unchanged.
Fields with a list of values (groups, companies, addresses, emails, phones, urls) will replace the old values. This means that you must provide the entire list of values for that field, not just the values you want to add.
When removing a person from a group, their custom field values for that group are also removed.

Authorizations

​
Authorization
string
header
required

API key for authentication

Path Parameters

​
personId
string
required

The ID of the person to update.

Required string length: 40

Body

application/json
​
firstName
string

The first name of the person.

Maximum length: 500
Example:

"John"

​
lastName
string

The last name of the person.

Maximum length: 500
Example:

"Doe"

​
fullName
string

The full name of the person.

Maximum length: 1000
Example:

"John Doe"

​
description
string

A short description of the person.

Maximum length: 5000
Example:

"A brief description of the person."

​
birthday
string<date> | null

The birthday of the person, in ISO format.

Required string length: 10
Example:

"1990-01-01"

​
jobTitle
string

The job title of the person.

Maximum length: 500
Example:

"Software Engineer"

​
groups
object[]

The groups to add the person to. You must provide group ids.

Maximum length: 100
Example:
[
  {
    "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
  }
]
​
companies
object[]

The companies associated with the person. You can either provide a name or an id. If you provide a name, the company will be created if it does not already exist. The first company in the list will be the person's primary company.

Maximum length: 20
  • Option 1
  • Option 2
Example:
[
  { "name": "Tech Corp" },
  {
    "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
  }
]
​
addresses
string[]

A list of addresses associated with the person. The first address in the list will be the person's primary address.

Maximum length: 20
Example:
[
  "123 Main St, Springfield, USA",
  "456 Main St, Springfield, USA"
]
​
emails
string[]

A list of email addresses associated with the person. The first email address in the list will be the person's primary email address.

Maximum length: 20
Example:
["john@example.com", "john@techcorp.com"]
​
phones
string[]

A list of phone numbers associated with the person. The first phone number in the list will be the person's primary phone number.

Maximum length: 20
Example:
["+1234567890", "+0987654321"]
​
urls
string[]

A list of URLs associated with the person. The first URL in the list will be the person's primary URL.

Maximum length: 20
Example:
[
  "https://example.com",
  "https://example.com/about"
]
​
customFieldValues
object

The custom field values associated with the person, grouped by group ids. The format is the following:

{
  "<groupId>": {
    "<customFieldName>": "<customFieldValue>"
  }
}

The group ids passed must also be provided in the groups field, otherwise a validation error will be thrown.

The format of the custom field value depends on the type of the custom field:

  • textField: string, eg: "Foo"
  • numericField: number or numeric string, eg: 42 or "42"
  • dateField: ISO 8601 string (YYYY-MM-DD), eg: "2021-01-01"
  • singleSelect: string (option label), eg: "Active"
  • multipleSelect: array of strings (option labels), eg: ["B2B", "B2C"]
  • contactField: array of objects with id property, eg: [{"id": "per_20228901-ce2b-418c-a267-671823107d8c"}]
  • userField: array of objects with either id (workspace user id) or email (workspace user email) property, eg: [{"id": "usr_a23373bb-5296-4c59-b2e8-8f121707d562"}, {"email": "jane@example.com"}]
  • magicField: string, eg: "foo"
  • objectField: array of objects with id property, eg: [{"id": "obj_2f62707c-52c0-421a-a11f-68e1ce9610f4"}]

Passing a null value or an empty array will unset the custom field value.

Example:
{
  "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
    "Status": "Active",
    "Programming languages": ["Javascript", "Python"],
    "Join date": "2021-01-01",
    "Relationships": [
      {
        "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f"
      },
      {
        "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03"
      }
    ]
  },
  "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
    "Favorite color": "Blue",
    "Favorite number": 42,
    "Assignee": [
      {
        "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
      },
      { "email": "jane@example.com" }
    ]
  }
}

Response

The updated person in the workspace.

​
data
object
required

A person in the workspace.

Example:
{
  "id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "description": "John Doe is a software engineer at Tech Corp.",
  "birthday": "1980-06-15",
  "jobTitle": "Software Engineer",
  "createdAt": "2021-01-01T00:00:00.000Z",
  "createdBy": {
    "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
    "fullName": "John Doe",
    "email": "john.doe@example.com"
  },
  "groups": [
    {
      "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
      "name": "Engineering"
    }
  ],
  "companies": [
    {
      "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
      "name": "Tech Corp"
    }
  ],
  "addresses": [
    "123 Main St, Springfield, USA",
    "456 Main St, Springfield, USA"
  ],
  "emails": ["john@example.com", "john@techcorp.com"],
  "phones": ["+1234567890", "+0987654321"],
  "urls": ["https://example.com"],
  "customFieldValues": {
    "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
      "Status": "Active",
      "Programming languages": ["Javascript", "Python"],
      "Join date": "2021-01-01",
      "Relationships": [
        {
          "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f",
          "fullName": "Bob Smith",
          "entityType": "person"
        },
        {
          "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03",
          "fullName": "HR services",
          "entityType": "company"
        }
      ]
    },
    "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
      "Favorite color": "Blue",
      "Favorite number": "42",
      "Assignee": [
        {
          "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
          "fullName": "Jane Doe",
          "email": "jane@example.com"
        }
      ]
    }
  },
  "interactionMetadata": {
    "user": {
      "approximateCount": 21,
      "lastInteractedAt": "2025-05-01T00:00:00Z"
    },
    "workspace": {
      "approximateCount": 21,
      "lastInteractedAt": "2025-05-01T00:00:00Z",
      "lastInteractedBy": [
        {
          "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
          "fullName": "John Doe",
          "email": "john.doe@example.com"
        }
      ]
    }
  }
}
​
deprecations
string[]
Example:
["This field is deprecated"]