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

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

# Get appointments for subscribed NPNs

`GET` `/v2/appointments`

Operation ID: `getAppointments`

Returns all appointment records for NPNs you are **currently subscribed** to. If no query parameters are provided in the request, then the response will include all appointments 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
- `coCodes` (string, optional) - comma separated list of company/co codes (must by 5 digits) - this will filter on the `coCode` field
- `status` (string, optional) - A single appointment status to search for. This is an exact string match of either `TERMINATED` or `APPOINTED` - this will filter on the `status` field
- `loaCategories` (array, optional) - comma seperated list of loa categories - this will filter on the `loaMapping.categories` array (it will return all records containing at least one of the values passed)
- `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/appointments:
    get:
      tags:
        - Producer Appointments
      operationId: getAppointments
      summary: Get appointments for subscribed NPNs
      description: >
        Returns all appointment records for NPNs you are **currently
        subscribed** to.


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

        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/coCodesParam"
        - $ref: "#/components/parameters/statusParam"
        - $ref: "#/components/parameters/loaCategoriesParam"
        - $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:
                      appointments:
                        type: array
                        items:
                          $ref: "#/components/schemas/AppointmentsV2Response"
                  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
    coCodesParam:
      name: coCodes
      in: query
      description: comma separated list of company/co codes (must by 5 digits) - this
        will filter on the `coCode` field
      required: false
      schema:
        type: string
        example: 24740,70408,21458
    statusParam:
      name: status
      in: query
      description: A single appointment status to search for. This is an exact string
        match of either `TERMINATED` or `APPOINTED` - this will filter on the
        `status` field
      required: false
      schema:
        type: string
        enum:
          - TERMINATED
          - APPOINTED
        example: TERMINATED
    loaCategoriesParam:
      name: loaCategories
      in: query
      description: comma seperated list of loa categories - this will filter on the
        `loaMapping.categories` array (it will return all records containing at
        least one of the values passed)
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      explode: false
      example:
        - casualty
        - property
    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:
    AppointmentsV2Response:
      allOf:
        - $ref: "#/components/schemas/AppointmentsBaseResponse"
        - 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
    AppointmentsBaseResponse:
      type: object
      description: Base schema containing common appointment fields.
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the appointment.
          example: 1234567
        npn:
          type: string
          description: National Producer Number associated with the appointment.
          example: "18551108"
        transactionId:
          type: string
          format: uuid
          example: ae51f10b-8b5e-40ba-98a9-8f860392b344
        forState:
          type: string
          description: Two-letter state code where the appointment applies.
          example: AL
          minLength: 2
          maxLength: 2
        branchId:
          type: string
          description: Optional branch identifier.
          example: ""
        companyName:
          type: string
          description: Name of the appointing insurance company.
          example: My Insurance Company
        feinId:
          type: string
          description: Federal Employer Identification Number (FEIN) of the company.
          example: ""
        coCode:
          type: string
          description: 5-digit company code.
          example: "98765"
          minLength: 5
          maxLength: 5
        loa:
          type: string
          description: Line of Authority (LOA) name.
          example: Property
        loaCode:
          type: string
          description: Line of Authority code (may be numeric or alphanumeric).
          example: "12"
        status:
          type: string
          description: Appointment status (e.g., Active, Terminated).
          example: Terminated
        statusReasonDate:
          type: string
          format: date
          description: Date when the current status took effect.
          example: 2024-02-29
        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.
        terminationReason:
          type: string
          description: Reason for termination, if applicable.
          example: Not for Cause
        countyCode:
          type: string
          description: Optional county code.
          example: ""
        loaMapping:
          $ref: "#/components/schemas/LoaMapping"
        niprDeleted:
          type: boolean
          description: Indicates if the appointment is marked as deleted by NIPR.
          example: false
    SelfLink:
      type: object
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              example: https://api.sandbox.agentsync.io/v1/{endpoint}/{id}
    LoaMapping:
      type: object
      properties:
        categories:
          type: array
          items:
            type: string
          example:
            - property
            - health
            - casualty
  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
```