--- title: "Get a person by ID" url: "https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8/operations/getPersonV2" --- > Full API specification: https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8.md # Get a person by ID `GET` `/v2/persons/{personId}` Operation ID: `getPersonV2` Returns the customer-facing identity for the specified person. The person must be owned by the authenticated customer. 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`. Returns 404 if the person does not exist or is not visible to the authenticated customer. ## Path parameters - `personId` (string, uuid, required) - ID of the person ## Responses - `200` - Person retrieved successfully. - `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}: get: summary: Get a person by ID description: > Returns the customer-facing identity for the specified person. The person must be owned by the authenticated customer. 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`. Returns 404 if the person does not exist or is not visible to the authenticated customer. operationId: getPersonV2 tags: - Persons security: - oauth2: - identity.profiles.read parameters: - $ref: "#/components/parameters/PersonIdParam" responses: "200": description: Person retrieved 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" "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: PersonIdParam: name: personId in: path description: ID of the person required: true schema: type: string format: uuid 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: 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 responses: 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) ```