API Basics

This section covers the fundamental concepts for working with the Audian API v2.

Base URL

All API requests use:

https://api.audian.com:8443/v2/

Authentication

After authenticating with your API key, use the X-Auth-Token header:

curl -X GET "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users" \
  -H "X-Auth-Token: {AUTH_TOKEN}" \
  -H "Accept: application/json"

See Authentication for details on obtaining your auth token.

Request Format

Request Body Structure

All request bodies wrap data in a data object:

{
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}

Example: Create a User

curl -X PUT "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users" \
  -H "X-Auth-Token: {AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }
  }'

Response Format

Successful Response

{
  "auth_token": "eyJhbGciOiJSUzI1...",
  "data": {
    "id": "user_abc123",
    "first_name": "John",
    "last_name": "Doe"
  },
  "request_id": "req_xyz789",
  "revision": "automatic",
  "status": "success"
}

Error Response

{
  "auth_token": "eyJhbGciOiJSUzI1...",
  "data": {
    "message": "invalid credentials"
  },
  "error": "401",
  "message": "unauthorized",
  "request_id": "req_xyz789",
  "status": "error"
}

HTTP Methods

Method	Usage	Example
GET	Retrieve resources	GET /accounts/{id}/users
PUT	Create or replace	PUT /accounts/{id}/users
POST	Update existing	POST /accounts/{id}/users/{user_id}
PATCH	Partial update	PATCH /accounts/{id}/users/{user_id}
DELETE	Remove	DELETE /accounts/{id}/users/{user_id}

Account-Scoped Endpoints

Most endpoints are scoped to your account:

/v2/accounts/{ACCOUNT_ID}/users
/v2/accounts/{ACCOUNT_ID}/devices
/v2/accounts/{ACCOUNT_ID}/callflows

The account_id is returned when you authenticate.

Common Headers

Header	Value	Required
X-Auth-Token	Your auth token	Yes
Content-Type	application/json	Yes (for PUT/POST)
Accept	application/json	Recommended

Pagination

List endpoints support pagination:

# Get users without pagination (all results)
GET /v2/accounts/{ACCOUNT_ID}/users?paginate=false

# Get paginated results
GET /v2/accounts/{ACCOUNT_ID}/users?page_size=50

See Pagination for details.

Filtering

Filter results with query parameters:

# Filter users by first name
GET /v2/accounts/{ACCOUNT_ID}/users?filter_first_name=John

# Multiple filters
GET /v2/accounts/{ACCOUNT_ID}/devices?filter_device_type=sip_device&filter_enabled=true

See Filtering for details.

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Server Error

Topics

• Request Format - Detailed request structure
• Response Format - Response structure
• Pagination - Handling large result sets
• Filtering - Search and filter
• Sorting - Order results
• Versioning - API version info