8x8 Addresses API

openapi: 3.2.0
info:
  title: 8x8 Administration - Address Management Addresses 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: []
tags:
- name: Addresses
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:
  schemas:
    Address:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          example: b1c4944a-17a0-4b00-8d48-36001df07e22
          readOnly: true
        displayForm:
          type:
          - string
          - 'null'
          example: 7 W 34TH ST, 613, New York NY, 10001
        organization:
          type:
          - string
          - 'null'
          example: 8x8
          minLength: 1
          maxLength: 128
        building:
          type:
          - string
          - 'null'
          example: Bardon Hall
          minLength: 1
          maxLength: 128
        streetNumber:
          type:
          - string
          - 'null'
          example: '7'
          minLength: 1
          maxLength: 45
        streetNumberSuffix:
          type:
          - string
          - 'null'
          example: bis
        preDirectional:
          type:
          - string
          - 'null'
          example: W
        streetName:
          type:
          - string
          - 'null'
          example: Whitechapel High Street
          minLength: 1
          maxLength: 128
        streetNameSuffix:
          type:
          - string
          - 'null'
          example: Ave
        postDirectional:
          type:
          - string
          - 'null'
          example: E
        dependentStreet:
          type:
          - string
          - 'null'
          example: Gemini Business Park
          minLength: 1
          maxLength: 128
        secondaryLocation:
          type:
          - string
          - 'null'
          example: UNIT 203
          minLength: 1
          maxLength: 45
        city:
          type:
          - string
          - 'null'
          example: New York
          minLength: 1
          maxLength: 45
        dependentCity:
          type:
          - string
          - 'null'
          example: NYC
          minLength: 1
          maxLength: 45
        state:
          type:
          - string
          - 'null'
          example: NY
          minLength: 1
          maxLength: 45
        county:
          type:
          - string
          - 'null'
          example: Santa Clara
          minLength: 1
          maxLength: 45
        postal:
          type:
          - string
          - 'null'
          example: '10001'
          minLength: 1
          maxLength: 45
        zip4:
          type:
          - string
          - 'null'
          example: '2032'
          minLength: 1
          maxLength: 45
        country:
          type: string
          example: US
          minLength: 1
          maxLength: 45
        createdTime:
          type:
          - string
          - 'null'
          format: date-time
          example: '2025-01-01T01:02:03Z'
          readOnly: true
        origin:
          type:
          - string
          - 'null'
          enum:
          - ADMIN
          - TEAMS_OC
          - ADMIN_API
          example: ADMIN
        addressUsage:
          $ref: '#/components/schemas/AddressUsage'
      required:
      - country
    AddressPage:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Address'
        pagination:
          $ref: '#/components/schemas/Pagination'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    AddressUsage:
      type: object
      properties:
        customer:
          type:
          - integer
          - 'null'
          example: 1
        site:
          type:
          - integer
          - 'null'
          example: 1
        userPersonal:
          type:
          - integer
          - 'null'
          example: 1
        userExtension:
          type:
          - integer
          - 'null'
          example: 1
        trunk:
          type:
          - integer
          - 'null'
          example: 1
        operatorConnect:
          type:
          - integer
          - 'null'
          example: 1
        license:
          type:
          - integer
          - 'null'
          example: 1
    Pagination:
      type: object
      properties:
        pageSize:
          type:
          - integer
          - 'null'
          description: Number of items per page
          example: 100
        pageNumber:
          type:
          - integer
          - 'null'
          description: Current page number (0-indexed)
          example: 0
        hasMore:
          type:
          - boolean
          - 'null'
          description: Indicates if there are more pages available
          example: false
        filter:
          type:
          - string
          - 'null'
          description: RSQL filter expression used in the request
          example: country==US
        sort:
          type:
          - string
          - 'null'
          description: Sort expression used in the request
          example: city
        nextScrollId:
          type:
          - string
          - 'null'
          description: Scroll ID for retrieving the next page
    Error:
      type: object
      properties:
        field:
          type:
          - string
          - 'null'
          description: Field name related to the error
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type:
          - string
          - 'null'
          description: Detailed error message
          example: Address not found
    AddressCreate:
      type: object
      properties:
        organization:
          type:
          - string
          - 'null'
          example: 8x8
          minLength: 1
          maxLength: 128
        building:
          type:
          - string
          - 'null'
          example: Bardon Hall
          minLength: 1
          maxLength: 128
        streetNumber:
          type:
          - string
          - 'null'
          example: '7'
          minLength: 1
          maxLength: 45
        streetName:
          type:
          - string
          - 'null'
          example: Whitechapel High Street
          minLength: 1
          maxLength: 128
        dependentStreet:
          type:
          - string
          - 'null'
          example: Gemini Business Park
          minLength: 1
          maxLength: 128
        secondaryLocation:
          type:
          - string
          - 'null'
          example: UNIT 203
          minLength: 1
          maxLength: 45
        city:
          type:
          - string
          - 'null'
          example: New York
          minLength: 1
          maxLength: 45
        dependentCity:
          type:
          - string
          - 'null'
          example: NYC
          minLength: 1
          maxLength: 45
        state:
          type:
          - string
          - 'null'
          example: NY
          minLength: 1
          maxLength: 45
        county:
          type:
          - string
          - 'null'
          example: Santa Clara
          minLength: 1
          maxLength: 45
        postal:
          type:
          - string
          - 'null'
          example: '10001'
          minLength: 1
          maxLength: 45
        zip4:
          type:
          - string
          - 'null'
          example: '2032'
          minLength: 1
          maxLength: 45
        country:
          type: string
          example: US
          minLength: 1
          maxLength: 45
      required:
      - country
    PaginationLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    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
    Link:
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
          description: URL for the link
          example: /admin-provisioning/addresses?pageSize=100
    ErrorResponse:
      type: object
      properties:
        status:
          type:
          - integer
          - 'null'
          description: HTTP status code
          example: 404
        instance:
          type:
          - string
          - 'null'
          description: URI reference that identifies the specific occurrence of the problem
        time:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp when the error occurred
          example: '2025-01-01T01:02:03Z'
        title:
          type:
          - string
          - 'null'
          description: Short, human-readable summary of the problem
          example: Address not found
        detail:
          type:
          - string
          - 'null'
          description: Human-readable explanation specific to this occurrence
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key