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