etherFAX REST API

etherFAX REST API Developer Hub

Welcome to the etherFAX REST API developer hub. You'll find comprehensive guides and documentation to help you start working with etherFAX REST API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started
Suggest Edits

Introduction

A web-based API for sending, receiving, and managing fax and document delivery through the etherFAX network.

 

The etherFAX API is a web interface based on REST semantics using simple HTTP GET/POST web operations compatible with many operating systems and programming languages. This interface is provided to all application and fax server partners that wish to integrate fax delivery into their applications and services.

This web API provides access to simple resource controllers. At this time, supported controllers are Accounts, Outbox, Status, Inbox, and Routes. Each resource supports optional parameters within the URI scheme and provides responses in various data formats (JSON, XML, etc.) and simple HTTP status codes.

Web Service Base URL

All requests referenced in this document use the following base URL:

https://na.connect.etherfax.net/rest/3.0/api

If a simple GET is performed on the root API, the following text will be returned with the remote client's IP address displayed.

etherFAX REST Services 3.0
Your client address is: 150.76.16.64
Copyright © 2008-2018, etherFAX, LLC

Supported Request Formats

The etherFAX REST API observes the Content-Type value in the HTTP header when performing POST operations (i.e. sending a fax). Supported Content-Type values are:

  • application/x-www-form-urlencoded
  • application/json

Supported Response Formats

The etherFAX REST API will provide responses in JSON format by default but may be overridden in the URI parameter list.

  • application/json
  • application/xml

The optional &f parameter may be used to explicitly request JSON or XML responses from the etherFAX web service. If omitted, all responses will be returned in the JSON format.

Date and Time Formats

All date/time values are represented in UTC represented using the RFC3339 format.

Here are some examples of Internet date/time format.

2017-04-12T23:20:50.52

This represents 20 minutes and 50.52 seconds after the 23rd hour of April 12th, 2017 in UTC.

Suggest Edits

Authentication

This section describes the authentication mechanisms supported by the etherFAX REST API.

 

Authentication

The etherFAX REST web service supports the Basic HTTP authorization model using an account/password or an api-key provided by the etherFAX administration portal.

Each client must use the etherFAX account number, username, and password provided by etherFAX personnel. When authenticating against the REST web services, you must make sure all GET/POST operations have correctly added the Authorization header to HTTP request using Basic authentication.

The Authorization field is constructed as follows:

The account and username are combined with a forward slash (/), followed by a colon (:) and then the password. This means that the username itself cannot contain a colon. The character set to use for this encoding is by default unspecified, as long as it is compatible with US-ASCII or UTF-8.

Example:

    Account = efax-0000-0000
    User = appservice
    Password = ixlr8

The strings are combined and then base64 encoded:

Combined string:

    efax-0000-0000/appservice:ixlr8

String octets base64 encoded:

    ZWZheC0wMDAwLTAwMDAvYXBwc2VydmljZTppeGxyOA==

Add the following Authorization header to your HTTP request.

Authorization: Basic ZWZheC0wMDAwLTAwMDAvYXBpc2VydmljZTppeGxyOA==

Alternatively, an api-key may be used in lieu of the account/password method described above using the Bearer authentication scheme.

Authorization: Bearer your_api_key
Suggest Edits

/accounts

This resource is used to query information from the current account, features that are enabled, supported file formats and other information.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/accounts
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/accounts
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/accounts' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/accounts");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/accounts"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "Account": "EFAX-9999-9999",
  "Name": "Pearson Medical",
  "AccountId": 101,
  "Ports": 4,
  "Enabled": true,
  "Features": [
    "FaxResume",
    "NoRedialAttempts",
    "InternationalDialing",
    "InactiveCallRejection"
  ],
  "AcceptedFormats": [
    "application/pdf",
    "image/tiff"
  ],
  "Numbers": 38,
  "Devices": 8,
  "Country": 1,
  "CreatedOn": "2009-08-11T00:42:55.38"
}
 
Suggest Edits

/accounts/pkinfo

Sets the public key for this account.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://na.connect.etherfax.net/rest/3.0/api/accounts/pkinfo
curl --request POST \
  --url https://na.connect.etherfax.net/rest/3.0/api/accounts/pkinfo
var request = require("request");

