---
title: "List persons"
url: "https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8/operations/listV2Persons"
---

> Full API specification: https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8.md

# List persons

`GET` `/v2/persons`

Operation ID: `listV2Persons`

Returns persons paginated by opaque continuation token, ordered by (modifiedDate, id) ascending. Supply `updated_since` to fetch only records modified at or after a given timestamp, or `firm_id` to restrict results to persons associated with a specific firm. Returns 404 if `firm_id` is supplied but is not owned by your organization. Returns 401 when the request carries no token and 403 when the token lacks the required scope.

## Query parameters

- `page_token` (string, optional) - Opaque continuation token returned by the previous response's `page.nextToken`. Omit on the first request. Format is server-controlled and may change without an API version bump.
- `page_size` (integer, int32, optional) - Requested number of items in the response. Defaults to 25 when omitted; values outside `[1, 250]` are rejected with `400` (not clamped). The actual size returned is reflected in `page.size` and may be smaller (last page or empty result).
- `updated_since` (string, date-time, optional) - RFC3339 UTC timestamp (e.g. 2026-06-01T00:00:00Z). When supplied, filters to persons whose record was modified at or after this instant (inclusive).
- `firm_id` (string, uuid, optional) - UUID of a firm. When supplied, restricts the result to persons associated with that firm. Returns 404 if the firm is not visible to the authenticated customer (never 403, so firm existence is not leaked across customer boundaries).

## Responses

- `200` - A page of persons.
- `400` - One or more request fields failed validation
- `401` - No valid bearer token was presented
- `403` - The token does not carry the required scope
- `404` - The requested resource does not exist or is not visible to the caller
- `429` - Rate limit exceeded. The caller has exceeded the maximum number of requests allowed per rate-limit window for the authenticated credential. NOTE: The response body for this status deviates from the standard V2 error shape ({message, details, code}). The body contains only a top-level "message" string. Clients should treat the Retry-After header as the authoritative retry signal and must not parse the message string.
- `500` - An unexpected server error occurred

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Identity API
  version: v1.275.8
servers:
  - url: https://api.sandbox.agentsync.io/id
    description: Sandbox server
  - url: https://api.agentsync.io/id
    description: Production server
paths:
  /v2/persons:
    get:
      summary: List persons
      description: >
        Returns persons paginated by opaque continuation token, ordered by
        (modifiedDate, id) ascending. Supply `updated_since` to fetch only
        records modified at or after a given timestamp, or `firm_id` to restrict
        results to persons associated with a specific firm.


        Returns 404 if `firm_id` is supplied but is not owned by your
        organization. Returns 401 when the request carries no token and 403 when
        the token lacks the required scope.
      operationId: listV2Persons
      tags:
        - Persons
      security:
        - oauth2:
            - identity.profiles.read
      parameters:
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/PageSize"
        - name: updated_since
          in: query
          required: false
          description: >
            RFC3339 UTC timestamp (e.g. 2026-06-01T00:00:00Z). When supplied,
            filters to persons whose record was modified at or after this
            instant (inclusive).
          schema:
            type: string
            format: date-time
            example: 2026-06-01T00:00:00Z
        - name: firm_id
          in: query
          required: false
          description: >
            UUID of a firm. When supplied, restricts the result to persons
            associated with that firm. Returns 404 if the firm is not visible to
            the authenticated customer (never 403, so firm existence is not
            leaked across customer boundaries).
          schema:
            type: string
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        "200":
          description: A page of persons.
          headers:
            ratelimit-limit:
              $ref: "#/components/headers/ratelimit-limit"
            ratelimit-remaining:
              $ref: "#/components/headers/ratelimit-remaining"
            ratelimit-reset:
              $ref: "#/components/headers/ratelimit-reset"
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                  - page
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/PersonListItemV2"
                  page:
                    $ref: "#/components/schemas/Page"
        "400":
          $ref: "#/components/responses/V2BadRequest"
        "401":
          $ref: "#/components/responses/V2Unauthorized"
        "403":
          $ref: "#/components/responses/V2Forbidden"
        "404":
          $ref: "#/components/responses/V2NotFound"
        "429":
          $ref: "#/components/responses/V2TooManyRequests"
        "500":
          $ref: "#/components/responses/V2InternalServerError"
