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

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

# Create a person

`POST` `/v2/persons`

Operation ID: `createPersonV2`

Creates a new producer identity and associates them with the authenticated customer. The new person is immediately visible to the caller's organization. When `sendInvite` is omitted or `false`, the person is created without sending an email invitation. Set `sendInvite: true` to trigger the same invite email as the V1 `?sendInvite=true` path. Returns 400 when required fields are missing or field values fail validation.

## Header parameters

- `Idempotency-Key` (string, uuid, optional) - Client-generated UUID used to deduplicate retried requests. When provided, the server caches the first successful response for this key and returns it for any subsequent request with the same key from the same client, without re-processing.

## Request body (required)

Content types: `application/json`

## Responses

- `201` - Person created 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
- `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:
    post:
      summary: Create a person
      description: >
        Creates a new producer identity and associates them with the
        authenticated customer. The new person is immediately visible to the
        caller's organization.


        When `sendInvite` is omitted or `false`, the person is created without
        sending an email invitation. Set `sendInvite: true` to trigger the same
        invite email as the V1 `?sendInvite=true` path.


        Returns 400 when required fields are missing or field values fail
        validation.
      operationId: createPersonV2
      tags:
        - Persons
      security:
        - oauth2:
            - identity.profiles.write
      parameters:
        - $ref: "#/components/parameters/IdempotencyKeyParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePersonRequest"
      responses:
        "201":
          description: Person created 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"
        "429":
          $ref: "#/components/responses/V2TooManyRequests"
        "500":
          $ref: "#/components/responses/V2InternalServerError"
security:
  - oauth2:
      - identity.profiles.write
components:
  parameters:
    IdempotencyKeyParam:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: >
        Client-generated UUID used to deduplicate retried requests. When
        provided, the server caches the first successful response for this key
        and returns it for any subsequent request with the same key from the
        same client, without re-processing.
  schemas:
    CreatePersonRequest:
      title: CreatePersonRequest
      description: >
        Fields for creating a new person. `firstName`, `lastName`, and
        `primaryEmail` are required. `sendInvite` defaults to `false`; set it to
        `true` to trigger an email invitation. Internal-only fields (customer
        ID, intake ID) are not accepted.
      type: object
      required:
        - firstName
        - lastName
        - primaryEmail
      properties:
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Smith
        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
          example: jane.smith@example.com
        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.
        sendInvite:
          type: boolean
          default: false
          description: When true, sends an email invitation to the person. Defaults to
            false.
    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: []
    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)
```