FOfolk
People

Create people in batch

Changed on

Create up to 100 new people in the workspace. Each record is created on its own: one that fails does not prevent the others from being created.

post/v1/people/batch/create

Request

  • Base URL
    https://api.folk.app
  • URL
    https://api.folk.app/v1/people/batch/create
  • 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": [
    {
      "fullName": "John Doe",
      "jobTitle": "Software Engineer",
      "emails": [
        "john@example.com"
      ],
      "companies": [
        {
          "name": "Example Inc."
        }
      ],
      "groups": [
        {
          "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
        }
      ]
    }
  ]
}

Response

The outcome of each record, with each created 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"
            }
          }
        }
      },
      {
        "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