FOfolk
People

Update people in batch

Changed on

Update up to 100 existing people in the workspace, each with the fields PATCH /v1/people/{personId} accepts. Each record is updated on its own: one that fails does not prevent the others from being updated.

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.

groups replaces the groups of the person, and removing a group deletes data. A group you can access that is missing from groups is removed from the person, together with the person's custom field values in that group. This is the opposite of POST /v1/people/batch/create, where groups only adds: the same payload adds groups when it creates a person and removes groups when it updates one. Leave groups out to keep the person's groups unchanged. Each result lists the groups it removed in removedGroups.

The records of one person, by its ID or by the ID of a person merged into it, are merged into one update, in request order: the last value given for a field wins, and customFieldValues are merged group by group, the last value given for a custom field winning. The merged update is validated as a whole: if it is invalid, every record of that person fails with that error. Each of those records gets its own result, with the person as finally updated.

post/v1/people/batch/update

Request

  • Base URL
    https://api.folk.app
  • URL
    https://api.folk.app/v1/people/batch/update
  • Auth
    HTTP bearer

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

Example request

{
  "records": [
    {
      "id": "per_183ed5cc-3182-45de-84d1-d520f2604810",
      "jobTitle": "Engineering Manager",
      "emails": [
        "john@example.com"
      ],
      "customFieldValues": {
        "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
          "Status": "Active"
        }
      }
    }
  ]
}

Response

The outcome of each record, with each updated person.

deprecationsstring[]

Example response

{
  "data": {
    "results": [
      {
        "status": "succeeded",
        "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"
            }
          }
        },
        "removedGroups": [
          {
            "id": "grp_2b7c9e14-3f8a-4d61-a5e2-7c0d9b4f6a13"
          }
        ]
      },
      {
        "status": "failed",
        "error": {
          "code": "NOT_FOUND",
          "message": "Not found.",
          "documentationUrl": "https://developer.folk.app/api-reference/errors#not-found"
        }
      }
    ]
  },
  "deprecations": [
    "This field is deprecated"
  ]
}

Changes