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

# List persons for a customer

> List people for one of your customers across their business entities.

List people for one of your customers across their business entities.

If the person you need does not exist yet, create them with [Create a person](/engine/commendaos/partner-api/commenda-os-persons-POST).

Person responses include `residentialAddress` as a top-level field. They do not include a person `locations` array; Location resources are business-entity addresses.


## OpenAPI

````yaml GET /partner/commenda-os/customers/{customerId}/persons
openapi: 3.0.1
info:
  title: Commenda Public APIs
  description: >-
    APIs for Commenda entity management, partner incorporation, indirect tax,
    compliance, and corporate operations.
  license:
    name: NONE
    url: NONE
  version: 1.0.0
servers:
  - url: https://api.prod.commenda.io/api/v1
    description: Commenda platform APIs, including Partner Incorporation and Commenda OS.
  - url: https://transaction-tax.api.in.commenda.io/api/v1
    description: Global Indirect Tax API.
security:
  - bearerAuth: []
paths:
  /partner/commenda-os/customers/{customerId}/persons:
    get:
      summary: List persons for a customer
      description: List people for one of your customers across their business entities.
      operationId: listPartnerCommendaOsPersons
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: integer
          description: Commenda customer identifier.
      responses:
        '200':
          description: Persons retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPersonsResponse'
        '401':
          description: Missing or invalid partner API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommendaOsPartnerError'
      security:
        - xApiKeyAuth: []
      servers:
        - url: https://api.prod.commenda.io/api/v1
components:
  schemas:
    CommendaOsPersonsResponse:
      type: object
      required:
        - persons
        - count
      properties:
        persons:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsPerson'
        count:
          type: integer
          example: 2
    CommendaOsPartnerError:
      type: object
      required:
        - statusCode
        - message
        - error
      properties:
        statusCode:
          type: integer
          description: HTTP status code for the error response.
        message:
          description: >-
            Error message returned by the API. Exact text varies by failure
            mode.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        error:
          type: string
          description: Standard error label for the response status.
    CommendaOsPerson:
      type: object
      required:
        - id
        - firstName
        - lastName
        - dateOfBirth
        - email
        - kycIds
        - residentialAddress
        - stakeholderId
        - phoneNumber
        - businessEntitiesInfo
      properties:
        id:
          type: integer
          example: 12
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Founder
        dateOfBirth:
          type: string
          example: '1990-04-18'
        email:
          type: string
          format: email
          example: jane@acme.com
        gender:
          type: string
          nullable: true
        nationalities:
          type: array
          items:
            type: string
        kycIds:
          type: array
          items:
            $ref: '#/components/schemas/CommendaOsKycId'
        residentialAddress:
          type: object
          allOf:
            - $ref: '#/components/schemas/CommendaOsPersonAddress'
          nullable: true
          description: >-
            Person residential address, used for participant resource
            requirements such as
            `participants.{participantId}.resource.residentialAddress`.
        onboardingInfo:
          type: object
          nullable: true
          additionalProperties: true
        stakeholderId:
          type: string
          example: stk_123
        phoneNumber:
          type: string
          example: '+14155550123'
        employmentStartDate:
          type: string
          nullable: true
          example: '2025-01-01'
        directorIdentificationNumber:
          type: string
          nullable: true
          description: Director Identification Number (DIN) assigned to Indian directors.
          example: '00012345'
        businessEntitiesInfo:
          type: array
          items:
            type: object
            required:
              - businessEntityId
              - businessEntityName
              - sharePercentage
              - governanceRelationships
            properties:
              businessEntityId:
                type: integer
                example: 44
              businessEntityName:
                type: string
                example: Acme Holdings LLC
              sharePercentage:
                type: number
                example: 75
              governanceRelationships:
                type: object
                description: >
                  Map of governance roles this person holds at the business
                  entity, keyed by role name. The value carries role-specific
                  flags. The set of keys present is a subset of `DIRECTOR`,
                  `AUTHORIZED_SIGNATORY`, and `BENEFICIAL_OWNER`.
                  `BENEFICIAL_OWNER` is included when the person is currently
                  recorded as an ultimate beneficial owner (UBO) of the business
                  entity by Commenda's ownership engine.
                additionalProperties: true
                example:
                  DIRECTOR:
                    startDate: '2020-01-15'
                    endDate: null
                    isResidentDirector: true
                  BENEFICIAL_OWNER:
                    isBeneficialOwner: true
              jobTitle:
                type: array
                items:
                  type: string
              startDateOfEmployment:
                type: string
                nullable: true
                example: '2025-01-01'
              isResidentDirector:
                type: boolean
                nullable: true
                description: >-
                  Whether this director is a resident director of the business
                  entity. Applicable to jurisdictions that require at least one
                  locally resident director (e.g. India).
    CommendaOsKycId:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          example: US_SSN
        name:
          type: string
          example: Social Security Number
        value:
          type: string
          nullable: true
        documentId:
          type: string
          nullable: true
        doesNotHaveKYCId:
          type: boolean
          nullable: true
        decryptedValue:
          type: string
          nullable: true
    CommendaOsPersonAddress:
      type: object
      description: Address fields stored directly on a Commenda OS person.
      required:
        - addressLine1
        - city
        - country
      properties:
        addressLine1:
          type: string
          example: 1 Raffles Place
        addressLine2:
          type: string
          nullable: true
          example: Suite 21045
        addressLine3:
          type: string
          nullable: true
        city:
          type: string
          example: Singapore
        postalCode:
          type: string
          nullable: true
          example: '048616'
        state:
          type: string
          nullable: true
        country:
          type: string
          example: SG
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````