8x8 Administration - Site Management API
8x8 Administration Site Management API for creating and managing sites within an 8x8 tenant.
OpenAPI Specification
openapi: 3.0.0
info:
title: 8x8 Administration - Site Management API
version: "1.0"
description: |
Site management API providing endpoints to create, retrieve, list, update, and delete sites. Sites represent physical or logical locations within an organization where users and devices are deployed.
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 `PUT`) and in the `Accept` header for requests that return a payload (`GET`, and asynchronous `DELETE` operations that return an operation resource).
```
Content-Type: application/vnd.sites.v1+json # on POST/PUT (request payload)
Accept: application/vnd.sites.v1+json # on GET (response payload)
```
## Base URL
`https://api.8x8.com/admin-provisioning`
## Endpoints
| Endpoint | Method | Purpose | Async? |
|----------|--------|---------|--------|
| `/sites` | GET | Retrieve paginated list of sites with filtering | No |
| `/sites` | POST | Create a new site | Yes |
| `/sites/{siteId}` | GET | Retrieve a specific site's details | No |
| `/sites/{siteId}` | PUT | Update an existing site | Yes |
| `/sites/{siteId}` | DELETE | Remove a site | Yes |
## OpenAPI Specification
Download the complete OpenAPI specification: [site-api-v1.yaml](/administration/site-api-v1.yaml)
servers:
- url: https://api.8x8.com/admin-provisioning
description: Production server
security:
- ApiKeyAuth: []
paths:
/sites:
post:
operationId: createSite
summary: Create a new site
description: Creates a new site. Returns an Operation object that can be polled to track the creation progress.
tags:
- Sites
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
requestBody:
description: Site object to be created
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
example:
name: "Headquarters"
pbxName: "pbx01"
locale: "en-US"
timezone: "America/Los_Angeles"
siteCode: "1345"
extensionLength: 4
address:
id: "b1c4944a-17a0-4b00-8d48-36001df07e22"
responses:
'202':
description: Site creation operation initiated successfully
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
example:
operationId: "op_123456789"
status: "PENDING"
customerId: "0012J00042NkZQIQA3"
resourceType: "SITE"
resourceId: "0023OEZiR7qQ_EGb6xYjgg"
operationType: "CREATE"
createdTime: "2025-01-01T01:02:03Z"
'400':
description: Bad Request - Invalid site data
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 400
title: "Bad Request"
errors:
- code: "BAD_REQUEST"
message: "Invalid site data"
'403':
description: Forbidden - Access denied to this resource
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'408':
description: Request Timeout - Downstream service timeout
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 408
title: "Request Timeout"
errors:
- code: "REQUEST_TIMEOUT"
message: "Request to downstream service timed out"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'429':
description: Too Many Requests - Rate limit exceeded
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 429
title: "Too Many Requests"
errors:
- code: "TOO_MANY_REQUESTS"
message: "Rate limit exceeded, please try again later"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
get:
operationId: listSites
summary: List sites
description: |
List sites with optional filtering, sorting, and pagination.
Filter by site name using RSQL expressions with wildcards.
tags:
- Sites
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: pageNumber
in: query
description: 'Page number (0-indexed, default: 0)'
required: false
schema:
type: integer
example: 0
- name: filter
in: query
description: |
Filter expression using RSQL syntax. Only filtering by 'name' field is supported.
Supports exact match and wildcard patterns.
Examples:
- Exact match: name==Headquarters
- Wildcard at end: name==Office*
- Wildcard at start: name==*Office
- Wildcard at both ends: name==*Branch*
Only the '==' operator is supported. Logical operations (AND/OR) are not supported.
required: false
schema:
type: string
example: "name==Office*"
- name: sort
in: query
description: "Sort expression. Use '+' prefix or no prefix for ascending order, '-' prefix for descending order (e.g., 'name', '+name', or '-name')"
required: false
schema:
type: string
example: "name"
responses:
'200':
description: Successful response with paginated sites
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/SitePage'
example:
data:
- id: "0023OEZiR7qQ_EGb6xYjgg"
name: "Headquarters"
pbxName: "pbx01"
locale: "en-US"
timezone: "America/Los_Angeles"
siteCode: "1345"
extensionLength: 4
address:
id: "b1c4944a-17a0-4b00-8d48-36001df07e22"
pagination:
pageSize: 100
pageNumber: 0
hasMore: false
'400':
description: Bad Request - Invalid filter or query parameters
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidFilterFormat:
summary: Invalid filter format
value:
status: 400
title: "Invalid filter format"
errors:
- code: "VALIDATION_ERROR"
message: "Invalid filter syntax"
invalidOperator:
summary: Invalid operator
value:
status: 400
title: "Invalid filter format"
errors:
- code: "VALIDATION_ERROR"
message: "Invalid operator: !=. Only '==' operator is supported"
unsupportedField:
summary: Unsupported field
value:
status: 400
title: "Invalid filter format"
errors:
- code: "VALIDATION_ERROR"
message: "Invalid filter field: id. Only filtering by name is supported"
logicalOperations:
summary: Logical operations not supported
value:
status: 400
title: "Invalid filter format"
errors:
- code: "VALIDATION_ERROR"
message: "Logical operations (AND/OR) are not supported"
wildcardPosition:
summary: Invalid wildcard position
value:
status: 400
title: "Invalid filter format"
errors:
- code: "VALIDATION_ERROR"
message: "Wildcard (*) can only appear at the beginning or end"
'403':
description: Forbidden - Access denied to this resource
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'408':
description: Request Timeout - Downstream service timeout
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 408
title: "Request Timeout"
errors:
- code: "REQUEST_TIMEOUT"
message: "Request to downstream service timed out"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'429':
description: Too Many Requests - Rate limit exceeded
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 429
title: "Too Many Requests"
errors:
- code: "TOO_MANY_REQUESTS"
message: "Rate limit exceeded, please try again later"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Error searching sites in Voice-Config"
errors:
- code: "UNKNOWN"
message: "Error searching sites in Voice-Config"
/sites/{siteId}:
get:
operationId: getSite
summary: Get site by ID
description: Retrieve a specific site by its ID
tags:
- Sites
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: siteId
in: path
description: Site identifier
required: true
schema:
type: string
example: "0023OEZiR7qQ_EGb6xYjgg"
responses:
'200':
description: Site retrieved successfully
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
example:
id: "0023OEZiR7qQ_EGb6xYjgg"
name: "Headquarters"
pbxName: "pbx01"
locale: "en-US"
timezone: "America/Los_Angeles"
siteCode: "1345"
extensionLength: 4
address:
id: "b1c4944a-17a0-4b00-8d48-36001df07e22"
callerIdSettings:
mainNumber: "+12266280120"
setMainNumberAsCallerId: true
shareMainNumberAsCallerId: false
displayName: "John Doe"
'400':
description: Bad Request - Invalid request
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 400
title: "Bad Request"
errors:
- code: "BAD_REQUEST"
message: "Invalid site ID format"
'403':
description: Forbidden - Access denied to this resource
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'404':
description: Not Found - Site does not exist
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Not Found"
errors:
- code: "NOT_FOUND"
message: "Site not found"
'408':
description: Request Timeout - Downstream service timeout
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 408
title: "Request Timeout"
errors:
- code: "REQUEST_TIMEOUT"
message: "Request to downstream service timed out"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'429':
description: Too Many Requests - Rate limit exceeded
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 429
title: "Too Many Requests"
errors:
- code: "TOO_MANY_REQUESTS"
message: "Rate limit exceeded, please try again later"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Error retrieving site from Voice-Config"
errors:
- code: "UNKNOWN"
message: "Error retrieving site from Voice-Config"
put:
operationId: updateSite
summary: Update site
description: Updates an existing site. Returns an Operation object that can be polled to track the update progress.
tags:
- Sites
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: siteId
in: path
description: Site identifier
required: true
schema:
type: string
example: "0023OEZiR7qQ_EGb6xYjgg"
requestBody:
description: Site object with updated fields
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
example:
name: "Headquarters Updated"
pbxName: "pbx01"
locale: "en-US"
timezone: "America/Los_Angeles"
siteCode: "1345"
extensionLength: 4
address:
id: "b1c4944a-17a0-4b00-8d48-36001df07e22"
responses:
'202':
description: Site update operation initiated successfully
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
example:
operationId: "op_123456789"
status: "PENDING"
customerId: "0012J00042NkZQIQA3"
resourceType: "SITE"
resourceId: "0023OEZiR7qQ_EGb6xYjgg"
operationType: "UPDATE"
createdTime: "2025-01-01T01:02:03Z"
'400':
description: Bad Request - Invalid site data
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 400
title: "Bad Request"
errors:
- code: "BAD_REQUEST"
message: "Invalid site data"
'403':
description: Forbidden - Access denied to this resource
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'404':
description: Not Found - Site does not exist
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Not Found"
errors:
- code: "NOT_FOUND"
message: "Site not found"
'408':
description: Request Timeout - Downstream service timeout
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 408
title: "Request Timeout"
errors:
- code: "REQUEST_TIMEOUT"
message: "Request to downstream service timed out"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'429':
description: Too Many Requests - Rate limit exceeded
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 429
title: "Too Many Requests"
errors:
- code: "TOO_MANY_REQUESTS"
message: "Rate limit exceeded, please try again later"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 500
title: "Internal Server Error"
errors:
- code: "UNKNOWN"
message: "An unexpected error occurred"
delete:
operationId: deleteSite
summary: Delete site
description: Deletes an existing site. Returns an Operation object that can be polled to track the deletion progress.
tags:
- Sites
parameters:
- name: X-Request-Id
in: header
description: Optional request identifier for tracking
required: false
schema:
type: string
format: uuid
- name: siteId
in: path
description: Site identifier
required: true
schema:
type: string
example: "0023OEZiR7qQ_EGb6xYjgg"
responses:
'202':
description: Site deletion operation initiated successfully
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/Operation'
example:
operationId: "op_123456789"
status: "PENDING"
customerId: "0012J00042NkZQIQA3"
resourceType: "SITE"
resourceId: "0023OEZiR7qQ_EGb6xYjgg"
operationType: "DELETE"
createdTime: "2025-01-01T01:02:03Z"
'400':
description: Bad Request - Site cannot be removed
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 400
title: "Bad Request"
errors:
- code: "BAD_REQUEST"
message: "Branch with id 0023OEZiR7qQ_EGb6xYjgg can not be removed. It is used by at least one extension"
'403':
description: Forbidden - Access denied to this resource
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 403
title: "Forbidden"
errors:
- code: "FORBIDDEN"
message: "Access denied to this resource"
'404':
description: Not Found - Site does not exist
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 404
title: "Not Found"
errors:
- code: "NOT_FOUND"
message: "Site not found"
'408':
description: Request Timeout - Downstream service timeout
headers:
X-Response-Id:
description: Unique response identifier generated by the service
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 408
title: "Request Timeout"
errors:
- code: "REQUEST_TIMEOUT"
message: "Request to downstream service timed out"
'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/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: 503
title: "Service unavailable"
errors:
- code: "SERVICE_UNAVAILABLE"
message: "Service unavailable"
'429':
description: Too Many
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-administration-site-api-v1.yaml