var options = { method: 'POST',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/accounts/pkinfo' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/accounts/pkinfo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://na.connect.etherfax.net/rest/3.0/api/accounts/pkinfo");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/accounts/pkinfo"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Form Data

PublicKey
string

This field contains the base64 encoded contents of the public key file (in PEM format) associated with the account.

 

Removing a Public Key

To remove a public key from an account, simply set the PublicKey parameter in the body to null.

{
  PublicKey: null
}
Suggest Edits

/outbox

This resource is used to send faxes through the etherFAX network to a destination fax number (or etherFAX endpoint).

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://na.connect.etherfax.net/rest/3.0/api/outbox
curl --request POST \
  --url https://na.connect.etherfax.net/rest/3.0/api/outbox
var request = require("request");

var options = { method: 'POST',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/outbox' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/outbox")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://na.connect.etherfax.net/rest/3.0/api/outbox");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/outbox"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "JobId": "aa52f281-44dd-45bf-a586-d12d127dd733",
  "FaxResult": 2,
  "State": 0,
  "PagesDelivered": 0,
  "ConnectTime": 0,
  "ConnectSpeed": 0,
  "RemoteId": null,
  "Tag": null,
  "CompletedOn": null
}

Form Data

DialNumber
string

Specifies the number to be dialed. This may be a long distance human readable number or E.164 (+18005551234) format.

LocalId
string

(Optional) Sets the fax id (CSID) for the send request. This is the fax CSID displayed by the remote fax system. This field supports up to 21 characters.

CallerId
string

(Optional) Sets the caller id for this send request. Where possible, this number will appear as the calling party/id to the remote system. For maximum effectiveness within carrier networks, a "toll" DID is highly recommended.

TotalPages
int32

Specifies the total number of pages in the fax image file.

TimeZoneOffset
string

Specifies the time zone offset of the originator. This value is used to maintain the local time of the originator in the fax header (i.e. -5 for Eastern Standard Time).

Tag
string

Tag (Optional) Sets a user defined string associated with the fax request. This string will appear in FaxStatus responses making it easier for applications to track their fax messages. This field supports up to 64 characters.

FaxImage
string

Contains the base64 encoded string representing the binary image data (tiff, pdf or other supported document format).

Header
string

Specifies the header format string displayed at the top of each page of this fax job. Keywords and examples are shown below.

TZ
string

Specifies the time zone offset of the originator and functions similar to TimeZoneOffset. However, this parameter also supports Linux style time zones such as "America/Chicago", "America/New_York", etc. Using this parameter overrides the TimeZoneOffset value (if specified) and automatically adjusts for daylight savings for the time zone.

 

The following parameters are supported when performing a POST operation to the outbox controller. If you are using the urlencoded form of this function (Content-Type: application/x-www-form-urlencoded), each parameter must be URL encoded in the post data associated with the HTTP request.

Remarks

After the POST operation, the etherFAX service will respond with an abbreviated FaxStatus response indicating whether the fax operation was successfully submitted to the etherFAX network. A FaxResult lt value of InProgress indicates that that the fax has been accepted and a unique identifier has been assigned to the event. All events within the etherFAX network have globally unique identifiers assigned for their lifetime. These are also known as GUIDs.

All fax images presented for transmission should conform to the TIFF-F minimum baseline (see TIFF specification). For best results, only submit fax images that are bi-tonal (black & white), have a standard fax width of 1728 pixels and are roughly 200x200 (fine) or 200x100 (coarse) dots per inch (resolution).

etherFAX also supports PDF and SENx (encrypted) documents.

Note, each etherFAX account is configured with a maximum number of ports (channels) to limit the number of outbound fax operations. If the number of active channels exceeds this configuration, the fax event will be rejected with a FaxResult value of ChannelUnavailable.

  • See FaxResult section for explanation of the FaxResult values.

Header Strings: Feb 1, 2017

The use of this feature requires a patch to the etherFAX network that has not been completed. We will update this site when the Header string and the option to disable it are available for use.

Header Strings

The header parameter supports the following keywords and optional formatting:

Keyword Description
{date} Shows current date adjusted to account's local time zone.
{date:format} Shows current date adjusted to account's local time zone with optional formatting.
{time} Shows current time adjusted to account's local time zone.
{time:format} Shows current time adjusted to account's local time zone with optional formatting.
{utcdate} Shows the current date in UTC.
{utcdate:format} Shows the current date in UTC with optional formatting.
{utctime} Shows the current time in UTC
{utctime:format} Shows the current time in UTC with optional formatting.
{csid}
{from}
Shows the sender CSID's (Call Subscriber Identification) information.
{number}
{to}
Shows the destination fax number.
{page} Shows the current page number.
{pages} Shows the current page number and total pages in fax. This is equivalent to using: "{page} / {total}"
{total} Shows the total page count.

Default header used by etherFAX:

Example:

"  {date}  {time}   FROM: {csid}  TO: {number}   P. {page}"

Output:

"  05/06/2014  08:46 AM   FROM: etherFAX, LLC  TO: +18005551234    P. 1"

Example using date formatting:

Example:

"  {date:d-MMM-yyyy}  {time}   FROM: {csid}  TO: {number}   P. {page}"

Output:

"  6-May-2014  08:46 AM   FROM: etherFAX, LLC  TO: +18005551234    P. 1"

Note: It is best to leave 2 spaces at the beginning of the header string to avoid the header starting too close to the left edge of the page.

Suggest Edits

/outbox (pending)

Returns the number of active/pending events in the outbox for the given account, including the number of channels available for sending.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/outbox
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/outbox
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/outbox' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/outbox")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/outbox");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/outbox"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "PendingFaxes": 0,
  "AvailableChannels": 4
}

