Get a person

Get a person

curl --request GET \
  --url https://api.folk.app/v1/people/{personId} \
  --header 'Authorization: Bearer <token>'

{
  "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": "[email protected]"
    },
    "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": [
      "[email protected]",
      "[email protected]"
    ],
    "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": "[email protected]"
          }
        ]
      }
    },
    "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": "[email protected]"
          }
        ]
      }
    }
  }
}

GET

people

{personId}

Get a person

curl --request GET \
  --url https://api.folk.app/v1/people/{personId} \
  --header 'Authorization: Bearer <token>'

{
  "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": "[email protected]"
    },
    "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": [
      "[email protected]",
      "[email protected]"
    ],
    "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": "[email protected]"
          }
        ]
      }
    },
    "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": "[email protected]"
          }
        ]
      }
    }
  }
}

Authorizations

Authorization

string

header

required

API key for authentication

Path Parameters

personId

string

required

The ID of the person to retrieve.

Required string length: 40

Response

The retrieved person in the workspace.

data

object

required

A person in the workspace.

Show child attributes

data.id

string

required

data.firstName

string

required

The first name of the person.

Example:

"John"

data.lastName

string

required

The last name of the person.

Example:

"Doe"

data.fullName

string

required

The full name of the person.

Example:

"John Doe"

data.description

string

required

A short description of the person.

Example:

"A brief description of the person."

data.birthday

string<date> | null

required

The birthday of the person, in ISO format.

Required string length: 10

Example:

"1990-01-01"

data.jobTitle

string

required

The job title of the person.

Example:

"Software Engineer"

data.createdAt

string | null

required

The date and time the person was created, in ISO format.

Required string length: 20 - 40

Example:

"2021-01-01T00:00:00.000Z"

data.createdBy

object

required

A user in the workspace.

Show child attributes

data.createdBy.id

string

required

data.createdBy.fullName

string

required

data.createdBy.email

string

required

Example:

{
  "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
  "fullName": "John Doe",
  "email": "[email protected]"
}

data.groups

object[]

required

The groups associated with the person.

Show child attributes

data.groups.id

string

required

data.groups.name

string

required

Example:

[
  {
    "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
    "name": "Tech Corp"
  }
]

data.companies

object[]

required

The companies associated with the person. The first company in the list is the person's primary company.

Show child attributes

data.companies.id

string

required

The id of the company.

Example:

"com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"

data.companies.name

string

required

The name of the company.

Example:

"Tech Corp"

Example:

[
  {
    "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
    "name": "Tech Corp"
  }
]

data.addresses

string[]

required

An address associated with the person. The first address in the list is the person's primary address.

data.emails

string[]

required

An email address associated with the person. The first email address in the list is the person's primary email address.

data.phones

string[]

required

A phone number associated with the person. The first phone number in the list is the person's primary phone number.

data.urls

string[]

required

A URL associated with the person. The first URL in the list is the person's primary URL.

data.customFieldValues

object

required

Show child attributes

data.customFieldValues.{key}

object

Show child attributes

data.customFieldValues.{key}.{key}

A custom field value as a string.

Example:

"Value 1"

data.interactionMetadata

object

required

Metadata about interactions with the user and workspace.

Show child attributes

data.interactionMetadata.user

object

required

Show child attributes

data.interactionMetadata.user.approximateCount

integer

required

The approximate number of interactions between the current user and the contact.

Required range: x >= 0

Example:

21

data.interactionMetadata.user.lastInteractedAt

string<date-time> | null

required

The last interaction date between the current user and the contact.

Example:

"2025-05-01T00:00:00Z"

data.interactionMetadata.workspace

object

required

Show child attributes

data.interactionMetadata.workspace.approximateCount

integer

required

The approximate number of interactions of your workspace with the contact.

Required range: x >= 0

Example:

42

data.interactionMetadata.workspace.lastInteractedAt

string<date-time> | null

required

The last interaction date of your workspace with the contact.

Example:

"2025-05-01T00:00:00Z"

data.interactionMetadata.workspace.lastInteractedBy

object[]

required

List of users in your workspace who last interacted with the contact.

Show child attributes

data.interactionMetadata.workspace.lastInteractedBy.id

string

required

data.interactionMetadata.workspace.lastInteractedBy.fullName

string

required

data.interactionMetadata.workspace.lastInteractedBy.email

string

required

Example:

[
  {
    "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
    "fullName": "John Doe",
    "email": "[email protected]"
  }
]

Example:

{
  "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": "[email protected]"
      }
    ]
  }
}

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": "[email protected]"
  },
  "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": ["[email protected]", "[email protected]"],
  "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": "[email protected]"
        }
      ]
    }
  },
  "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": "[email protected]"
        }
      ]
    }
  }
}

deprecations

string[]

Example:

["This field is deprecated"]

Create a person Delete a person

⌘I

Introducton

Available endpoints

Authorizations

Path Parameters

Response