People

Update a person

Update an existing person in the workspace.

patch/v1/people/{personId}

Request

Base URL
https://api.folk.app
URL
https://api.folk.app/v1/people/{personId}
Auth
HTTP bearer

Path parameters

personIdstring required

The ID of the person to update.

Headers

Idempotency-Keystring

A unique key, such as a UUID, that makes retrying this request safe: a retry with the same key and body returns the original response without running the operation again. Keys are kept for 24 hours after the request completes.

Example:8e03978e-40d5-43e8-bc93-6894a57f9324

Request body

firstNamestring

The first name of the person.

lastNamestring

The last name of the person.

fullNamestring

The full name of the person.

descriptionstring

A short description of the person.

gender'Male' | 'Female' | 'Unknown' | 'Other' nullable

The gender of the person. Authorized values are "Female", "Male", "Unknown", "Other" or null to delete it.

jobTitlestring

The job title of the person.

addressesstring[]

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

emailsstring[]

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

phonesstring[]

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

urlsstring[]

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

customFieldValuesobject

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". Use the exact option labels of the custom field (case-sensitive): an unknown label creates a new option.
multipleSelect: array of strings (option labels), eg: ["B2B", "B2C"]. Use the exact option labels of the custom field (case-sensitive): an unknown label creates a new option.
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"}]
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 request

{
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "description": "A brief description of the person.",
  "gender": "Unknown",
  "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"
        }
      ]
    }
  }
}

Response

The updated person in the workspace.

deprecationsstring[]

Example response

{
  "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",
    "gender": "Female",
    "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"
          }
        ]
      }
    },
    "strongestConnection": {
      "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
        "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
        "fullName": "John Doe",
        "email": "john.doe@example.com"
      }
    }
  },
  "deprecations": [
    "This field is deprecated"
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.