Overview

API Endpoints

Url

Description

https://ws.concordfax.com/fax/v5

API endpoint that method calls will be executed against

https://ws.concordfax.com/fax/v5/faxws.wsdl

WSDL endpoint that describes API service. Used by many application frameworks to generate code proxies to service.

Concord Fax Web services offers the following methods for requesting status of a fax.

  • SimpleGetFaxStatus

  • GetFaxStatus

  • GetRealtimeFaxStatus

  • GetRealtimeFaxStatusEx

  • GetRealtimeFaxStatusEx2

  • GetRealtimeFaxStatusEx3

Any of these methods, with the exception of SimpleGetFaxStatus, can be used to request status for multiple jobs. SimpleGetFaxStatus can only be used with a single Job Id.

Request

A request for status from all of the fax status methods, follows an outline similar to the one shown below:

Xml Copy imageCopy
<?xml version="1.0" encoding="utf-8"?>
<urn:GetFaxStatus>
  <urn:UserID>string</urn:UserID>
  <urn:strPIN>string</urn:strPIN>
  <urn:FaxJobIds>
    <!--One or more repetitions:-->
      <urn:item>
        <urn:JobId>string</urn:JobId>
      </urn:item>
   </urn:FaxJobIds>
</urn:GetFaxStatus>

Response

The response provided to any fax status method requests will follow an outline similar to the one shown below:

Xml Copy imageCopy
<?xml version="1.0" encoding="utf-8"?>
<FaxWS:FaxStatusResponse>
  <FaxWS:return>boolean</FaxWS:return>
  <FaxWS:FaxStatusList>
    <!--Zero or more repetitions:-->
    <FaxWS:item>
      <FaxWS:FaxJobId>string</FaxWS:FaxJobId>
      <FaxWS:FaxJobStatusId>int</FaxWS:FaxJobStatusId>
      <FaxWS:StatusDescription>string</FaxWS:StatusDescription>
      <FaxWS:Error>
        <FaxWS:ErrorCode>int</FaxWS:ErrorCode>
        <FaxWS:ErrorString>string</FaxWS:ErrorString>
      </FaxWS:Error>
    </FaxWS:item>
  </FaxWS:FaxStatusList>
  <FaxWS:WSError>
    <FaxWS:ErrorCode>int</FaxWS:ErrorCode>
    <FaxWS:ErrorString>string</FaxWS:ErrorString>
  </FaxWS:WSError>
</FaxWS:FaxStatusResponse>

  • return element indicates the success or failure of the method call as a whole.

  • WSError element returns the method level error information for the success or failure of the method as a whole.

  • Error element at each of the item returns the error information for a specific job/recipient.

Best practices for making status calls

Follow the below guidelines while requesting fax status using Fax Web services:

  • Limit the number of jobs per request: Even though concord web services impose no limits on the number of jobs per requests, it is advised that for optimal response time / performance, limit the number of jobs per requests to 100.

  • Response Timeout: When requesting multiple job status per request, the time to process the request will increase. It is advised that you set the response timeout to 60-120 seconds or as required.

  • Status polling frequency: On average, a single page may take between 20-40 seconds to transmit. Therefore, polling for status more frequently than the value mentioned above will result in gateway returning cached responses. It is advised that you should NOT poll for status an interval less than 30 seconds.

  • Push Vs Pull: Concord’s web services provide efficient mechanisms for pushing status to the remote end on the completion of a fax. Status will be pushed to the remote end as soon as the fax is completed. Where possible it is advised to implement a push mechanism with failover to pull for efficient fax status processing. As an example, one may wait up to 5 minutes for the status to be pushed to remote end before starting to poll for status.

Use Case Scenario

  • If you are requesting status for a single job:

    • If the job ID you requested status for failed validation, error information is only set at the item level.

      • Return is set to true - Method Success

      • WSError is set to success - Method level error

      • Error is set to the appropriate error at item level

  • If you are requesting status for multiple jobs:

    • If all the job Ids you requested failed validation, error information is only set at the item level.

      • Return is set to true - Method Success

      • WSError is set to success - Method level error

      • Error is set to the appropriate error at each item level

    • If only some of the Job Ids you requested status for failed or all succeeded.

      • Return is set to true - Method Success

      • WSError is set to success - Method level error

      • Error is set to the appropriate error at each item level

Pseudo Code

Follow the below guidelines for requesting status / processing response of a fax status call:

  • Build the status request

  • Submit the request to FaxWS gateway

  • Web Service call failed (Connection issues, timed out etc.)

    • Retry status call after an appropriate delay

  • Web Service call succeeded

    • Return value is false (Failure)

      • Check WSError for error details, correct and retry submission

    • Return value is true (Success)

      • Process FaxWSStatusList

        • For each status in list

          • If FaxJobStatusId is 1: (Success)

            • Processing complete

          • If FaxJobStatusId is 2: (Failed)

            • Check Error for details, retry if required

          • If FaxJobStatusId is 3: (Pending)

            • Retry status request after an appropriate delay

See Also