RESTful API Faxing


The Clearly Fax service offers an API which allows you to send faxes and receive information about a particular fax. You may also receive Inbound fax information via the use of the callback URL which can be configured by contact Customer Care.

The Specification


  • Your API token can be found in the trunking store at https://trunking.clearlyip.com under the Location, locate the Tile called SIP Credentials and you will see a field called Keycode.  That Keycode is your API Token.

Callback URL

  • The API is designed to allow for you to be notified via a web callback on inbound and outbound faxes. 

Inbound Fax Callback URL


  • Navigate to the our Trunking store at https://trunking.clearlyip.com and Under Products and Service Click on Fax
    prod-services-faxing


  • Locate the Inbound Fax to Email Group you have setup already and press the edit icon or create a new one as outlined here.


  • Define the callback URL you want us to post to anytime a new fax is received.  You will also have to define at least a single email address so we can notify you if the callback fails.


Outbound Fax Callback URL

To provide a callback URL on outbound faxes, please see the OpenAPI specification at https://fax.sendfax.to/faxapi/v1/openapi.yaml

Callback Requirements

  • The callback URL must be HTTPS
  • The callback from our servers uses a POST request
  • The callback from our servers POSTs a JSON body to your URL
  • An example of the body you will receive in the callback is below:

     
  1. { 
        "uuid": "054055e6-2bfa-440b-bd76-22e3004c07b1",
    "state": "sent",
    "result": "FAILED",
    "resultstr": "error starting fax session",
    "srccid": "19203833100",
    "destcid": "19203833100",
    "remotename": "UnknownId",
    "localname": "SendFax.to API",
    "startutime": "1597097642.147518",
    "endutime": "1597097652",
    "sessiontime": "77",
    "pages": 3,
    "source": "api2fax"
  }
  2. {
      "method": "POST",
      "path": "/",
      "query": {},
      "headers": {
        "x-forwarded-for": "0.0.0.0",
        "x-forwarded-proto": "https",
        "x-forwarded-port": "443",
        "host": "callbackurl.example.com",
        "content-length": "361",
        "user-agent": "CIP Fax Callback Bot",
        "content-type": "application/json",
        "accept": "application/json"
      },
      "bodyRaw": "{\"uuid\":\"CLEARLYIP-2bfa-440b-bd76-22e3004cTEST\",\"state\":\"sent\",\"result\":\"FAILED\",\"resultstr\":\"error starting fax session\",\"pdfurl\":null,\"thumbnailurl\":null,\"srccid\":\"19203833100\",\"destcid\":\"19203833100\",\"remotename\":\"UnknownId\",\"localname\":\"SendFax.to API\",\"startutime\":\"1597097642.147518\",\"endutime\":\"1597097652\",\"sessiontime\":\"77\",\"pages\":3,\"source\":\"api2fax\"}",
      "body": {
        "uuid": "CLEARLYIP-2bfa-440b-bd76-22e3004cTEST",
        "state": "sent",
        "result": "FAILED",
        "resultstr": "error starting fax session",
        "srccid": "19203833100",
        "destcid": "19203833100",
        "remotename": "UnknownId",
        "localname": "SendFax.to API",
        "startutime": "1597097642.147518",
        "endutime": "1597097652",
        "sessiontime": "77",
        "pages": 3,
        "source": "api2fax"
      }
    }


    		 RSS of this page