Virtual Fax™ API User Guide

Virtual Fax API User Guide

PIPSUGVFAPI.05.04 - 1 - Protus IP Solutions

Introduction ________________________________________________________ 2

Single Fax Job Submission (XML)______________________________________ 2 Protus XML Submission Services_____________________________________________ 2 Input: Job Request _________________________________________________________________2 Output: Status Response _____________________________________________________________2 Single Fax Job Submission XML Element Hierarchy ____________________________ 3 Single Fax Job Submission XML Element Descriptions___________________________ 3 Example Single Fax Request _________________________________________________ 7 Protus Single Fax Job Submission (SMTP) _______________________________ 8 Protus SMTP Submission Services ____________________________________________ 8 Email Content_____________________________________________________________ 8 Required Parameters ________________________________________________________________8 Optional Parameters ________________________________________________________________9 Example Email ___________________________________________________________ 12 Sample Fax Cover Page ____________________________________________________ 13 Single Fax Confirmation Email Messages _______________________________ 14 Confirmation Email Destination and Parsing __________________________________ 14 Other Fax Result Reporting Options _________________________________________ 14 Deactivating Confirmations_________________________________________________ 14 Successful Fax Delivery Confirmation ________________________________________ 15 Default Confirmation Style__________________________________________________________15 Alternate Machine Friendly Confirmation Style__________________________________________16 Failed Fax Delivery Confirmation ___________________________________________ 17 Default Confirmation Style__________________________________________________________17 Alternate Machine Friendly Confirmation Style__________________________________________18



Introduction Protus offers a set of Application Programmer Interfaces (APIs) as part of its Job Submission capabilities. Customers can use either SMTP, or XML over HTTPS to submit jobs easily and securely, receiving immediate confirmation that Protus has received the job. Under the Virtual Fax product line, Protus has two APIs which may be used to submit single destination faxes:

• Single Fax Job Submission (SMTP) • Single Fax Job Submission (XML)

Under the Messaging Services product line, Protus has a number of APIs available to send multiple destination fax or voice broadcasts:

• Fax Broadcast Job Submission (SMTP) • Fax Broadcast Job Submission (XML) • Voice Broadcast Job Submission (XML)

The following sections describe each of the Virtual Fax APIs. The Messaging Service APIs may be found in the user guide: “Messaging Service APIs”.

Single Fax Job Submission (XML) Protus XML Submission Services The Protus system requires an XML document as the Job Submission input and provides a Request Status XML document as the result.

Input: Job Request To submit a job request to Protus, post a SOAP encapsulated XML document called a Job Request, to the Protus XML Submission Web Services:

https://www.protusfax.com/protus/xmlwebservices/xmlsubmitter/xmlsubmit.asmx

The XML document must contain all of the account and document information needed to create a Protus Job Request, as described below.

Output: Status Response The Protus server responds to a Broadcast Request with SOAP encapsulated response, which provides a status code indicating the success or failure of the Broadcast Request.



Single Fax Job Submission XML Element Hierarchy • single_fax_info

o login_key user_id user_email user_password

o single_fax_options billing_code from_name start_hour end_hour legal_size_flag tiff_image_flag resolution cover_page

• cover_page_name • cover_page_tags • cover_page_subject

o fax_recipient fax_recipient_number fax_recipient_name

o document_list document

Single Fax Job Submission XML Element Descriptions single_fax_info is the root element of the Single Fax Request XML document. Its only attributes are used to define the namespace and the location of the schema. It contains the four main functional elements for the broadcast: login_key, single_fax_options, fax_recipient, and document_list. login_key • required • has no attributes • contains elements pertaining to account identification and authentication user_id • only one of either user_id or user_email is required • has no attributes • contains the account user id number, which is an integer from 1 to 2000000000 user_email • only one of either user_id or user_email is required • has no attributes • contains the email address assigned to an account user, which is a string of up to 60 characters.



user_password • required • has no attributes • contains the password associated with the account user, which is a string of up to 20 characters. single_fax_options • required • has no attributes • contains elements pertaining to any special options to be applied to the fax send billing_code • optional • has no attributes • will appear on the broadcast report, but not on the faxed document • value: string of up to 128 characters • default: depends upon the account settings from_name • optional • has no attributes • will appear as the from text on the fax banner line • value: string of up to 50 characters • default: account from name default setting start_hour • optional • has no attributes • specifies the beginning hour of the allowed range of delivery hours • value: integer 0-23 • default: 0 end_hour • optional • has no attributes • specifies the end hour of the allowed range of delivery hours • value: integer 0-23 • default: 23 legal_size_flag • optional • has no attributes • specifies that document should be converted as legal size paper • value: true|false • default: false



