Programmable Fax Applications

Fax Applications operations

List all Fax Applications

This endpoint returns a list of your Fax Applications inside the 'data' attribute of the response. You can adjust which applications are listed by using filters. Fax Applications are used to configure how you send and receive faxes using the Programmable Fax API with Telnyx.

SecuritybearerAuth
Request
query Parameters
page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

filter[application_name][contains]
string
Default: "null"

If present, applications with application_name containing the given value will be returned. Matching is not case-sensitive. Requires at least three characters.

filter[outbound_voice_profile_id]
string <int64>

Identifies the associated outbound voice profile.

Example: filter[outbound_voice_profile_id]=1293384261075731499
sort
string
Default: "created_at"

Specifies the sort order for results. By default sorting direction is ascending. To have the results sorted in descending order add the - prefix.

That is:

  • connection_name: sorts the result by the connection_name field in ascending order.

  • -connection_name: sorts the result by the connection_name field in descending order.

If not given, results are sorted by created_at in descending order.
Enum: "created_at" "connection_name" "active"
Example: sort=connection_name
Responses
200

Successful response

Response Schema: application/json
Array of objects (Fax Application)
object (PaginationMeta)
400

Bad request

401

Unauthorized

404

Resource not found

get/fax_applications
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

try {
  const { data } = await telnyx.faxApplications.list({"page[number]":1,"page[size]":20});
} catch (error) {
  console.error(error);
}
Response samples
application/json
{
  • "data": [
    • {
      • "id": "1293384261075731499",
      • "record_type": "fax_application",
      • "application_name": "fax-router",
      • "active": false,
      • "anchorsite_override": "Amsterdam, Netherlands",
      • "webhook_event_url": "https://example.com",
      • "webhook_event_failover_url": "https://failover.example.com",
      • "webhook_timeout_secs": 25,
      • "inbound": {
        • "channel_limit": 10,
        • "sip_subdomain": "example",
        • "sip_subdomain_receive_settings": "only_my_connections"
        },
      • "outbound": {
        • "channel_limit": 10,
        • "outbound_voice_profile_id": "1293384261075731499"
        },
      • "created_at": "2018-02-02T22:25:27.521Z",
      • "updated_at": "2018-02-02T22:25:27.521Z"
      }
    ],
  • "meta": {
    • "total_pages": 3,
    • "total_results": 55,
    • "page_number": 2,
    • "page_size": 25
    }
}

Creates a Fax Application

Creates a new Fax Application based on the parameters sent in the request. The application name and webhook URL are required. Once created, you can assign phone numbers to your application using the /phone_numbers endpoint.

SecuritybearerAuth
Request
Request Body schema: application/json
required

Parameters that can be set when creating a Fax Application

application_name
required
string (Application Name)

A user-assigned name to help manage the application.

active
boolean (Connection Active)
Default: true

Specifies whether the connection can be used.

anchorsite_override
string (Anchorsite Override)
Default: "Latency"

Latency directs Telnyx to route media through the site with the lowest round-trip time to the user's connection. Telnyx calculates this time using ICMP ping messages. This can be disabled by specifying a site to handle all media.

Enum: "Latency" "Chicago, IL" "Ashburn, VA" "San Jose, CA" "Sydney, Australia" "Amsterdam, Netherlands" "London, UK" "Toronto, Canada" "Vancouver, Canada" "Frankfurt, Germany"
webhook_event_url
required
string <url> (Webhook Event URL)

The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'.

webhook_event_failover_url
string or null <url> (Webhook Event Failover URL)
Default: ""

The failover URL where webhooks related to this connection will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.

webhook_timeout_secs
integer or null (Webhook Timeout Secs) [ 0 .. 30 ]
Default: null

Specifies how many seconds to wait before timing out a webhook.

object
object
Responses
201

Successful response

Response Schema: application/json
object (Fax Application)
id
string <int64> (Int ID)

Uniquely identifies the resource.

record_type
string

