openapi: 3.0.0
info:
  title: 8x8 Administration - Address Management API
  version: "1.0"
  description: |
    Address management API providing endpoints to create, retrieve, list, and delete addresses.

    The current version of the API is v1.0.

    ## Authentication

    All requests to this API require authentication using an API key. Include your API key in the request header:

    ```
    x-api-key: YOUR_API_KEY
    ```

    ## Versioning

    The API version is specified through a vendor-specific media type. Send it in the `Content-Type` header for requests that carry a payload (such as `POST`) and in the `Accept` header for requests that return a payload (`GET`). The synchronous `DELETE` endpoint returns no content (`204`) and is not versioned.

    ```
    Content-Type: application/vnd.addresses.v1+json   # on POST (request payload)
    Accept: application/vnd.addresses.v1+json          # on GET (response payload)
    ```

    ## Base URL

    `https://api.8x8.com/admin-provisioning`

    ## Endpoints

    | Endpoint | Method | Purpose | Async? |
    |----------|--------|---------|--------|
    | `/addresses` | GET | Retrieve paginated list of addresses with filtering | No |
    | `/addresses` | POST | Create a new address | No |
    | `/addresses/{addressId}` | GET | Retrieve a specific address's details | No |
    | `/addresses/{addressId}` | DELETE | Remove an address | No |

    ## OpenAPI Specification

    Download the complete OpenAPI specification: [address-api-v1.yaml](/administration/address-api-v1.yaml)
