Objects

The following objects may be used when interacting with the Phaxio API:

Fax Object
Recipient Object
Phone Number Object
Barcode Object
ATA Object
Address Object
Blocking Rule Object
Port Order Object
Port Number Object
Port Number Note Object

Fax Object

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.
barcodes	A list of barcode objects if barcodes were scanned in the received document. All pages of received faxes will be scanned for Code128, Data Matrix, and PhaxCode barcodes.
caller_name	If enabled in your fax settings, this contains descriptive information about the sender for received faxes.
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.
caller_id	For sent faxes, the number set as the caller ID when sending the fax.
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.

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",
    "caller_id":"+18476661235",
    "from_number": null,
    "completed_at": "2015-09-02T11:28:54.000-05:00",
    "caller_name": "Catherine Lee",
    "cost": 21,
    "tags":{
        "order_id": "1234"
    },
    "recipients":[
        {
            "phone_number":"+14141234567",
            "status":"success",
            "retry_count":0,
            "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,
    "barcodes": []
}

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.
retry_count	The number of times transmission to this recipient was scheduled to be retried due to failures.
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.

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
}

Barcode Object

A JSON object describing a scanned barcode

Name	Data Type	Description
type	string	Describes the format of the barcode: phax_code, code_128, or data_matrix
page	int	The number of the page where the barcode was scanned. 1 based.
value	string	For non-PhaxCodeode barcodes, this is the information contained in the barcode
identifier	string	For PhaxCode barcodes only. The alpha-numeric identifier of the barcode.
metadata	string	For PhaxCode barcodes only. The metadata associated with the PhaxCode.

Example PhaxCode Object

{
    "type": "phax_code",
    "page": 1,
    "identifier": "px:ahZhax",
    "metadata": "example metadata which can even be JSON"
}

Example Barcode Object

{
    "type": "code_128",
    "page": 5,
    "value": "12345"
}

ATA Object

Name	Data Type	Description
id	integer	The ATA's ID number.
name	string	The name assigned to the ATA.
description	string	The description assigned to the ATA.
user_phone_number	E.164 Phone Number	The user phone number associated with the ATA.
domain	string	The domain for the ATA.
domain	string	The MAC address for the ATA (12 hexadecimal digits).
username	string	The username for the ATA. Note: This is only returned by operations that set or change the username (i.e. create and regenerate_credentials).
password	string	The password for the ATA. Note: This is only returned by operations that set or change the username (i.e. create and regenerate_credentials).

Autodetected ATA Object

Name	Data Type	Description
mac_address	string	The detected ATA's MAC address.
user_agent	string	The detected ATA's user agent string.
last_seen	string	A timestamp representing the last time the ATA was detected.

Address Object

A JSON object describing an address

Name	Description
id	ID number of address record. Used to reference address later.
end_subscriber_type	Entity type of the end subscriber. Either 'company' or 'individual'.
company_name	Company name of address (if address is owned by a company)
first_name	First name of owner of address (if address is owned by an individual)
last_name	Last name of owner of address (if address is owned by an individual)
phone_number	Phone number of address owner
email_address	Email address of address owner
vat_number	Value Added Tax (VAT) number
street	Street name
street_number	Street number
residence	Residence name
floor	Floor number
box	Box number
postal_code	Postal/ZIP code
city	City name
state	State/province/territory name
country	2-letter ISO 3166 country code (e.g. 'GB' or 'DE')
service_usage	User-defined value describing use or purpose of address

Example Address Object

{
    "id": 41,
    "end_subscriber_type": "individual",
    "company_name": null,
    "first_name": "Max",
    "last_name": "Mustermann",
    "phone_number": null,
    "email_address": "user@example.com",
    "vat_number": null,
    "street": "Wilhelmstraße",
    "street_number": "123",
    "residence": null,
    "floor": null,
    "box": null,
    "postal_code": "12345",
    "city": "Berlin",
    "state": null,
    "country": "DE",
    "service_usage": null
}

Blocking Rule Object

A JSON object describing a blocking rule

Name	Description
id	ID of the rule
to	The destination rule to block. (One of '*', a country alpha2 ('US'), or an e.164 phone number)
from	The source rule to block. (One of '*', a country alpha2 ('US'), or an e.164 phone number)
direction	The direction of the call that this rule applies to. (Either 'send' or 'receive)
is_locked	A boolean that denotes if this rule has been locked by the Phaxio service and cannot be altered by a user without contacting support.

Example Blocking Rule Object

{
    "id": 34567,
    "to": "*",
    "from": "+12015723798",
    "direction": "send",
    "is_locked": false
}

Port Order Object

Name	Description
id	The ID of the order.
port_numbers	An array of Port Number Objects
contact_number	The E.164 contact number for the order.
contact_email	The contact email for the order.
account_identifier	The identifier for the account associated with the numbers to port.
name_on_account	The name of the account associated with the numbers to port.
name_of_business	The name of the business associated with the numbers to port.
provider_name	The name of the provider associated with the numbers to port.
port_type	The type of numbers being ported. Either "business" or "residential".
port_out_pin	The PIN or password required to port out the number.
billing_number	The E.164 billing number for the order.
billing_address1	The first billing address line.
billing_address2	The second billing address line.
billing_city	The billing address city.
billing_state	The billing address state.
billing_zip	The billing address ZIP code.
status	The status of the order. See the statuses page for more information.
quantity	The quantity of numbers in the order.
created_at	A timestamp (in RFC 3339 format) representing the time when the order was created.
updated_at	A timestamp (in RFC 3339 format) representing the time when the order was last updated.
requested_for	A timestamp (in RFC 3339 format) representing the time when the order was requested to complete.
completed_at	A timestamp (in RFC 3339 format) representing the time when the order completed.
bill_received_at	A timestamp (in RFC 3339 format) representing the time when the bill was received.

Example Port Order Object

{
  "id": 1234,
  "contact_number": "+15551231234",
  "name_on_account": "Alice Acme",
  "name_of_business": "Acme",
  "provider_name": "Example Provider",
  "billing_number": "+15551231234",
  "billing_address1": "123 Test St.",
  "billing_address2": null,
  "billing_city": "Test City",
  "billing_state": "IL",
  "billing_zip": 12345,
  "esig": "Alice Acme",
  "status": "open",
  "quantity": 1,
  "created_at": "2021-07-07T18:56:04.590+00:00",
  "updated_at": "2021-07-07T18:56:04.590+00:00",
  "completed_at": null,
  "requested_for": null,
  "bill_received_at": null,
  "port_numbers" [
    {
      "id": 1234,
      "port_number": "+15551112222",
      "status": "open"
    },
    {
      "id": 5678,
      "port_number": "+15553334444",
      "status": "open"
    }
  ]
}

Port Number Object

Name	Description
id	The ID of the port number.
port_number	The E.164 phone number to port.
status	The status of the port number. See the statuses page for more information.

Example Port Number Object

{
  "id": 1234,
  "port_number": "+15551112222",
  "status": "open"
}

Port Number Note Object

Name	Description
id	The ID of the port number note.
note	The text of the note.
author	The author of the note.
created_at	A timestamp (in RFC 3339 format) representing the time when the note was created.
updated_at	A timestamp (in RFC 3339 format) representing the time when the note was last updated.

Example Port Number Note Object

{
  "id": 1234,
  "note": "Test note",
  "author": "John Smith",
  "created_at": "2015-09-02T11:28:02.000-05:00",
  "updated_at": "2015-09-02T11:28:02.000-05:00"
}