Skip to main content
POST
/
v1
/
people
Create a person
curl --request POST \
  --url https://api.folk.app/v1/people \
  --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"
          }
        ]
      }
    }
  }
}
Create a person in the workspace, optionally adding them to one or more groups. In the app, people without groups will only be visible through the “Search” section.
Folk automatically checks for duplicates when creating people. If the system detects a duplicate, the newly created person will be merged in the background, possibly overwriting some of the provided data.

Authorizations

​
Authorization
string
header
required

API key for authentication

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 person created 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"]