Query Params

a
string

Action to perform.

 
Suggest Edits

/inbox (unread)

Returns the number of unread fax events for the given account. When using the unread action, you may optionally provide the wait timeout value to wait for a new fax.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/inbox
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/inbox
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/inbox' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/inbox")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/inbox");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/inbox"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "UnreadFaxes": 0
}

Query Params

a
string

Action to perform.

wait
int32

Specifies the timeout in seconds to wait for a new fax to arrive. This wait method is only valid when using the unread action. When waiting, the function will return immediately if unread faxes are available for download or a new fax has arrived during the wait period.

 

Example: Get unread fax count with wait timeout

The following example queries the number of unread faxes available. If no unread faxes are available at the time this function is called, it will wait up to 120 seconds for a new fax to arrive. If a new fax arrives during the wait/timeout period, this function will return immediately allowing the application to retrieve the new fax the instant it arrives within the etherFAX network.

[GET] https://na.connect.etherfax.net/rest/3.0/api/inbox?a=unread&wait=120
Suggest Edits

/inbox (list)

Returns a list of unread faxes for the given account. All faxes are returned as FaxReceive child nodes in the response. The optional {count} value may be specified to limit the number of unread faxes returned in the list. Setting this value to 0 (or omitted) returns all unread faxes. This function only returns the information associated with the received fax and not the actual fax image data.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/inbox
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/inbox
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/inbox' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/inbox")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/inbox");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/inbox"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[
  {
    "JobId": "833fd712-2ca2-4c7b-8b26-8166629963de",
    "FaxResult": 0,
    "ConnectTime": 56,
    "ConnectSpeed": 33600,
    "PagesReceived": 2,
    "RemoteId": "9085551234",
    "CalledNumber": "+18005551234",
    "CallingNumber": "2125551234",
    "ReceivedOn": "2015-10-27T21:47:37.92",
    "FaxImage": null
  },
  {
    "JobId": "c12e1f95-77e7-4471-a456-508e43daa9a9",
    "FaxResult": 0,
    "ConnectTime": 68,
    "ConnectSpeed": 33600,
    "PagesReceived": 3,
    "RemoteId": "9085551234",
    "CalledNumber": "+18005551234",
    "CallingNumber": "2125551234",
    "ReceivedOn": "2015-10-27T21:47:43.14",
    "FaxImage": null
  }
]

Query Params

a
string

Action to perform.

count
int32

(Optional) Limits the returned results to the count specified.

 
Suggest Edits

/inbox (get)

Gets/downloads the FaxReceive information for the specified fax {id}. All information including the FaxImage content is returned using this method.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/inbox
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/inbox
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/inbox' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/inbox")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/inbox");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/inbox"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "JobId": "833fd712-2ca2-4c7b-8b26-8166629963de",
  "FaxResult": 0,
  "ConnectTime": 56,
  "ConnectSpeed": 33600,
  "PagesReceived": 2,
  "RemoteId": "9085551234",
  "CalledNumber": "+18005551234",
  "CallingNumber": "2125551234",
  "ReceivedOn": "2015-10-27T21:47:37.92",
  "FaxImage": null
}

Query Params

a
string

Action to perform.

id
string

Specifies the {id} of the <FaxReceive> object to retrieve.

download
int32

The download option allows the client to specify whether to include the FaxImage content when retrieving the received fax.

 
Suggest Edits

/inbox (getnext)

