> ## Documentation Index
> Fetch the complete documentation index at: https://developer.folk.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a person

> Retrieve an existing person in the workspace.



## OpenAPI

````yaml /schemas/2025-06-09.json get /v1/people/{personId}
openapi: 3.1.0
info:
  title: Folk External API
  description: >-
    Folk's public REST API lets you manage workspaces, groups, contacts, and
    real-time triggers.
  version: '2025-06-09'
  contact:
    name: folk
    email: tech@folk.app
    url: https://folk.app
servers:
  - url: https://api.folk.app
    description: Folk's public API production base URL.
    x-internal: false
security: []
tags:
  - name: Companies
    description: Operations related to companies.
  - name: Deals
    description: Operations related to deals.
  - name: Groups
    description: Operations related to groups.
  - name: Interactions
    description: Operations related to interactions.
  - name: Notes
    description: Operations related to notes.
  - name: People
    description: Operations related to people.
  - name: Reminders
    description: Operations related to reminders.
  - name: Tasks
    description: Operations related to tasks.
  - name: Users
    description: Operations related to users.
  - name: Webhooks
    description: Operations related to webhooks.
paths:
  /v1/people/{personId}:
    get:
      tags:
        - People
      summary: Get a person
      description: Retrieve an existing person in the workspace.
      operationId: getPerson
      parameters:
        - schema:
            type: string
            minLength: 40
            maxLength: 40
          required: true
          description: The ID of the person to retrieve.
          name: personId
          in: path
      responses:
        '200':
          description: The retrieved person in the workspace.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Person'
                  deprecations:
                    type: array
                    items:
                      type: string
                    example:
                      - This field is deprecated
                required:
                  - data
              example:
                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
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerApiKeyAuth: []
components:
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 1000
      description: >-
        The maximum number of requests that you can make in the current rate
        limit window.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 998
      description: The number of requests remaining in the current rate limit window.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1747322958
      description: >-
        The time at which the current rate limit window resets, in UTC epoch
        seconds.
    Retry-After:
      schema:
        type: integer
        example: 60
      description: >-
        The number of seconds to wait before making a new request after hitting
        the rate limit.
  schemas:
    Person:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
          description: The first name of the person.
          example: John
        lastName:
          type: string
          description: The last name of the person.
          example: Doe
        fullName:
          type: string
          description: The full name of the person.
          example: John Doe
        description:
          type: string
          description: A short description of the person.
          example: A brief description of the person.
        birthday:
          type:
            - string
            - 'null'
          minLength: 10
          maxLength: 10
          format: date
          description: >-
            The birthday of the person, in ISO format. Deleted with null or
            empty string.
          example: '1990-01-01'
        gender:
          type:
            - string
            - 'null'
          enum:
            - Male
            - Female
            - Unknown
            - Other
          description: >-
            The gender of the person. Authorized values are "Female", "Male",
            "Unknown", "Other" or null to delete it.
          example: Unknown
        jobTitle:
          type: string
          description: The job title of the person.
          example: Software Engineer
        createdAt:
          type:
            - string
            - 'null'
          minLength: 20
          maxLength: 40
          description: The date and time the person was created, in ISO format.
          example: '2021-01-01T00:00:00.000Z'
        createdBy:
          $ref: '#/components/schemas/User'
        groups:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
            required:
              - id
              - name
          description: The groups associated with the person.
          example:
            - id: grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
              name: Engineering
        companies:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: The id of the company.
                example: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
              name:
                type: string
                description: The name of the company.
                example: Tech Corp
            required:
              - id
              - name
          description: >-
            The companies associated with the person. The first company in the
            list is the person's primary company.
          example:
            - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
              name: Tech Corp
        addresses:
          type: array
          items:
            type: string
            description: >-
              An address associated with the person. The first address in the
              list is the person's primary address.
            example: 123 Main St, Springfield, USA
        emails:
          type: array
          items:
            type: string
            description: >-
              An email address associated with the person. The first email
              address in the list is the person's primary email address.
            example: john@example.com
        phones:
          type: array
          items:
            type: string
            description: >-
              A phone number associated with the person. The first phone number
              in the list is the person's primary phone number.
            example: '+1234567890'
        urls:
          type: array
          items:
            type: string
            description: >-
              A URL associated with the person. The first URL in the list is the
              person's primary URL.
            example: https://example.com
        customFieldValues:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              anyOf:
                - type: 'null'
                - type: string
                  description: A custom field value as a string.
                  example: Value 1
                - type: array
                  items:
                    type: string
                  description: An array of values for the custom field.
                  example:
                    - Value 1
                    - Value 2
                - type: array
                  items:
                    $ref: '#/components/schemas/User'
                  description: An array of users associated with the custom field.
                  example:
                    - id: usr_44b85098-441b-4d7f-9d72-c079b1caec45
                      fullName: Jane Doe
                      email: jane@example.com
                    - id: usr_a95a1b90-8e88-4855-bc29-d47b8e2704e1
                      fullName: John Doe
                      email: john@example.com
                - type: array
                  items:
                    anyOf:
                      - type: object
                        properties:
                          id:
                            type: string
                          fullName:
                            type: string
                          entityType:
                            type: string
                            enum:
                              - person
                        required:
                          - id
                          - fullName
                          - entityType
                      - type: object
                        properties:
                          id:
                            type: string
                          fullName:
                            type: string
                          entityType:
                            type: string
                            enum:
                              - company
                        required:
                          - id
                          - fullName
                          - entityType
                      - type: object
                        properties:
                          id:
                            type: string
                          fullName:
                            type: string
                          entityType:
                            type: string
                            enum:
                              - object
                        required:
                          - id
                          - fullName
                          - entityType
                  description: An array of relationships associated with the custom field.
                  example:
                    - id: per_183ed5cc-3182-45de-84d1-d520f2604810
                      fullName: John Doe
                      entityType: person
                    - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                      fullName: Tech Corp
                      entityType: company
                - type: 'null'
        interactionMetadata:
          $ref: '#/components/schemas/InteractionMetadata'
        strongestConnection:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/User'
          description: >-
            For each group the person is in, the workspace member with the
            strongest connection to the person. If the person has no strongest
            connection, this will be an empty object. Only the groups for which
            the person has a strongest connection will be included.
          example:
            grp_92346499-30bf-4278-ae8e-4aa3ae2ace2c:
              id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
              fullName: John Doe
              email: john.doe@example.com
      required:
        - id
        - firstName
        - lastName
        - fullName
        - description
        - birthday
        - gender
        - jobTitle
        - createdAt
        - createdBy
        - groups
        - companies
        - addresses
        - emails
        - phones
        - urls
        - customFieldValues
        - interactionMetadata
      description: 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'
        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
    User:
      type: object
      properties:
        id:
          type: string
        fullName:
          type: string
        email:
          type: string
      required:
        - id
        - fullName
        - email
      description: A user in the workspace.
      example:
        id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
        fullName: John Doe
        email: john.doe@example.com
    InteractionMetadata:
      type: object
      properties:
        user:
          type: object
          properties:
            approximateCount:
              type: integer
              minimum: 0
              description: >-
                The approximate number of interactions between the current user
                and the contact.
              example: 21
            lastInteractedAt:
              type:
                - string
                - 'null'
              format: date-time
              description: >-
                The last interaction date between the current user and the
                contact.
              example: '2025-05-01T00:00:00Z'
          required:
            - approximateCount
            - lastInteractedAt
        workspace:
          type: object
          properties:
            approximateCount:
              type: integer
              minimum: 0
              description: >-
                The approximate number of interactions of your workspace with
                the contact.
              example: 42
            lastInteractedAt:
              type:
                - string
                - 'null'
              format: date-time
              description: The last interaction date of your workspace with the contact.
              example: '2025-05-01T00:00:00Z'
            lastInteractedBy:
              type: array
              items:
                $ref: '#/components/schemas/User'
              description: >-
                List of users in your workspace who last interacted with the
                contact.
              example:
                - id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
                  fullName: John Doe
                  email: john.doe@example.com
          required:
            - approximateCount
            - lastInteractedAt
            - lastInteractedBy
      required:
        - user
        - workspace
      description: Metadata about interactions with the user and workspace.
      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: john.doe@example.com
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              additionalProperties: true
              example:
                limit: 1000
                remaining: 0
                retryAfter: '2025-10-01T12:00:00Z'
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
      required:
        - error
      description: Error response containing error details.
  responses:
    BadRequest:
      description: The request was unacceptable, often due to missing an invalid parameter.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_REQUEST
              message: The request was invalid.
              documentationUrl: https://developer.folk.app/api-reference/errors#bad-request
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Unauthorized:
      description: No valid API key provided.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: No valid API key provided.
              documentationUrl: https://developer.folk.app/api-reference/errors#unauthorized
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Forbidden:
      description: The API key doesn’t have permissions to perform the request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: The API key doesn’t have permissions to perform the request.
              documentationUrl: https://developer.folk.app/api-reference/errors#forbidden
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    NotFound:
      description: The requested resource doesn’t exist.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              documentationUrl: https://developer.folk.app/api-reference/errors#not-found
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    UnprocessableEntity:
      description: >-
        The request was unacceptable, often due to missing or invalid
        parameters.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNPROCESSABLE_ENTITY
              message: Invalid query parameters
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#unprocessable-entity
              details:
                issues:
                  - code: too_small
                    minimum: 1
                    type: number
                    inclusive: true
                    exact: false
                    message: Number must be greater than or equal to 1
                    path:
                      - limit
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    TooManyRequests:
      description: >-
        Too many requests hit the API too quickly. We recommend an exponential
        backoff of your requests.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RATE_LIMIT_EXCEEDED
              message: The rate limit has been exceeded.
              documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
              details:
                limit: 1000
                remaining: 0
                retryAfter: '2025-10-01T12:00:00Z'
    InternalServerError:
      description: Something went wrong on our end.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An internal server error occurred.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#internal-server-error
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    ServiceUnavailable:
      description: The server is overloaded or down for maintenance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SERVICE_UNAVAILABLE
              message: The service is currently unavailable.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#service-unavailable
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
  securitySchemes:
    bearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````