Virtual Fax API User Guide

Virtual Fax API User Guide

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 PIPSUGVFAPI.05.04-1 - Protus IP Solutions

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. PIPSUGVFAPI.05.04-2 - Protus IP Solutions

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 contains elements pertaining to account identification and authentication user_id only one of either user_id or user_email is required 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 contains the email address assigned to an account user, which is a string of up to 60 characters. PIPSUGVFAPI.05.04-3 - Protus IP Solutions

user_password required contains the password associated with the account user, which is a string of up to 20 characters. single_fax_options required contains elements pertaining to any special options to be applied to the fax send billing_code 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 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 specifies the beginning hour of the allowed range of delivery hours value: integer 0-23 default: 0 end_hour specifies the end hour of the allowed range of delivery hours value: integer 0-23 default: 23 legal_size_flag specifies that document should be converted as legal size paper value: true false default: false PIPSUGVFAPI.05.04-4 - Protus IP Solutions

tiff_image_flag specifies that document provided is a tiff image requiring no further image conversion value: true false default: false resolution 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 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 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 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 PIPSUGVFAPI.05.04-5 - Protus IP Solutions

the subject line which will appear on the cover page value: string (50) default: none fax_recipient required contains elements pertaining to an individual fax broadcast destination fax_recipient_number required contains the destination fax number beginning with the country code value: numeric string of up to 20 digits fax_recipient_name 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 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 PIPSUGVFAPI.05.04-6 - Protus IP Solutions

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/cqagaaaaaaaaaaaaaaab AAAAJgAAAAAA AAAAEAAAKQAAAAEAAAD+////AAAAACcAAAD///////////////////////////////////// //////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////... (lines omitted)... AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</document> </document_list> </single_fax_info> PIPSUGVFAPI.05.04-7 - Protus IP Solutions

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/ls=landscapeboolean@virtualfax.com From: protusaccountemail@customerisp.com 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. PIPSUGVFAPI.05.04-8 - Protus IP Solutions

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. PIPSUGVFAPI.05.04-9 - Protus IP Solutions

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 23 rd 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. PIPSUGVFAPI.05.04-10 - Protus IP Solutions

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 1 st 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. PIPSUGVFAPI.05.04-11 - Protus IP Solutions

Example Email In this example, the single fax automated email is coming from jdoe@ispsrus.com, 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. PIPSUGVFAPI.05.04-12 - Protus IP Solutions

Sample Fax Cover Page Virtual Fax API User Guide PIPSUGVFAPI.05.04-13 - Protus IP Solutions

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. PIPSUGVFAPI.05.04-14 - Protus IP Solutions

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 1 st 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 PIPSUGVFAPI.05.04-15 - Protus IP Solutions

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 PIPSUGVFAPI.05.04-16 - Protus IP Solutions

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 1 st 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 PIPSUGVFAPI.05.04-17 - Protus IP Solutions

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-18 - Protus IP Solutions

PIPSUGVFAPI.05.04