Fax Delivery and Status API
Custom applications can be created using the Fax Delivery and Status API utilizing the
The Fax Delivery and Status API supports the following file types.
|
File Extension |
Description |
|---|---|
| BMP | Bitmap |
| DOC | Microsoft Word v2003 and earlier |
| DOCX | Microsoft Word 2007 |
| EPS | Encapsulated Postscript |
| GIF | Graphics Interchange Format |
| HTM, HTML | Hypertext Markup Language |
| JPG, JPEG | Joint Photographic Experts Group |
| OMTPL | Omtool Template (Rich Text Format) |
| PCL | HP PCL5 Printer Control |
| Adobe Acrobat 7.0 | |
| PNG | Portable Network Graphics |
| PPT | Microsoft PowerPoint v2003 and earlier |
| PPTX | Microsoft PowerPoint v2007 |
| PS | PostScript Levels 1, 2, and 3 |
| RPT | Crystal Reports v10 and earlier |
| RTF | Rich Text Format |
| TIF, TIFF | Tagged Image File Format, group 3 and 4, black/white or grayscale images only |
| VSD, VDX |
Microsoft Visio v2003/2000 Note: The Compose component converts Visio files with Visio automation, which requires Visio 2003 to be installed on the server. (Visio automation with Visio 2000 installed on the server is not a supported configuration, but the Compose component supports Visio 2000 files.) |
| XLS | Microsoft Excel v2003 and earlier |
| XLSX | Microsoft Excel v2007 |
Installation and Configuration Requirements
-
-
-
One of the following
-
CloudFax connector
-
InterFAX connector
-
Note: The connectors based on your workflow requirements will require an InterFAX Service or Upland Intelligent Capture (UIC) account.
-
Dialogic fax modem driver and board
REST API HTTP Method Examples
Deliver
Any programming language used to make HTTP calls must be a POST request and the address the requests are sent to must be [site]/api/deliver.
See an example of the Deliver call endpoint below.
Select images to maximize and minimize view.
Status
The GET method is used to request data from a specific resource. The following parameters are specified in the Status example utilizing the GET method.
-
[site] -
-
PageNumber – Result page requested, one-based indexing
-
PageSize – Number of items per result page
-
Filter – Execute query to match items. This must be URL encoded, for example, equal signs to %3d, so that it is not damaged by the URL parameter parsing code.
The response is an array of items that match zero or more. Each object in the array represents one matching fax.
-
prCompleted indicates whether the job was completed; 0 is false, 1 is true.
-
prDelivered indicates whether the job was successfully delivered; 0 is false, 1 is true.
-
prFinalStateCode indicates the status if prCompleted == 1 and prDelivered == 0.
-
prFinalStateText indicates the final state of the job if prCompleted == 1 and prDelivered == 0.
Resend
Resend is used to resend a fax that was previously sent. The Deliver API is used first to send a fax job. The Resend method is then used to resend the fax when necessary.
RecipientEID is a long text string type received from the Deliver and Status API responses outlined above. It is used by the system to identify the fax job ID. It is contained in the string field labeled “prEntryID” in that response. You can get the RecipientEID from either call.
Use the RecipientEID in this call to tell the system which fax and which recipient to resend the fax to.
Note: No response body is returned.
Mark Read
Mark Read is used to mark faxes as read similar to email messages in a mailbox. The faxes will not appear bold if marked read.
RecipientEID is a long text string type received from the Deliver and Status API responses outlined above. It is used by the system to identify the fax job ID. It is contained in the string field labeled “prEntryID” in that response. You can get the RecipientEID from either call.
Faxes marked read are not retrieved by the AccuRoute CloudFax or InterFAX connector as new faxes.
Note: No response body is returned.
Mark Unread
Mark Unread is used to mark faxes as unread similar to email messages in a mailbox. The faxes will appear bold if marked unread.
RecipientEID is a long text string type received from the Deliver and Status API responses outlined above. It is used by the system to identify the fax job ID. It is contained in the string field labeled “prEntryID” in that response. You can get the RecipientEID from either call.
Note: No response body is returned.
Get Attachment Information
The GET method in this example is used to get attachment related information, for example, attachment size, date created, filename and more.
RecipientEID is a long text string type received from the Deliver and Status API responses outlined above. It is used by the system to identify the fax job ID. It is contained in the string field labeled “prEntryID” in that response. You can get the RecipientEID from either call.
Get Attachment as Merged PDF
The GET method in this example is used to get all attachments associated with a fax as a merged PDF. The Response is an application/octet-stream containing all attachments merged as a PDF.
RecipientEID is a long text string type received from the Deliver and Status API responses outlined above. It is used by the system to identify the fax job ID. It is contained in the string field labeled “prEntryID” in that response. You can get the RecipientEID from either call.
FAQs
|
REST API Parameter |
Question |
Answer |
|---|---|---|
| HTTP Post: message.prOriginator | What is purpose of Message.prOriginator? Is it an email address? What email address should be used if it is an automated outbound fax? | It identifies who sent the job. Typically, it is an email address although it does not have to be. It must be non-blank. |
| recipients | Does the fax number format need to include: 1 + area code + number? Is punctuation allowed? | The format depends on the system configuration. It is recommended that the 11 digit number format is used |
| attachments | What is the naming convention for a filename? | The filename must include the extension that identifies the document type, for example, documentname.pdf, documentname.docx. |
| bytes | Is Bytes the attachment size or the actual stream of bytes? | Bytes is the actual stream of bytes. |
| filename | Is there a need to indicate the document type or will that be captured from the filename? | The document type is determined by the filename extension. |
| HTTP Responses | What are the expected HTTP responses and their meaning? | A HTTP 200 response indicates success. Other responses have their typical http meanings. Note: A HTTP 200 response is returned if the job delivered to the system failed as indicated by the DeliveryResponse object member. In this case, success is false and the actual error is included in the ErrorText. |
| messageEntryID | What is the messageEntryID in a response and how is it used? | Each job delivered to the system is given a unique "Message Id" that identifies the job. |
| recipientIDs | What is the purpose of the recipientIDs list? | Each recipient submitted as part of the job is given a unique id. This allows direct access to their status when bundling multiple recipients in one job. |
| HTTP GET: items | Will the item detail include a time stamp for when the transmission was completed? | Yes. |
| prRecipientType | What are the prRecipientType values and what do they mean? | The values are typically 0 for Email and 1 for Fax. |
| prCompleted, prDelivered | What is the difference between prCompleted and prDelivered? | prDelivered is set to true if the fax is delivered successfully. prCompleted is set to true when the job has completed the entire workflow. There are additional steps past delivery. The job is still in progress when it is sent and delivered. It is not useful to check prDelivered until prCompleted is true. |
Troubleshooting
| Error | Recommendation |
|---|---|
| 400 | Ensure values have before and after quotes, for example, “value”. |
| 401 | Configure IIS to allow Anonymous Access. |
| 404 | Check the URL specified. |