API Call Status and Job Status

API Resources


This article assumes you:

  1. Have an API developer account.
  2. Sent a Fax via the API

After we send the fax we are going to query the API for the status.

Here is a PHP Curl request to the Fax_GetFaxDescriptionsUsingIds API function. We are passing in the standard account information as well as a nested array of the FaxIds1 field which is the job id we got back from our Fax_SendFax call.


<?php

$curl = curl_init()

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api2.westfax.com/REST/Fax_GetFaxDescriptionsUsingIds/json",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => array('Username' => 'test@test.com','Password' => 'fakepass','Cookies' => 'false',
  'ProductId' => '00000000-0000-0000-0000-000000000',
  'FaxIds1' => '{"Id":"111111-1111-1111-1111-111111111111","Direction":"Outbound"}'),
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

>

Here is the result. Notice the output is broken down into two calls in the FaxCallInfoList. You have the Individual CallId for each call in the job and the individual status. Here it is Waiting to dial. This means we just received the fax and it’s in the pre-processing phase where it is converted to TIFF and being prepared for faxing. Also, note the Id field on the main Result object. That is the JobID and the Status is currently Submitted.


{
    "Success": true,
    "Result": [
        {
            "FaxCallInfoList": [
                {
                    "CallId": "00000000-0000-0000-0000-11111",
                    "CompletedUTC": "2020-02-24T17:02:45Z",
                    "TermNumber": "1112223333",
                    "OrigNumber": "2223334444",
                    "OrigCSID": "2223334444",
                    "Result": "Waiting to dial"
                },
                {
                    "CallId": "00000000-0000-0000-0000-22222",
                    "CompletedUTC": "2020-02-24T17:02:45Z",
                    "TermNumber": "5556667777",
                    "OrigNumber": "2223334444",
                    "OrigCSID": "2223334444",
                    "Result": "Waiting to dial"
                }
            ],
            "Id": "1111111-1111-1111-1111-111111111",
            "Date": "2020-02-24T17:02:45Z",
            "Direction": "Outbound",
            "Tag": "Retrieved",
            "PageCount": 1,
            "FaxQuality": "Normal",
            "Status": "Submitted",
            "Reference": "Test Job 1",
            "JobName": "Test Job"
        }
    ]
}

Now that some time has passed let’s run the call again. This result below is the same job but it is now Complete. You will see one of the jobs is marked as “Sent” and the other one is “Failed” and the overall job has the Status of “Complete“. You need to look at the Result of the FaxCallInfoList to determine the true status of a fax job. Complete just means that we are done with this fax. It does not mean success. You will want to either resend the fax to the failed call or handle it manually by figuring out what is wrong with the number and updating it.


{
    "Success": true,
    "Result": [
        {
            "FaxCallInfoList": [
                {
                    "CallId": "00000000-0000-0000-0000-11111",
                    "CompletedUTC": "2020-02-24T17:04:55Z",
                    "TermNumber": "1112223333",
                    "OrigNumber": "2223334444",
                    "TermCSID": "(222) 333-4444",
                    "OrigCSID": "2223334444,
                    "Result": "Sent"
                },
                {
                    "CallId": "00000000-0000-0000-0000-22222",
                    "CompletedUTC": "2020-02-24T17:04:52Z",
                    "TermNumber": "5556667777",
                    "OrigNumber": "2223334444",
                    "TermCSID": "(222) 333-4444",
                    "OrigCSID": "2223334444",
                    "Result": "Failed"
                }
            ],
            "Id": "1111111-1111-1111-1111-111111111",
            "Date": "2020-02-24T17:05:28Z",
            "Direction": "Outbound",
            "Tag": "Retrieved",
            "PageCount": 1,
            "FaxQuality": "Normal",
            "Status": "Complete",
            "Reference": "Test Job 1",
            "JobName": "Test Job"
        }
    ]
}
In summary:

The job Status is representative of whether we are still processing a fax job. The individual Result code on the FaxCallInfoList is the authoritative location for the status. Complete means that we are done and will not work on the calls anymore and it is final.

This confuses some using the API and usually results in 2 kinds of mistakes:

  • The developer sends multiple calls per job, and does not realize that there is a job Result, AND a call Status. The developer interprets the job Status as the final result, and therefore does not get the real result of the job.
  • The developer ignores the job result and uses the call result that is retrieved and assumes that the result is the final result. Unless the job Status is marked as Complete we are still processing the calls. One should wait for Status = Complete before you read the individual Result.

WestFax can also customize your retry strategy. We typically retry 5 times before failing. If you wish to have us only try once and then fail let us know and we can adjust your retry settings.

All possible values of the Call Result (Bold are common Result codes)
Sent, //Fax was sent
Waiting to dial, //We are preparing the fax.
Dialing, // We are dialing the number.
Busy, //The line is busy
NoAnswer,
NoFaxDevice,
Cancelled,
Failed, //We retried several times and it never sent.
InvalidNumber // Bad number i.e. 22930-3940-399430A
OperatorIntercept // Disconnected number. The Three tones recording.
All possible values of Job Status (Some you will never see. Bold are common Status codes):
Complete, //Job is done. Check call Result for individual fax status.
Submitted, //This means it’s still processing.
Production,
UnSubmitted,
UnAssigned,
Failed, //None of the calls went through. See Call Result for status.
Cancelled,
Paused

February 27, 2020 /