---
title: "Get entities for subscribed NPNs"
url: "https://developer.agentsync.io/apis/producer-sync-api/versions/bdfe7300-4ebb-41e2-95d6-66cc697404bc/operations/getEntities"
---

> Full API specification: https://developer.agentsync.io/apis/producer-sync-api/versions/bdfe7300-4ebb-41e2-95d6-66cc697404bc.md

# Get entities for subscribed NPNs

`GET` `/v2/entities`

Operation ID: `getEntities`

Returns all entity records for NPNs you are **currently subscribed** to. If no query parameters are provided in the request, then the response will include all entities 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)
- `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.85.1
servers:
  - url: https://api.sandbox.agentsync.io
    description: Sandbox
paths:
  /v2/entities:
    get:
      tags:
        - Producer Entities
      operationId: getEntities
      summary: Get entities for subscribed NPNs
      description: >
        Returns all entity records for NPNs you are **currently subscribed** to.


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

        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/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:
                      entities:
                        type: array
                        items:
                          $ref: "#/components/schemas/EntitiesV2Response"
                  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"
    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:
    EntitiesV2Response:
      allOf:
        - $ref: "#/components/schemas/EntitiesBaseResponse"
        - type: object
          properties:
            links:
              $ref: "#/components/schemas/EntitiesLinks"
    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
    EntitiesBaseResponse:
      type: object
      description: Common entity fields shared across versions.
      properties:
        id:
          type: integer
          format: int64
          example: 1234567
          description: Unique identifier for the entity.
        npn:
          type: string
          example: "18551108"
          description: National Producer Number associated with the entity.
        transactionId:
          type: string
          format: uuid
          example: ae51f10b-8b5e-40ba-98a9-8f860392b344
        type:
          type: string
          enum:
            - INDIVIDUAL
            - FIRM
          example: INDIVIDUAL
          description: Type of entity - individual or firm.
        feinId:
          type:
            - string
            - "null"
          example: "123456789"
          description: Federal Employer Identification Number. Expected to be NULL for
            individuals.
        companyName:
          type:
            - string
            - "null"
          example: Acme Insurance Group
          description: Name of the firm. Expected to be NULL for individuals.
        firstName:
          type: string
          example: Jeff
        middleName:
          type: string
          example: Lee
        lastName:
          type: string
          example: Android
        dateOfBirth:
          type:
            - string
            - "null"
          format: date
          example: 1983-12-15
          description: Date of birth for the producer. Expected to be NULL for a firm.
        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.
        noLicenses:
          type: boolean
          example: false
        subscriptionCount:
          type: integer
          example: 4
        niprDeleted:
          type: boolean
          example: false
          description: Indicates if the entity was marked deleted by NIPR.
    EntitiesLinks:
      type: object
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              format: uri
              example: https://api.sandbox.agentsync.io/v1/entities/1000013
        addresses:
          type: object
          properties:
            href:
              type: string
              format: uri
              example: https://api.sandbox.agentsync.io/v1/entities/1000013/addresses
        contactInfos:
          type: object
          properties:
            href:
              type: string
              format: uri
              example: https://api.sandbox.agentsync.io/v1/entities/1000013/contactInfos
        appointments:
          type: object
          properties:
            href:
              type: string
              format: uri
              example: https://api.sandbox.agentsync.io/v1/entities/1000013/appointments
        licenses:
          type: object
          properties:
            href:
              type: string
              format: uri
              example: https://api.sandbox.agentsync.io/v1/entities/1000013/licenses
        residentLicense:
          type: object
          properties:
            href:
              type: string
              format: uri
              example: https://api.sandbox.agentsync.io/v2/entities/1000013/residentLicense
  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
```