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

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

# Update a person

`PUT` `/v2/persons/{personId}`

Operation ID: `updatePersonV2`

Partially updates the specified person's identity fields. Only the fields present in the request body are applied — omitted fields retain their existing values. The person must be owned by the authenticated customer. Returns 404 if the person does not exist or is not visible to the authenticated customer (cross-customer access returns 404, not 403).

## Path parameters

- `personId` (string, uuid, required) - ID of the person

## Request body (required)

Content types: `application/json`

## Responses

- `200` - Person updated successfully.
- `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/{personId}:
    put:
      summary: Update a person
      description: >
        Partially updates the specified person's identity fields. Only the
        fields present in the request body are applied — omitted fields retain
        their existing values. The person must be owned by the authenticated
        customer.


        Returns 404 if the person does not exist or is not visible to the
        authenticated customer (cross-customer access returns 404, not 403).
      operationId: updatePersonV2
      tags:
        - Persons
      security:
        - oauth2:
            - identity.profiles.write
      parameters:
        - $ref: "#/components/parameters/PersonIdParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePersonRequest"
      responses:
        "200":
          description: Person updated successfully.
          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:
                $ref: "#/components/schemas/PersonV2"
        "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.write
components:
  parameters:
    PersonIdParam:
      name: personId
      in: path
      description: ID of the person
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    UpdatePersonRequest:
      title: UpdatePersonRequest
      description: >
        Fields to apply to a person. Only non-null fields are applied — omitted
        or null fields leave the stored value untouched (partial update).
        `firstName` and `lastName` are required.
      type: object
      required:
        - firstName
        - lastName
      properties:
        firstName:
          type: string
          example: Grace
        lastName:
          type: string
          example: Hopper
        middleName:
          type: string
          nullable: true
        preferredFirstName:
          type: string
          nullable: true
          maxLength: 100
        title:
          $ref: "#/components/schemas/PersonTitle"
        suffix:
          $ref: "#/components/schemas/PersonSuffix"
        dateOfBirth:
          type: string
          format: date
          nullable: true
        gender:
          $ref: "#/components/schemas/PersonGender"
        primaryEmail:
          type: string
          format: email
          nullable: true
        secondaryEmail:
          type: string
          format: email
          nullable: true
        citizenshipCountry:
          type: string
          nullable: true
        residentState:
          type: string
          nullable: true
        unitedStatesCitizen:
          type: boolean
          nullable: true
        unitedStatesWorkAuthorized:
          type: boolean
          nullable: true
        married:
          type: boolean
          nullable: true
        npn:
          type: string
          nullable: true
          maxLength: 12
          pattern: ^[1-9][0-9]*$
          description: National Producer Number. Must start with a non-zero digit and
            contain only digits.
        finraCrdNumber:
          type: string
          nullable: true
          maxLength: 11
          pattern: ^[0-9]+$
          description: FINRA CRD number. Must contain only digits.
        ssn:
          type: string
          nullable: true
          minLength: 9
          maxLength: 9
          pattern: ^[0-9]*$
          description: Social Security Number. Must be exactly 9 digits.
    PersonV2:
      title: PersonV2
      description: >
        Customer-facing producer identity. SSN is masked — only the last four
        digits are present via `ssnLast4`. The full unmasked SSN is available
        only via `GET /v2/persons/{personId}/ssn`.
      type: object
      required:
        - id
        - npnVerified
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the person.
          readOnly: true
          example: 550e8400-e29b-41d4-a716-446655440000
        title:
          $ref: "#/components/schemas/PersonTitle"
        firstName:
          type: string
          description: The person's first name.
          example: Jane
        preferredFirstName:
          type: string
          nullable: true
          description: The name the person prefers to be addressed by, when different from
            their legal first name.
          example: Janey
        middleName:
          type: string
          nullable: true
          description: The person's middle name.
          example: Quincy
        lastName:
          type: string
          description: The person's last name.
          example: Smith
        suffix:
          $ref: "#/components/schemas/PersonSuffix"
        primaryEmail:
          type: string
          format: email
          nullable: true
          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.
          example: "12345678"
        npnVerified:
          type: boolean
          readOnly: true
          description: Whether the person's NPN has been verified against NIPR.
        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. Full SSN available
            only via GET /v2/persons/{personId}/ssn.
          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.
          readOnly: true
          example: 2026-06-01T14:22:00Z
    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
  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
  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)
```