servers:
  - url: https://api.8x8.com/admin-provisioning
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /addresses:
    get:
      operationId: listAddresses
      summary: List addresses
      description: |
        List addresses with optional filtering, sorting, and pagination.
        Uses infinite scroll pagination with scrollId for efficient navigation.
      tags:
        - Addresses
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
        - name: pageSize
          in: query
          description: 'Number of items per page (default: 100)'
          required: false
          schema:
            type: integer
            example: 100
        - name: scrollId
          in: query
          description: 'Scroll identifier for pagination (used to retrieve subsequent pages)'
          required: false
          schema:
            type: string
        - name: filter
          in: query
          description: "RSQL filter expression. Supported fields: country, state, displayForm. Example: 'country==US', 'country==US;state==CA'"
          required: false
          schema:
            type: string
            example: "country==US"
        - name: sort
          in: query
          description: "Sort expression. Use '+' prefix or no prefix for ascending order, '-' prefix for descending order (e.g., 'city', '+city', or '-city')"
          required: false
          schema:
            type: string
            example: "city"
      responses:
        '200':
          description: Successful response with paginated addresses
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/AddressPage'
              example:
                data:
                  - id: "b1c4944a-17a0-4b00-8d48-36001df07e22"
                    displayForm: "7 W 34TH ST, 613, New York NY, 10001"
                    streetNumber: "7"
                    preDirectional: "W"
                    streetName: "34TH ST"
                    secondaryLocation: "613"
                    city: "New York"
                    state: "NY"
                    postal: "10001"
                    country: "US"
                    createdTime: "2025-01-01T01:02:03Z"
                    origin: "ADMIN"
                pagination:
                  pageSize: 100
                  pageNumber: 0
                  hasMore: false
                _links:
                  self:
                    href: "/admin-provisioning/addresses?pageSize=100"
        '400':
          description: Bad Request - Validation errors or invalid parameters
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidSort:
                  summary: Invalid sort parameter
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "sort"
                        message: "Invalid sort expression"
                invalidFilter:
                  summary: Invalid filter parameter
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "filter"
                        message: "Invalid filter expression"
                invalidScrollId:
                  summary: Invalid scroll ID
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "scrollId"
                        message: "Invalid scroll identifier"
                conflictingParams:
                  summary: Conflicting query parameters
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "CONFLICTING_QUERY_PARAMETER"
                        message: "Cannot use scrollId with other query parameters"
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service Unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service is temporarily unavailable"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Internal Server Error"
                errors:
                  - code: "UNKNOWN"
                    message: "An unexpected error occurred"
    post:
      operationId: createAddress
      summary: Create address
      description: Create a new address
      tags:
        - Addresses
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/vnd.addresses.v1+json:
            schema:
              $ref: '#/components/schemas/AddressCreate'
            example:
              streetNumber: "7"
              streetName: "34TH ST"
              secondaryLocation: "613"
              city: "New York"
              state: "NY"
              postal: "10001"
              country: "US"
      responses:
        '200':
          description: Address created successfully
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/Address'
              example:
                id: "b1c4944a-17a0-4b00-8d48-36001df07e22"
                displayForm: "7 W 34TH ST, 613, New York NY, 10001"
                streetNumber: "7"
                preDirectional: "W"
                streetName: "34TH ST"
                secondaryLocation: "613"
                city: "New York"
                state: "NY"
                postal: "10001"
                country: "US"
                createdTime: "2025-01-01T01:02:03Z"
                origin: "ADMIN"
        '400':
          description: Bad Request - Validation errors
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingCountry:
                  summary: Missing required field
                  value:
                    status: 400
                    title: "Validation error"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "country"
                        message: "Required field is missing"
                multipleValidationErrors:
                  summary: Multiple validation errors
                  value:
                    status: 400
                    title: "Multiple validation errors"
                    errors:
                      - code: "VALIDATION_ERROR"
                        field: "city"
                        message: "Validation provider returned a different address"
                      - code: "VALIDATION_ERROR"
                        field: "streetName"
                        message: "Validation provider returned a different address"
                invalidCountryCode:
                  summary: Invalid country code
                  value:
                    status: 400
                    title: "Failed to create address"
                    errors:
                      - code: "VALIDATION_ERROR"
                        message: "Invalid country code"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Internal Server Error"
                errors:
                  - code: "UNKNOWN"
                    message: "An unexpected error occurred"
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service Unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service is temporarily unavailable"
  /addresses/{addressId}:
    get:
      operationId: getAddress
      summary: Get address by ID
      description: Retrieve a specific address by its ID
      tags:
        - Addresses
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
        - name: addressId
          in: path
          description: Address identifier
          required: true
          schema:
            type: string
            example: "b1c4944a-17a0-4b00-8d48-36001df07e22"
      responses:
        '200':
          description: Address retrieved successfully
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/Address'
              example:
                id: "b1c4944a-17a0-4b00-8d48-36001df07e22"
                displayForm: "7 W 34TH ST, 613, New York NY, 10001"
                streetNumber: "7"
                preDirectional: "W"
                streetName: "34TH ST"
                secondaryLocation: "613"
                city: "New York"
                state: "NY"
                postal: "10001"
                country: "US"
                createdTime: "2025-01-01T01:02:03Z"
                origin: "ADMIN"
                addressUsage:
                  customer: 1
                  site: 2
                  userExtension: 3
        '404':
          description: Not Found - Address does not exist
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                title: "Address not found"
                errors:
                  - code: "NOT_FOUND"
                    message: "Address not found: customerId: testCustomerId addressId: unknownAddress"
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service Unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service is temporarily unavailable"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Failed getting address internally"
                errors:
                  - code: "UNKNOWN"
                    message: "Failed getting address internally"
    delete:
      operationId: deleteAddress
      summary: Delete address
      description: Delete a specific address by its ID
      tags:
        - Addresses
      parameters:
        - name: X-Request-Id
          in: header
          description: Optional request identifier for tracking
          required: false
          schema:
            type: string
            format: uuid
        - name: addressId
          in: path
          description: Address identifier
          required: true
          schema:
            type: string
            example: "b1c4944a-17a0-4b00-8d48-36001df07e22"
      responses:
        '204':
          description: Address deleted successfully
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
        '400':
          description: Bad Request - Address is currently in use and cannot be deleted
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                title: "Address is currently in use and cannot be deleted"
                errors:
                  - code: "BAD_REQUEST"
                    message: "Address is currently in use and cannot be deleted"
        '404':
          description: Not Found - Address does not exist
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                title: "Address not found"
                errors:
                  - code: "NOT_FOUND"
                    message: "Address not found: customerId: testCustomerId addressId: unknownAddress"
        '500':
          description: Internal Server Error - Unexpected error occurred
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 500
                title: "Internal Server Error"
                errors:
                  - code: "UNKNOWN"
                    message: "An unexpected error occurred"
        '503':
          description: Service Unavailable - Service unavailable due to connectivity or network issues
          headers:
            X-Response-Id:
              description: Unique response identifier generated by the service
              schema:
                type: string
                format: uuid
          content:
            application/vnd.addresses.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 503
                title: "Service Unavailable"
                errors:
                  - code: "SERVICE_UNAVAILABLE"
                    message: "Service is temporarily unavailable"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    Address:
      type: object
      properties:
        id:
          type: string
          example: "b1c4944a-17a0-4b00-8d48-36001df07e22"
          readOnly: true
          nullable: true
        displayForm:
          type: string
          example: "7 W 34TH ST, 613, New York NY, 10001"
          nullable: true
        organization:
          type: string
          example: "8x8"
          minLength: 1
          maxLength: 128
          nullable: true
        building:
          type: string
          example: "Bardon Hall"
          minLength: 1
          maxLength: 128
          nullable: true
        streetNumber:
          type: string
          example: "7"
          minLength: 1
          maxLength: 45
          nullable: true
        streetNumberSuffix:
          type: string
          example: "bis"
          nullable: true
        preDirectional:
          type: string
          example: "W"
          nullable: true
        streetName:
          type: string
          example: "Whitechapel High Street"
          minLength: 1
          maxLength: 128
          nullable: true
        streetNameSuffix:
          type: string
          example: "Ave"
          nullable: true
        postDirectional:
          type: string
          example: "E"
          nullable: true
        dependentStreet:
          type: string
          example: "Gemini Business Park"
          minLength: 1
          maxLength: 128
          nullable: true
        secondaryLocation:
          type: string
          example: "UNIT 203"
          minLength: 1
          maxLength: 45
          nullable: true
        city:
          type: string
          example: "New York"
          minLength: 1
          maxLength: 45
          nullable: true
        dependentCity:
          type: string
          example: "NYC"
          minLength: 1
          maxLength: 45
          nullable: true
        state:
          type: string
          example: "NY"
          minLength: 1
          maxLength: 45
          nullable: true
        county:
          type: string
          example: "Santa Clara"
          minLength: 1
          maxLength: 45
          nullable: true
        postal:
          type: string
          example: "10001"
          minLength: 1
          maxLength: 45
          nullable: true
        zip4:
          type: string
          example: "2032"
          minLength: 1
          maxLength: 45
          nullable: true
        country:
          type: string
          example: "US"
          minLength: 1
          maxLength: 45
        createdTime:
          type: string
          format: date-time
          example: "2025-01-01T01:02:03Z"
          readOnly: true
          nullable: true
        origin:
          type: string
          enum: [ADMIN, TEAMS_OC, ADMIN_API]
          example: "ADMIN"
          nullable: true
        addressUsage:
          $ref: '#/components/schemas/AddressUsage'
      required:
        - country
    AddressCreate:
      type: object
      properties:
        organization:
          type: string
          example: "8x8"
          minLength: 1
          maxLength: 128
          nullable: true
        building:
          type: string
          example: "Bardon Hall"
          minLength: 1
          maxLength: 128
          nullable: true
        streetNumber:
          type: string
          example: "7"
          minLength: 1
          maxLength: 45
          nullable: true
        streetName:
          type: string
          example: "Whitechapel High Street"
          minLength: 1
          maxLength: 128
          nullable: true
        dependentStreet:
          type: string
          example: "Gemini Business Park"
          minLength: 1
          maxLength: 128
          nullable: true
        secondaryLocation:
          type: string
          example: "UNIT 203"
          minLength: 1
          maxLength: 45
          nullable: true
        city:
          type: string
          example: "New York"
          minLength: 1
          maxLength: 45
          nullable: true
        dependentCity:
          type: string
          example: "NYC"
          minLength: 1
          maxLength: 45
          nullable: true
        state:
          type: string
          example: "NY"
          minLength: 1
          maxLength: 45
          nullable: true
        county:
          type: string
          example: "Santa Clara"
          minLength: 1
          maxLength: 45
          nullable: true
        postal:
          type: string
          example: "10001"
          minLength: 1
          maxLength: 45
          nullable: true
        zip4:
          type: string
          example: "2032"
          minLength: 1
          maxLength: 45
          nullable: true
        country:
          type: string
          example: "US"
          minLength: 1
          maxLength: 45
      required:
        - country
    AddressUsage:
      type: object
      properties:
        customer:
          type: integer
          example: 1
          nullable: true
        site:
          type: integer
          example: 1
          nullable: true
        userPersonal:
          type: integer
          example: 1
          nullable: true
        userExtension:
          type: integer
          example: 1
          nullable: true
        trunk:
          type: integer
          example: 1
          nullable: true
        operatorConnect:
          type: integer
          example: 1
          nullable: true
        license:
          type: integer
          example: 1
          nullable: true
    AddressPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          nullable: true
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    Pagination:
      type: object
      properties:
        pageSize:
          type: integer
          description: Number of items per page
          example: 100
          nullable: true
        pageNumber:
          type: integer
          description: Current page number (0-indexed)
          example: 0
          nullable: true
        hasMore:
          type: boolean
          description: Indicates if there are more pages available
          example: false
          nullable: true
        filter:
          type: string
          description: RSQL filter expression used in the request
          example: "country==US"
          nullable: true
        sort:
          type: string
          description: Sort expression used in the request
          example: "city"
          nullable: true
        nextScrollId:
          type: string
          description: Scroll ID for retrieving the next page
          nullable: true
    PaginationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    Link:
      type: object
      properties:
        href:
          type: string
          description: URL for the link
          example: "/admin-provisioning/addresses?pageSize=100"
          nullable: true
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 404
          nullable: true
        instance:
          type: string
          description: URI reference that identifies the specific occurrence of the problem
          nullable: true
        time:
          type: string
          format: date-time
          description: Timestamp when the error occurred
          example: "2025-01-01T01:02:03Z"
          nullable: true
        title:
          type: string
          description: Short, human-readable summary of the problem
          example: "Address not found"
          nullable: true
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          nullable: true
    Error:
      type: object
      properties:
        field:
          type: string
          description: Field name related to the error
          nullable: true
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Detailed error message
          example: "Address not found"
          nullable: true
    ErrorCode:
      type: string
      enum:
        - UNKNOWN
        - VALIDATION_ERROR
        - FORBIDDEN
        - CONFLICTING_QUERY_PARAMETER
        - SERVICE_UNAVAILABLE
        - NOT_FOUND
        - BAD_REQUEST
        - REQUEST_TIMEOUT
        - TOO_MANY_REQUESTS
        - CONFLICT
      description: Error code indicating the type of error