security:
  - oauth2:
      - identity.profiles.read
components:
  parameters:
    PageToken:
      name: page_token
      in: query
      required: false
      description: >
        Opaque continuation token returned by the previous response's
        `page.nextToken`. Omit on the first request. Format is server-controlled
        and may change without an API version bump.
      schema:
        type: string
    PageSize:
      name: page_size
      in: query
      required: false
      description: >
        Requested number of items in the response. Defaults to 25 when omitted;
        values outside `[1, 250]` are rejected with `400` (not clamped). The
        actual size returned is reflected in `page.size` and may be smaller
        (last page or empty result).
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 250
        default: 25
  headers:
    ratelimit-limit:
      description: >
        Maximum number of requests allowed per rate-limit window for the
        authenticated credential. The value returned in this header is
        authoritative; do not cache it.
      schema:
        type: integer
    ratelimit-remaining:
      description: Number of requests remaining in the current rate-limit window.
      schema:
        type: integer
    ratelimit-reset:
      description: >
        Unix timestamp (seconds) after which at least one additional request
        slot becomes available. In a sliding window this is a hint, not a hard
        reset point — retrying exactly at this instant may still return 429
        under sustained load.
      schema:
        type: integer
    Retry-After:
      description: >
        Minimum seconds to wait before retrying. Use this value directly as your
        retry delay; it already accounts for any server-side backoff.
      schema:
        type: integer
  schemas:
    PersonListItemV2:
      title: PersonListItemV2
      description: >
        A single person row returned by GET /v2/persons. Carries the person's
        core identity fields. Related resources such as addresses, phones,
        employments, and licenses are not included here — retrieve them via the
        single-resource and dedicated collection endpoints.
      type: object
      required:
        - id
        - updatedAt
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the person.
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        firstName:
          type: string
          description: The person's first name.
          example: Jane
        middleName:
          type: string
          nullable: true
          description: The person's middle name.
          example: Quincy
        lastName:
          type: string
          description: The person's last name.
          example: Smith
        preferredFirstName:
          type: string
          nullable: true
          description: The name the person prefers to be addressed by, when different from
            their legal first name.
          example: Janey
        title:
          $ref: "#/components/schemas/PersonTitle"
        suffix:
          $ref: "#/components/schemas/PersonSuffix"
        primaryEmail:
          type: string
          format: email
          description: The person's primary contact email address.
          example: jane.smith@example.com
        secondaryEmail:
          type: string
          format: email
          nullable: true
          description: The person's secondary contact email address.
          example: jane.alt@example.com
        dateOfBirth:
          type: string
          format: date
          nullable: true
          description: The person's date of birth (YYYY-MM-DD).
          example: 1990-05-15
        gender:
          $ref: "#/components/schemas/PersonGender"
        citizenshipCountry:
          type: string
          nullable: true
          description: The person's country of citizenship.
          example: US
        residentState:
          type: string
          nullable: true
          description: The person's state of residence.
          example: CO
        unitedStatesCitizen:
          type: boolean
          nullable: true
          description: Whether the person is a United States citizen.
          example: true
        unitedStatesWorkAuthorized:
          type: boolean
          nullable: true
          description: Whether the person is authorized to work in the United States.
          example: true
        married:
          type: boolean
          nullable: true
          description: Whether the person is married.
          example: false
        npn:
          type: string
          nullable: true
          description: National Producer Number. Null when the person's NPN has not been
            verified.
          example: "12345678"
        finraCrdNumber:
          type: string
          nullable: true
          description: The person's FINRA Central Registration Depository (CRD) number.
          example: "1234567"
        ssnLast4:
          type: string
          nullable: true
          description: Last four digits of the Social Security Number. Null when no SSN is
            on record.
          example: "6789"
        createdAt:
          type: string
          format: date-time
          description: RFC3339 timestamp when the person record was created.
          readOnly: true
          example: 2026-01-15T10:30:00Z
        updatedAt:
          type: string
          format: date-time
          description: RFC3339 timestamp of the most recent modification. Use this field
            with updated_since for delta sync.
          readOnly: true
          example: 2026-06-01T14:22:00Z
    Page:
      type: object
      description: Page metadata for a token-based list response.
      required:
        - size
        - nextToken
      properties:
        size:
          type: integer
          format: int32
          minimum: 0
          description: >
            Number of items actually returned in this response — equal to
            `items.length`. On an empty result this is `0`. This is NOT a copy
            of the request's `page_size` hint; clients holding the hint already
            know what they asked for.
          example: 25
        nextToken:
          type: string
          nullable: true
          description: >
            Opaque token to request the next page. `null` when this is the last
            page. Pass back as the `page_token` query parameter to resume.
          example: eyJ2IjoxLCJrIjp7InVwZGF0ZWRBdCI6IjIwMjYtMDUtMTlUMTI6MDA6MDBaIiwiaWQiOiIwMUhYWVoifX0
    PersonTitle:
      type: string
      nullable: true
      enum:
        - DR
        - MR
        - MRS
        - MS
        - MISS
      description: The person's honorific title.
      example: MS
    PersonSuffix:
      type: string
      nullable: true
      enum:
        - JR
        - SR
        - I
        - II
        - III
        - OBE
        - MBE
        - BSC
        - JP
        - GM
      description: The person's name suffix.
      example: JR
    PersonGender:
      type: string
      nullable: true
      enum:
        - MALE
        - FEMALE
      description: The person's gender.
      example: FEMALE
    V2Error:
      type: object
      required:
        - message
        - details
        - code
      properties:
        message:
          type: string
          description: Human-readable error summary. Do not parse — use "code" for
            branching.
          example: Validation failed
        details:
          type: array
          description: Per-field validation errors. Empty for all non-400 responses.
          items:
            $ref: "#/components/schemas/V2FieldError"
        code:
          type: string
          description: Stable machine-readable error code.
          enum:
            - validation_failed
            - unauthorized
            - unauthorized_scope
            - resource_not_found
            - conflict
            - unprocessable
            - unsupported_media_type
            - rate_limited
            - internal
          example: validation_failed
    V2FieldError:
      type: object
      required:
        - param
        - message
      properties:
        param:
          type: string
          description: The request field that failed validation
          example: email
        message:
          type: string
          description: Human-readable description of the failure
          example: must not be blank
  responses:
    V2BadRequest:
      description: One or more request fields failed validation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Validation failed
            code: validation_failed
            details:
              - param: email
                message: must not be blank
    V2Unauthorized:
      description: No valid bearer token was presented
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Authentication required
            code: unauthorized
            details: []
    V2Forbidden:
      description: The token does not carry the required scope
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Insufficient scope
            code: unauthorized_scope
            details: []
    V2NotFound:
      description: The requested resource does not exist or is not visible to the caller
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: Resource not found
            code: resource_not_found
            details: []
    V2TooManyRequests:
      description: >
        Rate limit exceeded. The caller has exceeded the maximum number of
        requests allowed per rate-limit window for the authenticated credential.

        NOTE: The response body for this status deviates from the standard V2
        error shape ({message, details, code}). The body contains only a
        top-level "message" string. Clients should treat the Retry-After header
        as the authoritative retry signal and must not parse the message string.
      headers:
        ratelimit-limit:
          $ref: "#/components/headers/ratelimit-limit"
        ratelimit-remaining:
          $ref: "#/components/headers/ratelimit-remaining"
        ratelimit-reset:
          $ref: "#/components/headers/ratelimit-reset"
        Retry-After:
          $ref: "#/components/headers/Retry-After"
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
          example:
            message: API rate limit exceeded
    V2InternalServerError:
      description: An unexpected server error occurred
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/V2Error"
          example:
            message: An unexpected error occurred
            code: internal
            details: []
  securitySchemes:
    oauth2:
      type: oauth2
      description: >
        OAuth2 client credentials. The `tokenUrl` below is the SANDBOX token
        endpoint; for production use `https://auth.agentsync.io/oauth2/token`.
        OpenAPI 3.0 permits only one token URL per flow, so both cannot be
        expressed here — see the Authentication section for the full environment
        table.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sandbox.agentsync.io/oauth2/token
          scopes:
            identity.profiles.read: Read access to producer profile resources (V2 customer-facing)
            identity.profiles.write: Write access to producer profile resources (V2 customer-facing)
```