8x8 Administration - Address Management API
8x8 Administration Address Management API for managing service and emergency addresses attached to sites and users.
OpenAPI Specification
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