Fax API

REST API v2 — send faxes programmatically to the US and Canada

1. Overview

The GotFreeFax REST API v2 lets you send faxes to the United States and Canada from any programming language using standard JSON over HTTPS. Use it to integrate fax sending into web apps, back-office workflows, or scheduled jobs.

Base URL: https://www.gotfreefax.com

API access is available to GotFreeFax.com prepaid account holders.

2. Authentication

All authenticated endpoints use Bearer token authentication. The token is your account number and PIN encoded in Base64.

Creating Your Token

Combine your account number and PIN with a colon separator, then Base64-encode the result:

Token = base64("ACCOUNT_NUMBER:PIN")

Example:
  Account Number: 1234567890
  PIN: 5678
  Combined: 1234567890:5678
  Base64 Token: MTIzNDU2Nzg5MDo1Njc4

Using the Token

Include the token in the Authorization header of every request:

Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4

Code Examples

# Python
import base64
token = base64.b64encode(b"1234567890:5678").decode()
headers = {"Authorization": f"Bearer {token}"}

# JavaScript
const token = btoa("1234567890:5678");
headers: { "Authorization": `Bearer ${token}` }

# C#
var token = Convert.ToBase64String(Encoding.UTF8.GetBytes("1234567890:5678"));
request.Headers.Add("Authorization", "Bearer " + token);

# cURL
curl -H "Authorization: Bearer $(echo -n '1234567890:5678' | base64)"

Response Envelope

All endpoints return JSON with this envelope:

// Success
{
  "success": true,
  "data": { ... },
  "error": null
}

// Error
{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

3. Send a Fax

Send a fax with one or more file attachments.

Request Body

Field	Type	Required	Description
fax_number	string	Yes	10-digit US or Canada fax number
notify_url	string	No	URL to POST fax status notification
files	array	Yes	Array of file objects
files[].filename	string	Yes	Filename with extension (e.g. letter.pdf)
files[].content	string	Yes	Base64-encoded file content

Example Request

curl -X POST https://www.gotfreefax.com/api/v2/fax \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4" \
  -H "Content-Type: application/json" \
  -d '{
    "fax_number": "8885551234",
    "notify_url": "https://example.com/fax-callback",
    "files": [
      {
        "filename": "document.pdf",
        "content": "JVBERi0xLjQK..."
      }
    ]
  }'

Example Response

{
  "success": true,
  "data": {
    "job_id": "ABCDEFGHIJ"
  },
  "error": null
}

4. Check Fax Status

Check the delivery status of a sent fax.

Path Parameters

Parameter	Description
job_id	The job ID returned by the Send Fax endpoint

Example Request

curl https://www.gotfreefax.com/api/v2/fax/ABCDEFGHIJ \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4"

Example Response

{
  "success": true,
  "data": {
    "job_id": "ABCDEFGHIJ",
    "fax_number": "8885551234",
    "status": "success",
    "page_count": 2,
    "completed_at": "2025-01-15T10:30:00Z",
    "detail": ""
  },
  "error": null
}

Status Values

Status	Description
pending	Fax is queued or in progress
success	Fax delivered successfully
failure	Fax failed or was cancelled

5. Account Balance

Example Request

curl https://www.gotfreefax.com/api/v2/account/balance \
  -H "Authorization: Bearer MTIzNDU2Nzg5MDo1Njc4"

Example Response

{
  "success": true,
  "data": {
    "page_balance": 50,
    "amount_balance": 12.50
  },
  "error": null
}

6. Supported Formats Endpoint

Example Request

curl https://www.gotfreefax.com/api/v2/formats

Example Response

{
  "success": true,
  "data": {
    "formats": [
      { "description": "Adobe PDF", "extensions": ["pdf"] },
      { "description": "Microsoft Word", "extensions": ["doc", "dot"] },
      { "description": "Microsoft Word 2007+", "extensions": ["docx"] },
      ...
    ]
  },
  "error": null
}

7. Error Codes

HTTP Status	Code	Description
401	UNAUTHORIZED	Missing or invalid authentication token
400	INVALID_FAX_NUMBER	Fax number is not a valid 10-digit US/Canada number
400	INVALID_FILES	Missing files or invalid file data
400	INVALID_BASE64	File content is not valid base64
400	INVALID_JSON	Request body is not valid JSON
400	INVALID_JOB_ID	Job ID is missing or empty
400	UNSUPPORTED_FORMAT	File type is not supported (allowed: PDF, DOC, DOCX, JPG, JPEG, TXT)
400	TOO_MANY_FILES	Exceeded maximum of 10 files per fax
402	INSUFFICIENT_BALANCE	Account has no page credits remaining
404	NOT_FOUND	Fax job not found
500	SYSTEM_ERROR	Internal server error

8. Supported File Formats & Limits

Maximum 10 files per fax request.

Format	Extensions
Adobe PDF	pdf
Microsoft Word	doc, docx
JPEG Image	jpg, jpeg
Plain Text	txt

---

Need help? Contact us at gotfreefax.com/contact.