Gets and optionally downloads the next unread fax (if one is available) and returns the FaxReceive information. The {download} parameter may be set to 1 or 0 when using this function. This function is designed for multi-process environments that attempt to receive a fax using the same account. To resolve contention, only one peer may gain access to an unread fax at a time. If the peer fails to download the fax and mark it as received within a 5-minute window, the automatic lock on the fax is released and another peer may download the unread fax. Additionally, the peer may also set the {sid} parameter which is a GUID representing the site-id. etherFAX will record the site id responsible for downloading the fax document.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/inbox?a=getnext
curl --request GET \
  --url 'https://na.connect.etherfax.net/rest/3.0/api/inbox?a=getnext'
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/inbox',
  qs: { a: 'getnext' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/inbox?a=getnext")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/inbox?a=getnext");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/inbox"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "JobId": "833fd712-2ca2-4c7b-8b26-8166629963de",
  "FaxResult": 0,
  "ConnectTime": 56,
  "ConnectSpeed": 33600,
  "PagesReceived": 2,
  "RemoteId": "9085551234",
  "CalledNumber": "+18005551234",
  "CallingNumber": "2125551234",
  "ReceivedOn": "2015-10-27T21:47:37.92",
  "FaxImage": null
}

Query Params

a
string

Action to perform.

download
int32

(Optional) Indicates whether the FaxImage content should be downloaded in the response.

 
Suggest Edits

/inbox (received)

Marks the specified fax {id} as "received" indicating that it has been successfully read or delivered. Once an application has guaranteed that it has received the fax intact, it should mark the fax as received, thus permanently removing the fax image resource.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/inbox
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/inbox
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/inbox' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/inbox")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/inbox");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/inbox"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

a
string

Action to perform.

id
string

Specifies the unique job id to mark as read.

res
string

(Optional) The receiver (for SEN transactions only) can optionally set the final result code for the sending fax. This value may contain the numeric value or string of the FaxResult result code.

 
Suggest Edits

/status

This resource is used to monitor the status of one or more fax events using their unique identifier (GUID).

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/status
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/status
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/status' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/status");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/status"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "JobId": "ba93e53b-70b9-433d-a84b-0000013437e6",
  "FaxResult": 0,
  "State": 0,
  "PagesDelivered": 1,
  "ConnectTime": 41,
  "ConnectSpeed": 14400,
  "RemoteId": "9085551234",
  "Tag": "ID12345",
  "CompletedOn": "2015-04-28T00:35:23.113"
}

Query Params

id
string

Specifies one or more unique job identifiers (GUID) separated by commas.

timeout
string

Specifies the number of seconds for the wait timeout. The wait timeout has 2 uses:

- Wait for an event to transpire for the specified job id (send complete, in-job status, etc.).
- Wait for account wide events to occur (new job received, send completed, etc.).

type
string

Specifies the type of events to monitor when the wait timeout has been specified. Valid values are: receive, send, status and any.

receive - wait for receive event (account wide)
send - wait for send event (id or account wide)
status - wait for send job status (id or account wide)
any - any of the above conditions

 
Suggest Edits

/reports (metrics)

