---
title: "Get addresses for subscribed NPNs"
url: "https://developer.agentsync.io/apis/producer-sync-api/versions/953bc6f0-354b-4960-adc0-3acdb3d638a2/operations/getAddresses"
---

> Full API specification: https://developer.agentsync.io/apis/producer-sync-api/versions/953bc6f0-354b-4960-adc0-3acdb3d638a2.md

# Get addresses for subscribed NPNs

`GET` `/v2/addresses`

Operation ID: `getAddresses`

Returns all address records for NPNs you are **currently subscribed** to. If no query parameters are provided in the request, then the response will include all addresses for all currently subscribed NPNs. To maximize effectiveness, we strongly recommend using at least one parameter to narrow your results.

## Query parameters

- `npns` (array, optional) - comma separated list of National Producer Numbers (NPNs)
- `states` (array, optional) - comma separated list of states abbreviations (must be 2 characters) - this will filter on the `forState` field
- `updatedSince` (string, date, optional) - limits results to those that have an updated date equivalent to or after to the date provided (YYYY-MM-DD) - this will filter on the `updatedAt` field
- `includeDeleted` (boolean, optional) - specifiy whether or not deleted records should be included in the response - this will filter on the `niprDeleted` field
- `size` (integer, int64, optional) - the number of objects on the page (min = 1 / max = 1,000)
- `continuationToken` (string, optional) - Token for fetching the next page of results

## Responses

- `200` - Success
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `405` - Method Not Allowed
- `429` - Too Many Requests
- `500` - Internal Server Error
- `504` - Gateway Timeout

## OpenAPI definition