tiff_image_flag • optional • has no attributes • specifies that document provided is a tiff image requiring no further image conversion • value: true|false • default: false resolution • optional • has no attributes • specifies whether the document should be converted to a high (fine) resolution or low (draft) resolution tiff image • value: low|high • default: low cover_page • optional • has no attributes • identifies whether or not a cover page should be inserted at the beginning of the fax transmission. Cover pages provide Fax Number, To, From, Page Count, Date Time, Subject, Cover Page Flags and Comments as merged fields inside the first page of the fax transmission • contains elements pertaining to the creation of the cover page cover_page_name • optional • has no attributes • can be used by clients who have Custom Cover Page templates on file with the Protus System. Client’s requiring custom cover pages (i.e. movement of cover page merge points to alternate locations) must contact their sales representative and provide samples of desired cover page layouts. Once complete, custom cover page templates are assigned a unique code that must be identified here. • value: string (15) • default: none cover_page_tags • optional • has no attributes • sets the use of the Cover Page Flags. The flags are: U-Urgent, R-Reply, I-Information, C-Please Comment, A-Reply ASAP. • value: string (5) • default: none cover_page_subject • optional • has no attributes



• the subject line which will appear on the cover page • value: string (50) • default: none fax_recipient • required • has no attributes • contains elements pertaining to an individual fax broadcast destination fax_recipient_number • required • has no attributes • contains the destination fax number beginning with the country code • value: numeric string of up to 20 digits fax_recipient_name • optional • has no attributes • contains the destination name for the to field on the fax banner line • value: string of up to 50 characters • default: none document_list • required • has no attributes • contains at least one document element for each document to be faxed document • minimum 1 document element required • has attributes defining document characteristics • contains document to be faxed as encoded text, as defined by the document attributes document_content_type attribute • required • defines MIME content type of original document: text, html, etc. document_encoding_type attribute • required • defines MIME encoding type used to encode document • values base64|uuencode|quoted-printable|none|bin-hex document_extension attribute • required • provides file extension of original document • value: string



Example Single Fax Request <?xml version="1.0" encoding="UTF-8" ?> <single_fax_info xmlns="http://www.protus.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.protus.com sfax_schema.xsd"> <login_key> <user_id>14975</user_id> <user_password>xxxxxx</user_password> </login_key> <single_fax_options> <billing_code>Single - May 27 - 14975</billing_code> <from_name>Single - Randy Morrow</from_name> <start_hour>0</start_hour> <end_hour>23</end_hour> <release_date>2004-05-27T10:00:00</release_date> <legal_size_flag>false</legal_size_flag> <tiff_image_flag>false</tiff_image_flag> <resolution>low</resolution> <cover_page> <cover_page_tags>U</cover_page_tags> <cover_page_subject>This is the subject</cover_page_subject> </cover_page> </single_fax_options> <fax_recipient> <fax_recipient_number>16135554974</fax_recipient_number> <fax_recipient_name>SingleTest - Randy</fax_recipient_name> </fax_recipient> <document_list> <document document_content_type="text/plain" document_encoding_type="7bit" document_extension="txt">This is the content!</document> <document document_content_type="application/msword" document_encoding_type="base64" document_extension="doc">0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAGAAAAAAAAAAAAAAABAAAAJgAAAAAA AAAAEAAAKQAAAAEAAAD+////AAAAACcAAAD///////////////////////////////////// //////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////. . . (lines omitted) . . . AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</document> </document_list> </single_fax_info>



Protus Single Fax Job Submission (SMTP) Protus SMTP Submission Services For customers who wish to send machine generated email to fax transmissions Protus offers a configurable addressing method that allows the passing of fax parameters within the User Name section of the To: line. • Customers are asked to create a plain text MIME email with desired fax parameters included on the To: line. • The method supports a number of fax parameters. All tags are optional and position independent, so only the tags you need to activate must be included to control the features you want. • All of the Boolean flags default to “false” if they are not included.

Email Content The Protus system requires a plain-text MIME email, with the body as 7-bit plain-text and the attachments Base64 encoded, as the Fax Job Submission input. The email structure is as follows: To:Fax=faxnumber/fr=fromname/to=toname/bc=billingcode/lg=logoname /st=starthour/en=endhour/cp=coverpageboolean/cf=covertags/cn=covername /le=legalboolean/rf=fineresboolean/[email protected] From: [email protected] Subject: Cover Page Subject if required Email Body: Password Line 1 Comment section of cover page or Fax Content Line 2 Line 3 Etc… Email Attachments: Up to 9 attachments of supported file types