Returns account call metrics for the specified date range.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/reports?a=metrics
curl --request GET \
  --url 'https://na.connect.etherfax.net/rest/3.0/api/reports?a=metrics'
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/reports',
  qs: { a: 'metrics' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/reports?a=metrics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/reports?a=metrics");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/reports"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[
  {
    "FaxResult": 0,
    "Description": "Success",
    "Count": 909,
    "Percent": "95.18"
  },
  {
    "FaxResult": 3,
    "Description": "LineBusy",
    "Count": 4,
    "Percent": "0.42"
  },
  {
    "FaxResult": 7,
    "Description": "NoAnswer",
    "Count": 1,
    "Percent": "0.1"
  },
  {
    "FaxResult": 8,
    "Description": "InvalidOrMissingNumber",
    "Count": 20,
    "Percent": "2.09"
  },
  {
    "FaxResult": 11,
    "Description": "UnexpectedDisconnect",
    "Count": 2,
    "Percent": "0.21"
  },
  {
    "FaxResult": 106,
    "Description": "DecryptFailure",
    "Count": 4,
    "Percent": "0.42"
  },
]

Query Params

a
string
date
string

Specifies the date period or range for this request.

 

The date query parameter may contain a date qualifier or an actual time range.

Parameter
Description

h

Specifies the number of hours from the current time.

w

Weeks.

m

Months.

d

Days.

y

Years.

Examples:

Last Month:

.../reports?a=metrics&date=1m

Last 30 days:

.../reports?a=metrics&date=30d

Last 12 hours:

.../reports?a=metrics&date=12h

January 1, 2018 through March 1, 2018:

.../reports?a=metrics&date=2018-01-01,2018-03-01
Suggest Edits

/reports (send)

Returns send call detail records for the specified date range.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/reports?a=send
curl --request GET \
  --url 'https://na.connect.etherfax.net/rest/3.0/api/reports?a=send'
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/reports',
  qs: { a: 'send' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/reports?a=send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/reports?a=send");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/reports"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Query Params

a
string
date
string

Specifies the date period or range for this request.

 

The use of the date parameter is further described in the report metrics section.

Suggest Edits

/reports (receive)

Returns receive call detail records for the specified date range.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/reports?a=receive
curl --request GET \
  --url 'https://na.connect.etherfax.net/rest/3.0/api/reports?a=receive'
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/reports',
  qs: { a: 'receive' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/reports?a=receive")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/reports?a=receive");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/reports"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Query Params

a
string

Use the receive action to query a list of received call detail records.

date
string

Specifies the date period or range for this request.

 

The use of the date parameter is further described in the report metrics section.

Suggest Edits

/routes (info)

Retrieves information and supported file formats for the specified number in {id}.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/routes
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/routes
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/routes' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/routes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/routes");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/routes"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "Route": "+18562955300",
  "AcceptedFormats": [
    "image/tiff"
  ],
  "Resolutions": [
    "204x98",
    "204x196",
    "300"
  ],
  "PageWidths": [
    "a4"
  ],
  "Encryption": {
    "Enabled": true,
    "Required": false,
    "PublicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlHYk1CQUdCeXFHU000OUFnRUdCU3VCQkFBakE0R0dBQVFCb2J3NUJQSC9ENUpleGpRcGpMN0dLbUdHZkc0MwpEYTZHU2hzbkVjNGh3VWVCNEVLUDZ3WjFoYlp3cHRBUjhqYmNxWTJ3YlAreExmT3FBR0RZUC9vMTBBTUI1M3kzCjRzaDA2azdzSzhVKzY1SUhZZ3B6WjR3WWw1emsrQTQ2ZkRQUVhoS3BEdlVnWjExcm9WYUpOYUROK0p3QjFZT1UKbllNTUwzY05QZUs0dS9lcnBHMD0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg=="
  },
  "Name": "Pearson Medical"
}

Query Params

a
string

Action to perform.

id
string

Specifies the route (phone number) to query.

 

Note: If a route is not found within the etherFAX network (or the Federation services), a 404 (not found) result will be returned.

Suggest Edits

/routes (list)

Lists all inbound numbers associated with the given account.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/routes
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/routes
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/routes' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/routes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/routes");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/routes"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

a
string

Action to perform.

 
Suggest Edits

/routes (parse)

Parses the specified number in {id} and returns information such as destination country, etc. The {country} parameter may be used to specify the country of origin. If omitted, country code assigned to the account will be used.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/routes
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/routes
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/routes' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/routes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/routes");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/routes"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "InternationalDialPrefix": "011",
  "Normalized": "8005551234",
  "Origin": "+1/United States/Canada",
  "E164": "+18005551234",
  "Destination": "+1/United States/Canada",
  "Route": "8005551234"
}

Query Params

a
string

Action to perform.

id
string

Specifies the route (phone number) to query.

country
int32

(Optional) Specifies the country code or origin.

 
Suggest Edits

/routes (enable | disable)

Enables or disables the route specified in {id}. Only numbers/routes owned by the account may be enabled/disabled using this function.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/routes
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/routes
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/routes' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/routes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/routes");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/routes"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Query Params

a
string

Action to perform (enable, disable).

id
string

Specifies the phone number or route/endpoint to analyze.

 
Suggest Edits

/devices (unread)

Returns the number of unread faxes waiting for the associated device. Since the default device is selected as part of the authentication request, the {id} parameter is not required. This function behaves similarly to the inbox controller, except an additional action value is provided in the response.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/devices
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/devices
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/devices");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "UnreadFaxes": 0
  "Action": 0
}

Query Params

a
string

Action to perform.

wait
int32

Specifies the timeout in seconds to wait for a new fax to arrive. This wait method is only valid when using the unread action. When waiting, the function will return immediately if unread faxes are available for download or a new fax has arrived during the wait period.

 

Note: Devices return an extra element called Action and indicates which DeviceActions should be performed.

Example: Get unread fax count with wait timeout

The following example queries the number of unread faxes available. If no unread faxes are available at the time this function is called, it will wait up to 120 seconds for a new fax to arrive. If a new fax arrives during the wait/timeout period, this function will return immediately allowing the application to retrieve the new fax the instant it arrives within the etherFAX network.