```yaml
openapi: 3.1.1
info:
  title: ProducerSync API
  version: v2.80.2
servers:
  - url: https://api.sandbox.agentsync.io
    description: Sandbox
paths:
  /v2/addresses:
    get:
      tags:
        - Producer Addresses
      operationId: getAddresses
      summary: Get addresses for subscribed NPNs
      description: >
        Returns all address records for NPNs you are **currently subscribed**
        to.


        If no query parameters are provided in the request, then the response
        will include all addresses

        for all currently subscribed NPNs. To maximize effectiveness, we
        strongly recommend using at least one

        parameter to narrow your results.
      parameters:
        - $ref: "#/components/parameters/npnsParam"
        - $ref: "#/components/parameters/statesParam"
        - $ref: "#/components/parameters/updatedSinceParam"
        - $ref: "#/components/parameters/includeDeletedParam"
        - $ref: "#/components/parameters/sizeParam"
        - $ref: "#/components/parameters/continuationTokenParam"
      responses:
        "200":
          description: Success
          content:
            application/hal+json:
              schema:
                type: object
                properties:
                  embedded:
                    type: object
                    properties:
                      addresses:
                        type: array
                        items:
                          $ref: "#/components/schemas/AddressV2Response"
                  links:
                    $ref: "#/components/schemas/LinksV2"
          headers:
            ratelimit-limit:
              $ref: "#/components/headers/ratelimit-limit"
            ratelimit-remaining:
              $ref: "#/components/headers/ratelimit-remaining"
            ratelimit-reset:
              $ref: "#/components/headers/ratelimit-reset"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"
        "405":
          $ref: "#/components/responses/405MethodNotAllowed"
        "429":
          $ref: "#/components/responses/429TooManyRequests"
        "500":
          $ref: "#/components/responses/500InternalServerError"
        "504":
          $ref: "#/components/responses/504GatewayTimeout"
components:
  parameters:
    npnsParam:
      name: npns
      in: query
      description: comma separated list of National Producer Numbers (NPNs)
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      explode: false
      example:
        - "123456789"
        - "987654321"
    statesParam:
      name: states
      in: query
      description: comma separated list of states abbreviations (must be 2 characters)
        - this will filter on the `forState` field
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      explode: false
      example:
        - MO
        - CA
        - CO
    updatedSinceParam:
      name: updatedSince
      in: query
      description: limits results to those that have an updated date equivalent to or
        after to the date provided (YYYY-MM-DD) - this will filter on the
        `updatedAt` field
      required: false
      schema:
        type: string
        format: date
        example: 2024-10-15
    includeDeletedParam:
      name: includeDeleted
      in: query
      description: specifiy whether or not deleted records should be included in the
        response - this will filter on the `niprDeleted` field
      required: false
      schema:
        type: boolean
        default: true
    sizeParam:
      name: size
      in: query
      description: the number of objects on the page (min = 1 / max = 1,000)
      required: false
      schema:
        type: integer
        format: int64
        default: 250
        minimum: 1
        maximum: 1000
    continuationTokenParam:
      name: continuationToken
      in: query
      description: Token for fetching the next page of results
      required: false
      schema:
        type: string
  schemas:
    AddressV2Response:
      allOf:
        - $ref: "#/components/schemas/AddressBaseResponse"
        - type: object
          properties:
            links:
              $ref: "#/components/schemas/SelfLink"
    LinksV2:
      type: object
      properties:
        next:
          type: object
          properties:
            href:
              type: string
              example: https://access.sandbox.agentsync.io/v2/{endpoint}?continuationToken=1282784
        self:
          type: object
          properties:
            href:
              type: string
              example: https://access.sandbox.agentsync.io/v2/{endpoint}?continuationToken=0
    AddressBaseResponse:
      type: object
      description: Common address fields shared across versions.
      properties:
        id:
          type: integer
          format: int64
          example: 1234567
          description: Unique identifier for the address.
        npn:
          type: string
          example: "18551108"
          description: National Producer Number associated with the address.
        transactionId:
          type: string
          format: uuid
          example: ae51f10b-8b5e-40ba-98a9-8f860392b344
        type:
          type: string
          enum:
            - BUSINESS
            - MAILING
            - RESIDENCE
          example: BUSINESS
          description: Type of address. One of `BUSINESS`, `MAILING`, `RESIDENCE`
        forState:
          type: string
          example: AL
          minLength: 2
          maxLength: 2
          description: State where the address applies.
        branchId:
          type: string
          example: ""
          description: Identifier for a related branch, if applicable.
        niprDateUpdated:
          type: string
          format: date
          example: 2024-12-01
          description: Last date NIPR reported an update to this address.
        createdAt:
          type: string
          format: date
          example: 2021-04-04
          description: Date of the creation of this record in AgentSync.
        updatedAt:
          type: string
          format: date
          example: 2024-12-02
          description: Date of the most recent update to this record in AgentSync.
        line1:
          type: string
          example: 789 S Washington Ave
          description: Street address.
        city:
          type: string
          example: Denver
          description: City of the address.
        state:
          type: string
          example: CO
          description: State of the address.
        zip:
          type: string
          example: "80211"
          description: ZIP or postal code.
        country:
          type: string
          example: U.S.A.
          description: Country of the address.
        niprDeleted:
          type: boolean
          example: false
          description: Indicates if the address was marked deleted by NIPR.
    SelfLink:
      type: object
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              example: https://api.sandbox.agentsync.io/v1/{endpoint}/{id}
  headers:
    ratelimit-limit:
      description: Maximum number of requests allowed in the current window
      schema:
        type: integer
    ratelimit-remaining:
      description: Number of requests remaining in the current window
      schema:
        type: integer
    ratelimit-reset:
      description: Time when the rate limit will reset
      schema:
        type: integer
  responses:
    400BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              timestamp:
                type: integer
                example: 1742929112
              status:
                type: integer
                example: 400
              error:
                type: string
                example: Bad Request
              message:
                type: string
                example: Invalid parameter values provided - {parameter}:[{invalid values}]
              path:
                type: string
                example: "{endpoint_path}"
    401Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized
    403Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              timestamp:
                type: integer
                example: 1742935636
              status:
                type: integer
                example: 403
              path:
                type: string
                example: "{requested endpoint}"
              error:
                type: string
                example: Forbidden
    404NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              timestamp:
                type: integer
                example: 1742929112
              status:
                type: integer
                example: 404
              error:
                type: string
                example: Not Found
              message:
                type: string
                example: Error message describing what was not found
              path:
                type: string
                example: "{requested endpoint}"
    405MethodNotAllowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                example: about:blank
              status:
                type: integer
                example: 405
              detail:
                type: string
                example: Method 'PUT' is not supported.
              instance:
                type: string
                example: "{requested endpoint}"
    429TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: API rate limit exceeded
    500InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              timestamp:
                type: integer
                example: 1613510729601
              status:
                type: integer
                example: 500
              error:
                type: string
                example: Internal Server Error
              message:
                type: string
                example: Error message describing why this was a server error.
              path:
                type: string
                example: "{requested endpoint}"
    504GatewayTimeout:
      description: Gateway Timeout
```