Fax Object

Note: While normal v2 API operations already use v2 Fax Objects, callbacks are not yet versioned, and currently return v1 Fax Objects instead.

The fax object is a JSON object returned by the Phaxio API and represents a fax job in the system. Its properties are described in the table below.

Name Description
id The fax's ID number. Can be used to retrieve the fax later.
direction Either 'sent' or 'received'. States whether the fax is being sent or received.
num_pages The number of pages in the fax.
cost The total cost of the fax in cents. This value may change depending on the success of the job. See the billing page.
status The status of the job. See the statuses page for more information.
is_test true or false. States whether the job is in test mode.
created_at A timestamp (in RFC 3339 format) representing the time when the initial API call was made.
from_number For received faxes, this holds the sender's E.164 phone number.
to_number For received faxes, this holds the Phaxio phone number that was used to receive the call.
recipients For sent faxes, this holds an array of recipient objects. See below section on recipient objects.
tags A hash of tag name and value pairs. If a fax was sent with tag metadata, it will appear here.
error_type One of the Phaxio error types. Will give you a general idea of what went wrong for a failed fax. (e.g. `lineError`)
error_message A more detailed description of what went wrong for a failed fax.
error_id A numeric error code that corresponds to the error message, if any.
completed_at If the job is complete, this is a timestamp (in RFC 3339 format) representing the time the job was completed.

Recipient Object

A JSON object describing a fax recipient

Name Description
phone_number The recipient's E.164 phone number
status The status of the job for this specific recipient. See the statuses page for more information.
completed_at A timestamp (in RFC 3339 format) representing the time the job was completed for this recipient.
bitrate The bitrate in bits/second that the fax was transmitted at.
resolution The horizontal resolution that the fax image was transmitted at in pixels per meter.
error_type One of the Phaxio error types. Will give you a general idea of what went wrong for this receipient. (e.g. `lineError`)
error_message A more detailed description of what went wrong for this receipient.
error_id A numeric error code that corresponds to the error message, if any.

Example Fax Object

{
    "id": 123456,
    "direction": "sent",
    "num_pages": 3,
    "status": "success",
    "is_test":true,
    "created_at": "2015-09-02T11:28:02.000-05:00",
    "from_number": null,
    "completed_at": "2015-09-02T11:28:54.000-05:00",
    "cost": 21,
    "tags":{
        "order_id": "1234"
    },
    "recipients":[
        {
            "phone_number":"+14141234567",
            "status":"success",
            "completed_at":"2015-09-02T11:28:54.000-05:00",
            "bitrate":14400,
            "resolution":8040,
            "error_type":null,
            "error_id":null,
            "error_message":null
        }
    ],
    "to_number": null,
    "error_id": null,
    "error_type": null,
    "error_message": null
}

Phone Number Object

A JSON object describing a phone number

Name Description
phone_number The phone number in E.164 format
city The city for the area code of the number
state The state for the area code of the number
country The country of the number
cost The monthly cost of the number in cents
last_billed_at A timestamp (in RFC 3339 format) representing the last time your account was billed for this number
provisioned_at A timestamp (in RFC 3339 format) representing the time you provisioned the number
callback_url A callback URL, if configured, for incoming faxes to this number

Example Phone Number Object

{
    "phone_number": "+18476661235",
    "city": "Northbrook",
    "state": "Illinois",
    "country": "United States",
    "cost": 200,
    "last_billed_at": "2016-05-10T11:38:15.000-05:00",
    "provisioned_at": "2016-03-10T11:38:15.000-06:00",
    "callback_url": null
}