[GET] https://na.connect.etherfax.net/rest/3.0/api/devices?a=unread&wait=120
Suggest Edits

/devices (list)

Returns a list of unread faxes associated with the specified device.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/devices
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/devices
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/devices");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[
  {
    "JobId": "833fd712-2ca2-4c7b-8b26-8166629963de",
    "FaxResult": 0,
    "ConnectTime": 56,
    "ConnectSpeed": 33600,
    "PagesReceived": 2,
    "RemoteId": "9085551234",
    "CalledNumber": "+18005551234",
    "CallingNumber": "2125551234",
    "ReceivedOn": "2015-10-27T21:47:37.92",
    "FaxImage": null
  },
  {
    "JobId": "c12e1f95-77e7-4471-a456-508e43daa9a9",
    "FaxResult": 0,
    "ConnectTime": 68,
    "ConnectSpeed": 33600,
    "PagesReceived": 3,
    "RemoteId": "9085551234",
    "CalledNumber": "+18005551234",
    "CallingNumber": "2125551234",
    "ReceivedOn": "2015-10-27T21:47:43.14",
    "FaxImage": null
  }
]

Query Params

a
string

Action to perform.

 
Suggest Edits

/devices (status)

Queries the status of the device and returns all properties and settings associated with the authenticated device.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/devices
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/devices
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/devices");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "SerialNumber": "MT873615726",
  "Enabled": true,
  "SendEnable": true,
  "ReceiveEnable": true,
  "Reporting": 0,
  "SkipLines": 45,
  "LocalId": null,
  "CallerId": null,
  "PrinterIp": "192.168.1.100",
  "DeviceFlags": 3,
  "CreatedOn": "2016-09-19T17:15:38.707",
  "RegisteredOn": "2016-12-29T14:18:56.443",
  "TimeZone": "America/New_York"
}

Query Params

a
string

Query the device status.

 
Suggest Edits

/devices (actionreset)

Though the device's action is implicitly reset when the "unread" action is invoked, the remote client may explicitly call this function to clear the action state of the device.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/devices
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/devices
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/devices");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Query Params

a
string

Action to perform.

 
Suggest Edits

/devices (setaddr)

Allows the remote client to set the local IP address of the device. This function serves no other purposes than to report the current IP address of the device that may be viewed within the etherFAX administrative portal.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/devices
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/devices
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/devices");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Query Params

a
string

Action to perform.

addr
string

The string representation of the device's local IP address.

 
Suggest Edits

/devices (setconfig)

Allows the remote client to set certain configuration features of the device or quickly enable/disable others.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://na.connect.etherfax.net/rest/3.0/api/devices
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/devices
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/devices");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  Encryption: true
}

Query Params

a
string

Action to perform.

options
string

When using the setconfig action, the options parameter contains one or more options (or features) you wish to change, including the specified value.

 

The following options values are supported:

Option Description
addr Sets the local IP address of the device for easier identification in the etherFAX portal.
encryption Sets the Encryption Enabled flag. This flag is returned to callers that query route information to determine if a destination has encryption enabled.
required Sets the Encryption Required flag (also returned in route information).

Examples:

.../?a=setconfig&options=encryption:1

.../?a=setconfig&options=addr:192.168.1.32

Multiple options may be set at once for convenience:

...?a=setconfig&options=encryption:1,required:0

Encryption element when performing route query:

{
  "Route": "+18562955300",
  "Encryption": {
    "Enabled": true,
    "Required": false,
    "PublicKey": "..."
  }
}
Suggest Edits

/devices (register)

Performs a device registration to the etherFAX network and returns a security token used for subsequent authentication. Until a device has been created/enabled within the etherFAX network, this function cannot be completed successfully. Devices already registered within the system may not be re-registered until reset within the etherFAX administration portal.

 
gethttps://na.connect.etherfax.net/rest/3.0/api/devices
curl --request GET \
  --url https://na.connect.etherfax.net/rest/3.0/api/devices
var request = require("request");

var options = { method: 'GET',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/devices' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/devices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://na.connect.etherfax.net/rest/3.0/api/devices");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/devices"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "DeviceToken": "54524a6421f1ddaf6781c79f9e176cfc"
}

Query Params

a
string

Action to perform.

id
string

Specifies the serial number of the device performing the registration. This serial number must exist in the etherFAX portal and bound to a valid etherFAX account.

token
string

Unique registration token created by the device for validation against the etherFAX network.

profile
string

(Optional) The profile parameter allows the registering device to specify a device profile. If specified, the profile will be automatically associated with the device in the etherFAX Portal. Device profiles specify capabilities such as supported document types, resolutions, and page sizes.

 

