Skip to main content

Retrieve User

Retrieve details about a specific user.

Endpoint​

GET https://api.audian.com:8443/v2/accounts/{accountId}/users/{userId}

Request​

Path Parameters​

ParameterTypeRequiredDescription
accountIdstringYesAccount ID
userIdstringYesUser ID

Headers​

X-Auth-Token: YOUR_API_TOKEN

Query Parameters​

ParameterTypeDescription
includeDevicesbooleanInclude assigned devices
includePermissionsbooleanInclude user permissions
includePresencebooleanInclude current presence status
includeActivitybooleanInclude recent activity

Examples​

Retrieve Basic User Info​

curl -X GET https://api.audian.com:8443/v2/accounts/acc_1234567890/users/user_123456 \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Retrieve with All Details​

curl -X GET "https://api.audian.com:8443/v2/accounts/acc_1234567890/users/user_123456?includeDevices=true&includePermissions=true&includePresence=true" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

JavaScript/Node.js Example​

const axios = require('axios');

async function getUser(accountId, userId) {
  try {
    const response = await axios.get(
      `https://api.audian.com:8443/v2/accounts/${accountId}/users/${userId}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN'
        },
        params: {
          includeDevices: true,
          includePermissions: true,
          includePresence: true
        }
      }
    );
    
    console.log('User details:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error retrieving user:', error.response.data);
  }
}

getUser('acc_1234567890', 'user_123456');

Python Example​

import requests

def get_user(account_id, user_id):
    url = f'https://api.audian.com:8443/v2/accounts/{account_id}/users/{user_id}'
    headers = {
        'Authorization': 'Bearer YOUR_API_TOKEN'
    }
    params = {
        'includeDevices': True,
        'includePermissions': True,
        'includePresence': True
    }
    
    response = requests.get(url, headers=headers, params=params)
    
    if response.status_code == 200:
        print('User details:', response.json())
        return response.json()
    else:
        print('Error:', response.json())

get_user('acc_1234567890', 'user_123456')

Response​

Success Response (200 OK)​

{
  "id": "user_123456",
  "accountId": "acc_1234567890",
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "alice.smith@acme.com",
  "username": "alice.smith",
  "extension": "1001",
  "phone": "+1-555-0101",
  "title": "Sales Executive",
  "department": "Sales",
  "manager": "user_manager_001",
  "role": "standard",
  "status": "active",
  "timezone": "America/New_York",
  "language": "en",
  "createdAt": "2023-10-15T10:30:00Z",
  "updatedAt": "2023-10-20T14:22:00Z",
  "lastLogin": "2023-10-20T09:15:00Z",
  "devices": [
    {
      "id": "dev_sip_123456",
      "name": "Desk Phone - Alice Smith",
      "type": "sip",
      "status": "active",
      "registrationStatus": "registered"
    },
    {
      "id": "dev_softphone_123456",
      "name": "Desktop Softphone",
      "type": "softphone",
      "status": "active"
    }
  ],
  "permissions": [
    "calls.make",
    "calls.receive",
    "voicemail.access",
    "contacts.manage"
  ],
  "presence": {
    "status": "available",
    "message": "In office",
    "lastUpdate": "2023-10-20T14:15:00Z"
  },
  "settings": {
    "callWaiting": true,
    "callForwarding": {
      "enabled": false,
      "destination": null
    },
    "voicemail": {
      "enabled": true,
      "greetingType": "default"
    }
  }
}

Error Response (404 Not Found)​

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User does not exist",
    "details": {
      "userId": "user_123456"
    }
  }
}

Status Codes​

CodeDescription
200User retrieved successfully
400Bad request
401Unauthorized - invalid token
403Forbidden - no access to this user
404User not found
429Too many requests
500Server error

Response Fields​

User Object​

  • id: Unique user identifier
  • accountId: Parent account ID
  • firstName: User first name
  • lastName: User last name
  • email: Email address
  • username: Login username
  • extension: Phone extension
  • phone: Contact phone number
  • title: Job title
  • department: Department name
  • manager: Manager user ID
  • role: User role
  • status: User status (active, disabled, suspended)
  • timezone: User timezone
  • language: Preferred language
  • createdAt: ISO 8601 timestamp
  • updatedAt: ISO 8601 timestamp
  • lastLogin: Last login timestamp

Devices (optional)​

Array of assigned devices with:

  • id: Device ID
  • name: Device name
  • type: Device type
  • status: Device status
  • registrationStatus: SIP registration status

Permissions (optional)​

Array of permission strings:

  • calls.make - Make outbound calls
  • calls.receive - Receive inbound calls
  • calls.transfer - Transfer calls
  • calls.conference - Create conferences
  • voicemail.access - Access voicemail
  • recordings.access - Access call recordings
  • contacts.manage - Manage contacts
  • presence.view - View presence
  • admin.users - Manage users
  • admin.account - Manage account

Presence (optional)​

  • status: Available, busy, away, offline
  • message: Custom status message
  • lastUpdate: Last status change

Settings (optional)​

  • callWaiting: Call waiting enabled
  • callForwarding: Call forwarding configuration
  • voicemail: Voicemail settings
  • dnd: Do Not Disturb settings

List Users​

To retrieve all users in an account:

curl -X GET "https://api.audian.com:8443/v2/accounts/acc_1234567890/users?status=active&limit=50&offset=0" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Retrieve by Email​

Get user by email address:

curl -X GET "https://api.audian.com:8443/v2/accounts/acc_1234567890/users/by-email/alice.smith@acme.com" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Retrieve by Extension​

Get user by extension:

curl -X GET "https://api.audian.com:8443/v2/accounts/acc_1234567890/users/by-extension/1001" \
  -H "X-Auth-Token: YOUR_API_TOKEN"