Required Parameters Fax Number: Code: Fax= Type: String (11 digit number for North American destinations) Default: None The destination fax number for the transmission is inserted immediately following the string “Fax=”. North American destinations must begin with the number “1”. International destinations must begin with the country code (example: 44 for UK destinations) Avoid use of brackets “(“, dashes “-“, and spaces.



Optional Parameters From Text Over Ride: Code: /fr Type: String (50 character maximum) Default: User Account From Name This is an alphanumeric string that will be used to populate the “From” text on the Fax banner line. If this tag is not included, then the “From” text will be taken from the default associated with the User Account. Space Character is not supported. Fax Recipient Name: Code: /to Type: String (50 character maximum) Default: None This is an alphanumeric string that will be used to populate the “To” text on the Fax banner line. If the tag is not included, then no recipient name will appear on the fax banner or within an attached cover page. Space character is not supported. Billing Code: Code: /bc Type: String (128 character maximum) Default: User Account Billing Code This parameter assigns the customer’s customized billing code to the fax transmission. If not included, the billing code will be assigned from the customer’s account default setting alphanumeric. Billing Codes represent the senders reference ID for an individual transmission. They appear on fax confirmations, on-line reports and invoices. Logo Name: Code: /lg Type: String (15 character maximum) Default: Default Logo for Account Note: Fee may apply, Contact your Sales Associate This is a special parameter for clients with multiple Logo’s on file. The parameter allows a sender to request which specific logo should be inserted onto the fax transmission. Clients can have either a default logo or multiple logo’s set up for their account by contacting their sales associate and providing them with a Black and White BMP of JPG image. Large images, requiring resizing, may loose resolution. Note that logo insertion is not a compulsory feature for using Automated Single Fax. Start Hour: Code: /st Type: Integer (0-23) Default: 0 Sets the earliest hour before which no faxing may occur. The default of 0 means that faxing may commence at midnight.



End Hour: Code: /en Type: Integer (0-23) Default: 23 Sets the latest hour after which no faxing may occur. The default of 23 actually refers to the end of the 23rd hour, ie. 23:59 (11:59 PM), and means effectively that faxing is allowed until 1 minute before midnight. Cover Page: Code: /cp Type: Boolean (true/false) Default: false This tag identifies whether or not a cover page should be inserted at the beginning of the fax transmission. Cover pages provide Fax Number, To, From, Page Count, Date Time, Subject, Cover Page Flags and Comments as merged fields inside the first page of the fax transmission. This tag is required to activate the /cn and /cf parameters. Cover Page Flags: Code: /cf Type: String (URICA) Default: None This parameter sets the use of the Cover Page Flags. The flags are:U – Urgent, R- Reply, I –Information, C – Please Comment, A – Reply ASAP. Note that this tag can only be used if the Cover Page tag is set to “true”. Cover Page Name: Code: /cn Type: String (15 characters) Default: Default Cover Template Note: Fee may apply, Contact your sales associate. This tag can be used by clients who have Custom Cover Page templates on file with the Protus System. Client’s requiring custom cover pages (i.e. movement of cover page merge points to alternate locations) must contact their sales representative and provide samples of desired cover page layouts. Once complete, custom cover page templates are assigned a unique code that must be identified via the /cn tag. Legal Conversion: Code: /le Type: Boolean (true/false) Default: False This tag is used to request a legal format Tif conversion for attached documents. Note that receiving fax machine must be configured to accept Legal size Tif images in order to receive converted image on a single page.



Fine Resolution: Code: /rf Type: Boolean (true/false) Default: false This tag is used to request a Fine Resolution for converted TIF images. In general, Fine resolution can improve the quality of fax images containing detailed graphics and writing below 8 point font. Landscape Orientation: Code: /ls Type: Boolean (true/false) Default: false This tag is used to request a Landscape orientation for the conversion of the plain text email body. Note that Plain text emails cannot be formatted in the same way as attached document files. The default font used to convert plain text email bodies is Lucida Console 12 point font. See account parameters (Section 5) to change the default Font used for your account if required. Cover Page Subject: Code: no code. Uses subject line Type: String (Maximum 42 characters) Default: None The subject for the cover page can be passed on the subject line of the email message. Cover Page Comment: Code: no code. Uses email body Type: String (Email Body following Password) Default: None The Cover page comment section is populated with the content of the Plain Text email body following the Password parameter on the first line. Line length is set 72 characters. Number of lines available (using default Font size of 12) is 25 lines on 1st page and 49 lines on subsequent pages. Password: Code: no code. Uses first line of plain text email body Type: String (maximum 8 characters) Default: None The password parameter must appear as the first line in the plain text section of the email body. Passwords are case sensitive and can be any combination of alpha numeric characters up to 8 characters long. Contact us to have your password changed or password validation deactivated.



Example Email In this example, the single fax automated email is coming from [email protected], the customer’s password is “mypass”, and the customer wishes to send a fax to 1-613-248-4578 for a recipient named “Bob_Smith”. The From Name to appear on the fax banner line is “Jane_Doe”, and the faxes will be sent using “fine” resolution. The customer is assigning a billing code of “abc1234” which will appear on all associated reports. The client is requesting a standard Cover Page with a check mark in the “Urgent” cover page flag and the subject “BIG SALE!!!”. The cover page will include a short comment and the fax content will be composed of a 1 page Microsoft Word Document called “Flyer.doc”.



Sample Fax Cover Page



Single Fax Confirmation Email Messages Confirmation Email Messages are sent following either fax delivery or fax failure. Fax confirmation messages are available in 2 different styles; a default style containing friendly verbiage suitable for manual interpretation of fax results and an alternate machine friendly confirmation style suitable for automated email parsing.

Confirmation Email Destination and Parsing Confirmations are sent to the Confirmation Email Address specified in a clients account profile. The address can be different than the originating email address used for account validation. In general all confirmation emails contain basic fax information in the email subject line. It is therefore possible to automate confirmation email parsing using only the email headers. Special information like Duration and Error Reason Codes must be obtained by parsing the email plain text body.

Other Fax Result Reporting Options In addition to individual confirmation messages, reports of fax activity and fax results are available for download through our Client web Interface. In addition, a complete transaction breakdown is sent with all monthly Invoices.

Deactivating Confirmations If desired accounts can be set to not send confirmations for Successful or Failed fax attempts. This is an account parameter that must be set manually. Contact your Sales associate or our support department to de-activate confirmation sending for your account.



Successful Fax Delivery Confirmation

Default Confirmation Style

Email Header Destination Email: Confirmation Email Address from Account Profile Subject: Contains fax result, number, Protus Transaction ID, Account Number and Billing Code Email Body Email Body 1st Line: Fax result string “SUCCESSFUL FAX” Customer No.: Account Number used to process fax transmission Reference No.: Transaction ID number generated by Protus Fax System Billing Code: Client Reference number passed via /bc tag Sent At: Delivery time stamp in EST (GMT factor included) Pages: Number of pages in transmitted TIF file Duration: Value in seconds to transmit TIF image Your Fax To: Destination Fax number To: Recipient name passed via /to tag Cost: Cost of individual fax transmission down to 4 decimal places Taxes: If appropriate Report Version: Identifier of confirmation version



Alternate Machine Friendly Confirmation Style

Email Header Destination Email: Confirmation Email Address from Account Profile Subject: Contains fax result, number Email Header Protocol: Internal Use (Always = MF) Version: Identifier of Confirmation Version Key: Billing code passed via /bc tag Status: String “success” for successful faxes Status_info: Error code equal to 0 for successful faxes Delivery_time: Delivery date time in GMT Page_count: number of pages in delivered TIF file Billing_Rate: Rate per page delivered Phone_Number: This is the Destination Fax Number Transmit_time: Duration of fax transmission Reference_number: Transaction ID number generated by Protus Fax System



Failed Fax Delivery Confirmation

Default Confirmation Style

Email Header Destination Email: Confirmation Email Address from Account Profile Subject: Contains fax result, number, Protus Transaction ID, Account Number and Billing Code Email Body Email Body 1st Line: Fax result string “FAX FAILED” Customer No.: Account Number used to process fax transmission Reference No.: Transaction ID number generated by Protus Fax System Billing Code: Client Reference number passed via /bc tag Your Fax To: Destination Fax number To: Recipient name passed via /to tag Sent At: Delivery time stamp in EST (GMT factor included) Has Failed Because: Short Description verbiage of fax error reason (see Appendix C) Report Version: Identifier of confirmation version



Alternate Machine Friendly Confirmation Style

Email Header Destination Email: Confirmation Email Address from Account Profile Subject: Contains fax result and destination fax number Email Body Protocol: Internal Use (Always = MF) Version: Identifier of Confirmation version Key: Billing Code passed via /bc tag Status: Short Description verbiage of fax error reason (see Appendix D) Status_info: Hardware Result Code from Brooktrout Faxout Board Delivery_Time: Last attempted date time in GMT Page Count: Number of pages delivered Billing Rate: Rate per page (if applicable) Phone_number: Destination fax number attempted Transmit_Time: Duration of fax transmission Reference_Number: Transaction ID number generated by Protus Fax System

PIPSUGVFAPI.05.04

Virtual Fax™ API User Guide - Protus

Documents

Transcript of Virtual Fax™ API User Guide - Protus