Registering A Device

Before a device can operate within the etherFAX network, it must be created as a customer device and enabled for operation. To begin the registration process, each device must have the current date/time set correctly and create a registration URI following these steps.

In this example, our device serial number is: MT873615726.

Step 1: Create initial MD5 hash using the serial number as input.

Result: 3239f210aefade4a5de84cd018d18b44

Step 2: Create a temporary string using current date/time and initial hash.

"YYYY:mm:hash.DDD"

Where YYYY = year since 1900, MM = current month (0..11), hash (lower case) and DDD is the current day of the year (0..365).

Example: Feb 2, 2017

"0117:01:3239f210aefade4a5de84cd018d18b44.032"

Step 3: Perform final MD5 hash of temporary string.

Result: 414d6d04931da79f6d9925e0c30b85a3

Example:

[GET] https://na.connect.etherfax.net/rest/2.0/api/devices?a=register&id=MT873615726&token=414d6d04931da79f6d9925e0c30b85a3

Response:

{
  "DeviceToken": "54524a6421f1ddaf6781c79f9e176cfc"
}

On success, an HTTP 200/OK response and device security token will be returned. If the device is not enabled or has been previously registered, an HTTP 403/Forbidden is issued.

Once a DeviceToken has been created, the device may authenticate against the etherFAX REST using the same basic authorization semantics. However, the account must be replaced with the literal string of "device/" followed by the device serial number. The password is the DeviceToken returned from the register action. After the device security token is issued, it is the device's responsibility to persist the security token for later use.

Suggest Edits

/devices/pkinfo

Sets the public key for the current device.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://na.connect.etherfax.net/rest/3.0/api/devices/pkinfo
curl --request POST \
  --url https://na.connect.etherfax.net/rest/3.0/api/devices/pkinfo
var request = require("request");