Identifies the type of the resource.

application_name
string (Application Name)

A user-assigned name to help manage the application.

active
boolean (Connection Active)
Default: true

Specifies whether the connection can be used.

anchorsite_override
string (Anchorsite Override)
Default: "Latency"

Latency directs Telnyx to route media through the site with the lowest round-trip time to the user's connection. Telnyx calculates this time using ICMP ping messages. This can be disabled by specifying a site to handle all media.

Enum: "Latency" "Chicago, IL" "Ashburn, VA" "San Jose, CA" "Sydney, Australia" "Amsterdam, Netherlands" "London, UK" "Toronto, Canada" "Vancouver, Canada" "Frankfurt, Germany"
webhook_event_url
string <url> (Webhook Event URL)

The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'.

webhook_event_failover_url
string or null <url> (Webhook Event Failover URL)
Default: ""

The failover URL where webhooks related to this connection will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.

webhook_timeout_secs
integer or null (Webhook Timeout Secs) [ 0 .. 30 ]
Default: null

Specifies how many seconds to wait before timing out a webhook.

object
object
created_at
string

ISO 8601 formatted date indicating when the resource was created.

updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

422

Bad request

post/fax_applications
Request samples
application/json
{
  • "application_name": "fax-router",
  • "active": false,
  • "anchorsite_override": "Amsterdam, Netherlands",
  • "webhook_event_url": "https://example.com",
  • "webhook_event_failover_url": "https://failover.example.com",
  • "webhook_timeout_secs": 25,
  • "inbound": {
    • "channel_limit": 10,
    • "sip_subdomain": "example",
    • "sip_subdomain_receive_settings": "only_my_connections"
    },
  • "outbound": {
    • "channel_limit": 10,
    • "outbound_voice_profile_id": "1293384261075731499"
    }
}
Response samples
application/json
{
  • "data": {
    • "id": "1293384261075731499",
    • "record_type": "fax_application",
    • "application_name": "fax-router",
    • "active": false,
    • "anchorsite_override": "Amsterdam, Netherlands",
    • "webhook_event_url": "https://example.com",
    • "webhook_event_failover_url": "https://failover.example.com",
    • "webhook_timeout_secs": 25,
    • "inbound": {
      • "channel_limit": 10,
      • "sip_subdomain": "example",
      • "sip_subdomain_receive_settings": "only_my_connections"
      },
    • "outbound": {
      • "channel_limit": 10,
      • "outbound_voice_profile_id": "1293384261075731499"
      },
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}

Deletes a Fax Application

Permanently deletes a Fax Application. Deletion may be prevented if the application is in use by phone numbers.

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Responses
200

Successful response

Response Schema: application/json
object (Fax Application)
id
string <int64> (Int ID)

Uniquely identifies the resource.

record_type
string

Identifies the type of the resource.

application_name
string (Application Name)

A user-assigned name to help manage the application.

active
boolean (Connection Active)
Default: true

Specifies whether the connection can be used.

anchorsite_override
string (Anchorsite Override)
Default: "Latency"

Latency directs Telnyx to route media through the site with the lowest round-trip time to the user's connection. Telnyx calculates this time using ICMP ping messages. This can be disabled by specifying a site to handle all media.

Enum: "Latency" "Chicago, IL" "Ashburn, VA" "San Jose, CA" "Sydney, Australia" "Amsterdam, Netherlands" "London, UK" "Toronto, Canada" "Vancouver, Canada" "Frankfurt, Germany"
webhook_event_url
string <url> (Webhook Event URL)

The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'.

webhook_event_failover_url
string or null <url> (Webhook Event Failover URL)
Default: ""

The failover URL where webhooks related to this connection will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.

webhook_timeout_secs
integer or null (Webhook Timeout Secs) [ 0 .. 30 ]
Default: null

Specifies how many seconds to wait before timing out a webhook.

object
object
created_at
string

ISO 8601 formatted date indicating when the resource was created.

updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

401

Unauthorized

404

Resource not found

422

Bad request

delete/fax_applications/{id}
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data: faxApplications } = await telnyx.faxApplications.retrieve(id);
await faxApplications.del();
Response samples
application/json
{
  • "data": {
    • "id": "1293384261075731499",
    • "record_type": "fax_application",
    • "application_name": "fax-router",
    • "active": false,
    • "anchorsite_override": "Amsterdam, Netherlands",
    • "webhook_event_url": "https://example.com",
    • "webhook_event_failover_url": "https://failover.example.com",
    • "webhook_timeout_secs": 25,
    • "inbound": {
      • "channel_limit": 10,
      • "sip_subdomain": "example",
      • "sip_subdomain_receive_settings": "only_my_connections"
      },
    • "outbound": {
      • "channel_limit": 10,
      • "outbound_voice_profile_id": "1293384261075731499"
      },
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}

Retrieve a Fax Application

Return the details of an existing Fax Application inside the 'data' attribute of the response.

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Responses
200

Successful response

Response Schema: application/json
object (Fax Application)
id
string <int64> (Int ID)

Uniquely identifies the resource.

record_type
string

Identifies the type of the resource.

application_name
string (Application Name)

A user-assigned name to help manage the application.

active
boolean (Connection Active)
Default: true

Specifies whether the connection can be used.

anchorsite_override
string (Anchorsite Override)
Default: "Latency"

Latency directs Telnyx to route media through the site with the lowest round-trip time to the user's connection. Telnyx calculates this time using ICMP ping messages. This can be disabled by specifying a site to handle all media.

Enum: "Latency" "Chicago, IL" "Ashburn, VA" "San Jose, CA" "Sydney, Australia" "Amsterdam, Netherlands" "London, UK" "Toronto, Canada" "Vancouver, Canada" "Frankfurt, Germany"
webhook_event_url
string <url> (Webhook Event URL)

The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'.

webhook_event_failover_url
string or null <url> (Webhook Event Failover URL)
Default: ""

The failover URL where webhooks related to this connection will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.

webhook_timeout_secs
integer or null (Webhook Timeout Secs) [ 0 .. 30 ]
Default: null

Specifies how many seconds to wait before timing out a webhook.

object
object
created_at
string

ISO 8601 formatted date indicating when the resource was created.

updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

401

Unauthorized

404

Resource not found

422

Bad request

get/fax_applications/{id}
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

// In Node 10
const { data } = await telnyx.faxApplications.list({
  "page[number]":1,
  "page[size]":20
});

// In other environments
telnyx.faxApplications.list({
  "page[number]":1,
  "page[size]":20
}).then(function(response){
  const faxApplication = response.data; // asynchronously handled
});
Response samples
application/json
{
  • "data": {
    • "id": "1293384261075731499",
    • "record_type": "fax_application",
    • "application_name": "fax-router",
    • "active": false,
    • "anchorsite_override": "Amsterdam, Netherlands",
    • "webhook_event_url": "https://example.com",
    • "webhook_event_failover_url": "https://failover.example.com",
    • "webhook_timeout_secs": 25,
    • "inbound": {
      • "channel_limit": 10,
      • "sip_subdomain": "example",
      • "sip_subdomain_receive_settings": "only_my_connections"
      },
    • "outbound": {
      • "channel_limit": 10,
      • "outbound_voice_profile_id": "1293384261075731499"
      },
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}

Update a Fax Application

Updates settings of an existing Fax Application based on the parameters of the request.

SecuritybearerAuth
Request
path Parameters
id
required
string <int64>

Identifies the resource.

Example: 1293384261075731499
Request Body schema: application/json
required

Parameters to be updated for the Fax Application

application_name
required
string (Application Name)

A user-assigned name to help manage the application.

active
boolean (Connection Active)
Default: true

Specifies whether the connection can be used.

anchorsite_override
string (Anchorsite Override)
Default: "Latency"

Latency directs Telnyx to route media through the site with the lowest round-trip time to the user's connection. Telnyx calculates this time using ICMP ping messages. This can be disabled by specifying a site to handle all media.

Enum: "Latency" "Chicago, IL" "Ashburn, VA" "San Jose, CA" "Sydney, Australia" "Amsterdam, Netherlands" "London, UK" "Toronto, Canada" "Vancouver, Canada" "Frankfurt, Germany"
webhook_event_url
required
string <url> (Webhook Event URL)

The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'.

webhook_event_failover_url
string or null <url> (Webhook Event Failover URL)
Default: ""

The failover URL where webhooks related to this connection will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.

webhook_timeout_secs
integer or null (Webhook Timeout Secs) [ 0 .. 30 ]
Default: null

Specifies how many seconds to wait before timing out a webhook.

fax_email_recipient
string or null <email> (Fax Email Recipient)
Default: null

Specifies an email address where faxes sent to this application will be forwarded to (as pdf or tiff attachments)

object
object
Responses
200

Successful response

Response Schema: application/json
object (Fax Application)
id
string <int64> (Int ID)

Uniquely identifies the resource.

record_type
string

Identifies the type of the resource.

application_name
string (Application Name)

A user-assigned name to help manage the application.

active
boolean (Connection Active)
Default: true

Specifies whether the connection can be used.

anchorsite_override
string (Anchorsite Override)
Default: "Latency"

Latency directs Telnyx to route media through the site with the lowest round-trip time to the user's connection. Telnyx calculates this time using ICMP ping messages. This can be disabled by specifying a site to handle all media.

Enum: "Latency" "Chicago, IL" "Ashburn, VA" "San Jose, CA" "Sydney, Australia" "Amsterdam, Netherlands" "London, UK" "Toronto, Canada" "Vancouver, Canada" "Frankfurt, Germany"
webhook_event_url
string <url> (Webhook Event URL)

The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'.

webhook_event_failover_url
string or null <url> (Webhook Event Failover URL)
Default: ""

The failover URL where webhooks related to this connection will be sent if sending to the primary URL fails. Must include a scheme, such as 'https'.

webhook_timeout_secs
integer or null (Webhook Timeout Secs) [ 0 .. 30 ]
Default: null

Specifies how many seconds to wait before timing out a webhook.

object
object
created_at
string

ISO 8601 formatted date indicating when the resource was created.

updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

401

Unauthorized

404

Resource not found

422

Bad request

patch/fax_applications/{id}
Request samples
application/json
{
  • "application_name": "fax-router",
  • "active": false,
  • "anchorsite_override": "Amsterdam, Netherlands",
  • "webhook_event_url": "https://example.com",
  • "webhook_event_failover_url": "https://failover.example.com",
  • "webhook_timeout_secs": 25,
  • "inbound": {
    • "channel_limit": 10,
    • "sip_subdomain": "example",
    • "sip_subdomain_receive_settings": "only_my_connections"
    },
  • "outbound": {
    • "channel_limit": 10,
    • "outbound_voice_profile_id": "1293384261075731499"
    }
}
Response samples
application/json
{
  • "data": {
    • "id": "1293384261075731499",
    • "record_type": "fax_application",
    • "application_name": "fax-router",
    • "active": false,
    • "anchorsite_override": "Amsterdam, Netherlands",
    • "webhook_event_url": "https://example.com",
    • "webhook_event_failover_url": "https://failover.example.com",
    • "webhook_timeout_secs": 25,
    • "inbound": {
      • "channel_limit": 10,
      • "sip_subdomain": "example",
      • "sip_subdomain_receive_settings": "only_my_connections"
      },
    • "outbound": {
      • "channel_limit": 10,
      • "outbound_voice_profile_id": "1293384261075731499"
      },
    • "created_at": "2018-02-02T22:25:27.521Z",
    • "updated_at": "2018-02-02T22:25:27.521Z"
    }
}