Fax Status & History

Monitor fax delivery status, retrieve transmission history, and access detailed logs for sent and received faxes.

Endpoints

Get Fax Status

GET https://api.audian.com:8443/v2/fax/{faxId}/status

List Fax History

GET https://api.audian.com:8443/v2/fax/history

Get Fax Details

GET https://api.audian.com:8443/v2/fax/{faxId}

Get Fax Status

Check the current status of a sent fax.

Request

curl -X GET https://api.audian.com:8443/v2/fax/fax_abc123def456/status \
  -H "X-Auth-Token: YOUR_API_KEY"

Examples

JavaScript/Node.js

const axios = require('axios');

const getFaxStatus = async (faxId) => {
  try {
    const response = await axios.get(
      `https://api.audian.com:8443/v2/fax/${faxId}/status`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    console.log('Fax status:', response.data);
    return response.data;
  } catch (error) {
    console.error('Failed to get status:', error);
  }
};

// Usage
const status = await getFaxStatus('fax_abc123def456');
console.log(`Fax status: ${status.status}`);

Python

import requests

def get_fax_status(api_key, fax_id):
    url = f'https://api.audian.com:8443/v2/fax/{fax_id}/status'
    headers = {
        'X-Auth-Token': api_key
    }
    
    response = requests.get(url, headers=headers)
    return response.json()

# Usage
status = get_fax_status('YOUR_API_KEY', 'fax_abc123def456')
print(f"Status: {status['status']}")

Monitor Fax Delivery

const monitorFaxDelivery = async (faxId, maxWaitTime = 300000) => {
  const startTime = Date.now();
  
  while (Date.now() - startTime < maxWaitTime) {
    const status = await getFaxStatus(faxId);
    
    if (status.status === 'sent') {
      console.log('Fax delivered successfully!');
      return status;
    }
    
    if (status.status === 'failed') {
      console.error('Fax delivery failed:', status.error);
      return status;
    }
    
    // Wait 5 seconds before checking again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
  
  console.log('Monitoring timeout - fax still in progress');
};

Response Format

Status Response (200)

{
  "id": "fax_abc123def456",
  "to": "+12025551234",
  "status": "sent",
  "pages": 3,
  "pages_sent": 3,
  "sender_name": "John Smith",
  "sender_number": "+12025559999",
  "subject": "Invoice #12345",
  "quality": "high",
  "attempts": 1,
  "max_attempts": 3,
  "sent_at": "2024-02-04T13:05:00Z",
  "completed_at": "2024-02-04T13:07:30Z",
  "duration": 150,
  "delivery_confirmation": "dcn_abc123",
  "error_code": null,
  "error_message": null,
  "created_at": "2024-02-04T13:00:00Z"
}

Fax Status Values

Status	Description
`pending`	Fax queued for transmission
`sending`	Transmission in progress
`sent`	Successfully delivered
`failed`	Transmission failed
`no_answer`	Recipient did not answer
`busy`	Recipient line busy
`invalid_number`	Invalid fax number

List Fax History

Retrieve history of sent and received faxes.

Request

curl -X GET "https://api.audian.com:8443/v2/fax/history?limit=50&offset=0&status=sent" \
  -H "X-Auth-Token: YOUR_API_KEY"

Parameters

Parameter	Type	Description
`limit`	Number	Results per page (default: 20, max: 100)
`offset`	Number	Pagination offset
`status`	String	Filter by status
`from_date`	ISO8601	Start date for history
`to_date`	ISO8601	End date for history
`type`	String	Filter by type (sent, received)
`to_number`	String	Filter by recipient number
`from_number`	String	Filter by sender number

Examples

Get Sent Faxes from Last 7 Days

curl -X GET "https://api.audian.com:8443/v2/fax/history?type=sent&from_date=2024-01-28T00:00:00Z&limit=100" \
  -H "X-Auth-Token: YOUR_API_KEY"

JavaScript/Node.js

const listFaxHistory = async (filters = {}) => {
  try {
    const response = await axios.get(
      'https://api.audian.com:8443/v2/fax/history',
      {
        params: {
          limit: filters.limit || 50,
          offset: filters.offset || 0,
          status: filters.status,
          type: filters.type,
          from_date: filters.from_date,
          to_date: filters.to_date
        },
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    return response.data;
  } catch (error) {
    console.error('Failed to get history:', error);
  }
};

// Usage
const history = await listFaxHistory({
  type: 'sent',
  status: 'sent',
  limit: 50
});
console.log(`Found ${history.total} sent faxes`);

Python

import requests
from datetime import datetime, timedelta

def list_fax_history(api_key, fax_type='sent', days=7, limit=50):
    url = 'https://api.audian.com:8443/v2/fax/history'
    headers = {
        'X-Auth-Token': api_key
    }
    
    from_date = (datetime.now() - timedelta(days=days)).isoformat()
    
    params = {
        'type': fax_type,
        'from_date': from_date,
        'limit': limit,
        'offset': 0
    }
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Usage
history = list_fax_history('YOUR_API_KEY', fax_type='sent', days=7)
print(f"Total faxes: {history['total']}")

Response Format

History Response (200)

{
  "faxes": [
    {
      "id": "fax_abc123def456",
      "to": "+12025551234",
      "from": "+12025559999",
      "type": "sent",
      "status": "sent",
      "pages": 3,
      "subject": "Invoice #12345",
      "sent_at": "2024-02-04T13:05:00Z",
      "completed_at": "2024-02-04T13:07:30Z",
      "duration": 150
    },
    {
      "id": "fax_received_789",
      "from": "+14155552345",
      "to": "+12025551234",
      "type": "received",
      "status": "received",
      "pages": 5,
      "received_at": "2024-02-04T12:45:00Z",
      "duration": 180
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Get Full Fax Details

Retrieve comprehensive information about a specific fax.

curl -X GET https://api.audian.com:8443/v2/fax/fax_abc123def456 \
  -H "X-Auth-Token: YOUR_API_KEY"

Response

{
  "id": "fax_abc123def456",
  "to": "+12025551234",
  "from": "+12025559999",
  "type": "sent",
  "status": "sent",
  "pages": 3,
  "pages_sent": 3,
  "sender_name": "John Smith",
  "subject": "Invoice #12345",
  "quality": "high",
  "file_size": 245000,
  "attempts": 1,
  "max_attempts": 3,
  "started_at": "2024-02-04T13:00:00Z",
  "sent_at": "2024-02-04T13:05:00Z",
  "completed_at": "2024-02-04T13:07:30Z",
  "duration": 150,
  "baud_rate": 14400,
  "ecm_enabled": true,
  "error_code": null,
  "error_message": null,
  "created_at": "2024-02-04T13:00:00Z",
  "updated_at": "2024-02-04T13:07:30Z"
}

Error Codes

Code	Description	Recovery
`no_answer`	Recipient did not answer	Retry later
`busy`	Line was busy	Automatic retry
`invalid_number`	Number format invalid	Verify number
`no_fax_detected`	No fax machine detected	Wrong number type
`timeout`	Connection timeout	Retry later
`line_error`	Line transmission error	Retry later

Analytics and Reporting

Get Fax Statistics

const getFaxStats = async (startDate, endDate) => {
  const history = await listFaxHistory({
    type: 'sent',
    from_date: startDate,
    to_date: endDate,
    limit: 1000
  });
  
  const stats = {
    total_sent: 0,
    successful: 0,
    failed: 0,
    total_pages: 0,
    total_duration: 0
  };
  
  for (const fax of history.faxes) {
    stats.total_sent++;
    stats.total_pages += fax.pages;
    stats.total_duration += fax.duration || 0;
    
    if (fax.status === 'sent') {
      stats.successful++;
    } else {
      stats.failed++;
    }
  }
  
  stats.success_rate = (stats.successful / stats.total_sent * 100).toFixed(2) + '%';
  stats.avg_duration = Math.round(stats.total_duration / stats.total_sent) + 's';
  
  return stats;
};

Delivery Confirmation

Faxes include delivery confirmation (DCN) when available:

{
  "id": "fax_abc123def456",
  "status": "sent",
  "delivery_confirmation": {
    "dcn": "dcn_abc123",
    "confirmed_at": "2024-02-04T13:07:30Z",
    "recipient_id": "rec_123",
    "confirmed_pages": 3
  }
}

Best Practices

Status Polling: Poll status at 5-second intervals maximum
Monitoring: Set reasonable timeout limits (5-10 minutes)
Logging: Log all fax transactions for compliance
Alerting: Set up alerts for failed transmissions
Archival: Archive important fax IDs and confirmations
Cleanup: Remove old fax records based on policy

Limits and Quotas

Status check rate: 10 requests per second per fax
History query limit: 1000 per request
Retention period: Based on your plan
Query date range: Up to 1 year
Concurrent status checks: Unlimited

Endpoints​

Get Fax Status​

List Fax History​

Get Fax Details​

Get Fax Status​

Request​

Examples​

JavaScript/Node.js​

Python​

Monitor Fax Delivery​

Response Format​

Status Response (200)​

Fax Status Values​

List Fax History​

Request​

Parameters​

Examples​

Get Sent Faxes from Last 7 Days​

JavaScript/Node.js​

Python​

Response Format​

History Response (200)​

Get Full Fax Details​

Response​

Error Codes​

Analytics and Reporting​

Get Fax Statistics​

Delivery Confirmation​

Best Practices​

Limits and Quotas​

Endpoints

Get Fax Status

List Fax History

Get Fax Details

Get Fax Status

Request

Examples

JavaScript/Node.js

Python

Monitor Fax Delivery

Response Format

Status Response (200)

Fax Status Values

List Fax History

Request

Parameters

Examples

Get Sent Faxes from Last 7 Days

JavaScript/Node.js

Python

Response Format

History Response (200)

Get Full Fax Details

Response

Error Codes

Analytics and Reporting

Get Fax Statistics

Delivery Confirmation

Best Practices

Limits and Quotas