var options = { method: 'POST',
  url: 'https://na.connect.etherfax.net/rest/3.0/api/devices/pkinfo' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://na.connect.etherfax.net/rest/3.0/api/devices/pkinfo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://na.connect.etherfax.net/rest/3.0/api/devices/pkinfo");

xhr.send(data);
import requests

url = "https://na.connect.etherfax.net/rest/3.0/api/devices/pkinfo"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Form Data

PublicKey
string

This field contains the base64 encoded contents of the public key file (in PEM format) associated with the device.

 

Removing a Public Key

To remove a public key from a device, simply set the PublicKey parameter in the body to null.

{
  PublicKey: null
}
Suggest Edits

DeviceActions

Though most of the following actions are reserved for embedded device platforms (such as the etherFAX A2E), device developers should at least support UpdateConfig as a baseline requirement. This allows all devices to be remotely managed from the etherFAX administration portal.

 
/// <summary>
/// DeviceAction values.
/// </summary>
public enum DeviceAction
{
    UpdateConfig = 1,
    Ping,
    Reboot,
    Unregister,
    UpdateFirmware,
    UploadLogs
}
Suggest Edits

FaxAccount

Fax account structure.

 
/// <summary>
/// FaxAccount class.
/// </summary>
public class FaxAccount
{
    public string Account { get; set; }
    public int AccountId { get; set; }
    public int Country { get; set; }
    public string Name { get; set; }
    public bool Enabled { get; set; }
    public int Ports { get; set; }
    public int Numbers { get; set; }
    public string[] Features { get; set; }
}
Suggest Edits

FaxDevice

Fax device configuration structure.

 
/// <summary>
/// FaxDevice Configuration Information
/// </summary>
public class FaxDevice
{
    public int DeviceId { get; set; }
    public string SerialNumber { get; set; }
    public bool Enabled { get; set; }
    public bool SendEnable { get; set; }
    public bool ReceiveEnable { get; set; }
    public int Reporting { get; set; }
    public int SkipLines { get; set; }
    public string LocalId { get; set; }
    public string CallerId { get; set; }
    public string PrinterIp { get; set; }
    public int DeviceType { get; set; }
    public int DeviceGroup { get; set; }
    public int DeviceFlags { get; set; }
    public DateTime? CreatedOn { get; set; }
    public DateTime? RegisteredOn { get; set; }
    public string TimeZone { get; set; }
}
Suggest Edits

FaxReceive

Fax receive structure.

 
/// <summary>
/// FaxReceive class.
/// </summary>
public class FaxReceive
{
    public FaxResult FaxResult { get; set; }
    public Guid JobId { get; set; }
    public string CalledNumber { get; set; }
    public string CallingNumber { get; set; }
    public string RemoteId { get; set; }
    public int PagesReceived { get; set; }
    public int ConnectTime { get; set; }
    public int ConnectSpeed { get; set; }
    public DateTime ReceivedOn { get; set; }
    public byte[] FaxImage { get; set; }
}
Suggest Edits

FaxResult

The following constants are used to describe the various fax results (disposition) and states of transmission.

 
/// <summary>
/// FaxResult values.
/// </summary>
public enum EtherFaxResult
{
    Success = 0,
    Error,
    InProgress,
    LineBusy,
    LineDead,
    LineFailure,
    NoDialTone,
    NoAnswer,
    InvalidOrMissingNumber,
    InvalidOrMissingFile,
    InvalidChannel,
    UnexpectedDisconnect,
    NoChannelsAvailable,
    ChannelUnavailable,
    NothingToCancel,
    DeviceTimeout,
    DeviceBusy,
    NotFaxMachine,
    IncompatibleFaxMachine,
    FileError,
    FileNotFound,
    FileUnsupported,
    CallCollision,
    Cancelled,
    CallBlocked,
    DestinationBlackListed,
    RemoteDisconnect,
    NegotiationError,
    TrainingError,

    Unauthorized = 100,
    InvalidParameter,
    NotImplemented,
    ItemNotFound,
    EncryptionDisabled,
    EncryptionRequired,
    DecryptFailure,
    DocumentRejected,
    DocumentNotSupported,
    DocumentTooLarge
}
Suggest Edits

FaxSend

Fax send parameters used when sending a fax to the etherFAX network.

 
/// <summary>
/// FaxSend class.
/// </summary>
public class FaxSend
{
    public string DialNumber { get; set; }
    public string LocalId { get; set; }
    public string CallerId { get; set; }
    public int TotalPages { get; set; }
    public int TimeZoneOffset { get; set; }
    public int Priority { get; set; }
    public string Tag { get; set; }
    public byte[] FaxImage { get; set; }
    public string TZ { get; set; }
    public string HeaderString { get; set; }
    public int Options { get; set; }
}
Suggest Edits

FaxSendOptions

Fax send options used when sending a fax to the etherFAX network.

 
/// <summary>
/// FaxSendOptions values.
/// </summary>
[Flags]
public enum FaxSendOptions
{
    NoFaxHeader = 1,
    NativeDocument = 2,
    Encrypted = 4
}
Suggest Edits

FaxState

Fax states indicate the state of the fax event.

 
/// <summary>
/// FaxState values.
/// </summary>
public enum FaxState
{
    Idle = 0,
    Initializing,
    Dialing,
    Answering,
    Negotiating,
    Sending,
    Receiving,
    Cancelling,
    Disconnecting,
    Conversion
}
Suggest Edits

FaxStatus

Fax status structure.

 
/// <summary>
/// FaxStatus class.
/// </summary>
public class FaxStatus
{
    public FaxResult FaxResult { get; set; }
    public FaxState State { get; set; }
    public Guid JobId { get; set; }
    public int PagesDelivered { get; set; }
    public int ConnectTime { get; set; }
    public int ConnectSpeed { get; set; }
    public string RemoteId { get; set; }
    public string Tag { get; set; }
    public DateTime? CompletedOn { get; set; }
    public DateTime? DeliveredOn { get; set; }
}
Suggest Edits

PendingFaxResult

Pending faxes and available channels response.

 
/// <summary>
/// PendingFaxResult
/// </summary>
public class PendingFaxResult
{
    public int PendingFaxes { get; set; }
    public int AvailableChannels { get; set; }
}
Suggest Edits

RouteInfo (EncryptionParams)

Fax route information structure with encryption options.

 
/// <summary>
/// Encryption settings.
/// </summary>
public class EncryptionParams
{
    public bool Enabled { get; set; }
    public bool Required { get; set; }
    public byte[] PublicKey { get; set; }
}

/// <summary>
/// Routeinfo class (used for lookup).
/// </summary>
public class RouteInfo
{
    public string Route { get; set; }
    public string[] AcceptedFormats { get; set; }
    public string[] Resolutions { get; set; }
    public string[] PageWidths { get; set; }
    public EncryptionParams Encryption { get; set; }
    public string Name { get; set; }
}
Suggest Edits

UnreadFaxResult

Unread fax result response.

 
/// <summary>
/// UnreadFaxResult
/// </summary>
public class UnreadFaxResult
{
    public int UnreadFaxes { get; set; }
}