--- title: "List addresses for a person" url: "https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8/operations/listPersonAddressesV2" --- > Full API specification: https://developer-staging.agentsync.io/apis/identity/versions/1ed33a2c-924a-434c-9643-fbc531dea1b8.md # List addresses for a person `GET` `/v2/persons/{personId}/addresses` Operation ID: `listPersonAddressesV2` Returns addresses belonging to the specified person and visible to the authenticated customer, paginated by opaque continuation token. Results are ordered by (modifiedDate ASC, id ASC). Returns 404 if the person does not exist or is not visible to the authenticated customer. A 403 is returned only when the caller's token lacks the required scope; cross-customer access returns 404, not 403. ## Path parameters - `personId` (string, uuid, required) - ID of the person ## 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). ## Responses - `200` - A page of addresses belonging to the person. - `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}/addresses: get: summary: List addresses for a person description: > Returns addresses belonging to the specified person and visible to the authenticated customer, paginated by opaque continuation token. Results are ordered by (modifiedDate ASC, id ASC). Returns 404 if the person does not exist or is not visible to the authenticated customer. A 403 is returned only when the caller's token lacks the required scope; cross-customer access returns 404, not 403. operationId: listPersonAddressesV2 tags: - Addresses security: - oauth2: - identity.profiles.read parameters: - $ref: "#/components/parameters/PersonIdParam" - $ref: "#/components/parameters/PageToken" - $ref: "#/components/parameters/PageSize" responses: "200": description: A page of addresses belonging to the person. 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/AddressV2" 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: PersonIdParam: name: personId in: path description: ID of the person required: true schema: type: string format: uuid 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: AddressV2: title: AddressV2 type: object required: - id - type - addressLine1 - city - state - zip - country - preferred - createdAt properties: id: type: string format: uuid description: Address identifier. readOnly: true example: 550e8400-e29b-41d4-a716-446655440000 type: $ref: "#/components/schemas/AddressType" addressLine1: type: string description: First line of the street address. example: 123 Main St addressLine2: type: string nullable: true description: Second line of the street address (suite, unit, etc.). example: Apt 4B city: type: string description: City. example: Denver state: type: string minLength: 2 maxLength: 2 description: Two-letter US state code. example: CO zip: type: string nullable: true pattern: ^\d{5}(-\d{4})?$ description: ZIP code in 5-digit or ZIP+4 format. example: "80202" county: type: string nullable: true description: County name. example: Denver country: type: string nullable: true minLength: 2 maxLength: 2 description: Country code (ISO alpha-2). example: US moveInDate: type: string format: date nullable: true description: Date the person moved to this address (YYYY-MM-DD). example: 2020-01-15 preferred: type: boolean description: Whether this is the person's preferred address. example: true createdAt: type: string format: date-time description: RFC3339 UTC timestamp when the address was created. readOnly: true example: 2024-01-15T10:30:00Z updatedAt: type: string format: date-time nullable: true description: RFC3339 UTC timestamp when the address was last updated. readOnly: true example: 2024-01-15T14:45: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 AddressType: type: string enum: - MAILING - BUSINESS - PHYSICAL description: Type of address 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) ```