Virtual Fax™ User Guide
Web Services
Virtual Fax User Guide – Web Services
Table of Contents
WEB SERVICES PRIMER ..................................................................................................................1
WEB SERVICES ....................................................................................................................................1
WEB METHODS ....................................................................................................................................1
SOAP ENCAPSULATION .......................................................................................................................1
DOCUMENT/LITERAL FORMAT.............................................................................................................1
URL ENCODING...................................................................................................................................1
SECURE POSTING .................................................................................................................................1
VIRTUAL FAX WEB METHODS ......................................................................................................2
SENDING ..............................................................................................................................................3
Web Method - SendSingleFax().....................................................................................................3
REPORTING ..........................................................................................................................................8
Web Method – GetDetailFaxStatus() .............................................................................................8
Web Method – GetDetailFaxStatusCSV() ...................................................................................13
STATUS AND ERROR CODE DESCRIPTIONS .........................................................................................15
Status Result Codes ......................................................................................................................15
Transmission Result Codes ..........................................................................................................16
RECEIVING .........................................................................................................................................17
Web Method - DownloadAvailableFaxesInfo() ...........................................................................17
Web Method - DownloadZipFaxesByTime()...............................................................................20
Web Method - DownloadZipFaxesByTime()...............................................................................23
Web Method - DownloadZipFaxesByTime()...............................................................................25
Web Method - DeleteFaxesByTime() ..........................................................................................28
Web Method - DeleteFaxesByID() ..............................................................................................30
APPENDIX A – RETURN CODES AND MESSAGES ...................................................................33
VIRTUAL FAX WEB METHOD RETURN MESSAGES.............................................................................33
APPENDIX B – LOCATIONS OF RESOURCES............................................................................36
SENDING ............................................................................................................................................36
REPORTING ........................................................................................................................................36
RECEIVING .........................................................................................................................................36
APPENDIX C – SUPPORTED FILE FORMATS............................................................................37
PIPSUGVFWS.09.05
i
Virtual Fax User Guide – Web Services
Web Services Primer
Web Services
Web Services are a collection of web based applications that provide business
functionality through an internet connection. They use standard Internet protocols
such as HTTP, XML, and SOAP to provide interconnectivity and interoperability
between companies. Web Services provide component based functionality that can
be used and re-used without regard to the details of the service implementation. Web
Services run on a web server, and allow client programs to access the hosted
applications by calling Web Methods.
Web Methods
Web methods provide the mechanism for a remote application to access (or consume)
a specific application running on Web Services. Each of Protus’ web methods is
available through a URI and is accessed via either a plain HTTP POST request or
SOAP over HTTP POST. When using plain HTTP POST, the data will be structured
using URL Encoding. When using SOAP over HTTP POST the data will be
structured as an XML document. Web methods will typically provide responses
structured as XML documents for both plain HTTP and SOAP over HTTP posts,
which will at a minimum indicate the success or failure status of the post.
SOAP Encapsulation
SOAP (Simple Object Access Protocol) defines an envelope format and rules for
describing its contents. SOAP is used here as a wrapper for posting requests to and
responses from the various web methods contained in the web services.
Document/Literal Format
The posting methods provided support only Document/Literal formatted messages. If
you are using a SOAP toolkit that does not support Document/Literal, we recommend
that you write your own HTTP POST or SOAP over HTTP POST requests.
URL Encoding
URL Encoding is the structure typically employed when posting with plain HTTP.
This means that the argument’s name and value should be separated by an equal sign
( = ) and each such pairing separated by an ampersand ( & ). Neither the equal sign
nor ampersand should be included as data when URL encoding. This is in
accordance with the World Wide Web consortium specifications. For example:
UserID=12345&Password=abcdefg
Secure Posting
Since all of our HTTP posting methods described actually employ HTTPS, security
of all data transmitted over our Web Services is ensured.
PIPSUGVFWS.09.05
1
Virtual Fax User Guide – Web Services
Virtual Fax Web Methods
Virtual Fax Web Services are Internet fax services based on industry standard XML
technology. Virtual Fax Web Services are designed for developers to enable them to
create secure applications that send, receive, and report on faxes over the World Wide
Web.
Virtual Fax Web Services expose the following simple web methods for developers to
integrate Virtual Faxing into their applications:
•
•
•
Sending
o Fax Submission – SendSingleFax()
Reporting
o Detailed – GetDetailFaxStatus()
o Detailed CSV – GetDetailFaxStatusCSV()
Receiving
o Query Available Faxes – DownloadAvailableFaxInfo()
o Download by Time – DownloadZipFaxesByTime()
o Download by ID – DownloadZipFaxesByID()
o Delete by Time – DeleteFaxesByTime()
o Delete by ID – DeleteFaxesByID()
PIPSUGVFWS.09.05
2
Virtual Fax User Guide – Web Services
Sending
Virtual Fax Sending enables an organization or business to automate the distribution
of transactional faxes and to integrate the service within their own business systems,
applications, or software. Virtual Fax Sending web methods convert an electronic
document and deliver it as a fax to its destination, with no fax hardware or software
required, using simple Internet protocols.
File types supported for the document to be faxed include Microsoft Word (.doc) and
Adobe Acrobat (.pdf). For more information on supported file types, see “Supported
File Formats”. Multiple documents, having the same or different file types, may be
included in a single submission.
Web Method - SendSingleFax()
This web method is provided to send a fax, consisting of one or more document files,
to a single fax destination.
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/xmlsubmitter/messaging.asmx
Inputs
Element Hierarchy
single_fax_info
single_fax_info
SchemaVersion
single_fax_info
login_key
single_fax_info
login_key
user_id
single_fax_info
login_key
user_email
single_fax_info
login_key
user_password
single_fax_info
single_fax_options
single_fax_info
single_fax_options
billing_code
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Root element of the SendSingleFax XML document. Contains:
login_key, single_fax_options, fax_recipient, document_list
One
String
NA
NA
The version of the schema being used. Currently this value must be set
to 1.1 as that is the only version supported.
One
Container
NA
NA
User identification and authentication. Contains: user_id, user_email,
user_password.
One
Integer
1 to
NA
2000000000
Use either user_id or user_email, not both. Contains the id number of
the user account.
One
String
60 chars
NA
Use either user_id or user_email, not both. Contains the email address
assigned to the account user.
One
String
20 chars
NA
Contains the password associated with the account user id.
One
Container
NA
NA
Special options to be applied to the fax send. Contains: billing_code,
from_name, start_hour, end_hour, paper_size, tiff_image_flag,
resolution, cover_page.
Zero or
String
128 chars
Dependant on account
One
settings
Alphanumeric identifier that appears in reports, but not on the faxed
document.
3
Virtual Fax User Guide – Web Services
Element Hierarchy
Instances
single_fax_info
single_fax_options
from_name
Zero or
String
Dependant on account
One
settings
Appears in fax banner to identify who sent the fax.
Zero or
Boolean
true | false
false
One
Specifies that the system must convert the document to legal size
paper. The default is letter size for all documents.
Zero or
Enumeration
Letter |
Letter
One
Legal |
A4
Specifies that the paper size that the document to be converted uses.
The default is letter size for all documents.
Zero or
Boolean
true | false
true
One
Specifies that the document provided is a TIFF image requiring no
further conversion.
Zero or
Enumeration
low | high
low
One
Specifies whether the document should be converted to a low (draft) or
high (fine) resolution TIFF image.
Zero or
Container
NA
NA
One
Identifies whether or not a cover page should be inserted at the
beginning of a fax transmission. The following fields are
automatically set from either system generated defaults or values set
elsewhere in the submission: To, From, Fax Number, Date, and
Number of Pages. The Cover page tags and Subject line are specified
below. The Comments area of the cover page is populated by the first
document in the document list (which must be plain text). Contains:
cover_page_name, cover_page_tags, cover_page_subject.
Zero or
String
15
NA
One
Identifies the type of template or custom cover page used for the
transmission. The system assigns a unique code to the cover page
selected by a user. If omitted, the standard template is used. If a name
is specified and does not exist in the account, the request will be
rejected. To view the list of customized cover pages per account you
must manually login to the account. Click on Send a Single or
Broadcast fax, click on Advanced Settings, under the "Use this cover
page" drop down you will find all the names of the custom cover pages
available for that account in brackets.
Zero or
String
5
NA
One
Sets the use of the cover page flags. The flags are: U-Urgent, R-Reply,
I-Information, C-Please Comment, A-Reply ASAP. Any combination
of the letters URICA may be used.
Zero or
String
50
NA
One
The subject line that will appear on the cover page.
One
Container
NA
NA
Describes the recipient of the fax document. Contains:
fax_recipient_number, fax_recipient_name.
One
Numeric
7 - 20 digits NA
String
Contains the destination fax number beginning with the country code.
single_fax_info
single_fax_options
legal_size_flag
single_fax_info
single_fax_options
paper_size
single_fax_info
single_fax_options
tiff_image_flag
single_fax_info
single_fax_options
resolution
single_fax_info
single_fax_options
cover_page
single_fax_info
single_fax_options
cover_page
cover_page_name
single_fax_info
single_fax_options
cover_page
cover_page_tags
single_fax_info
single_fax_options
cover_page
cover_page_subject
single_fax_info
fax_recipient
single_fax_info
fax_recipient
fax_recipient_number
PIPSUGVFWS.09.05
Type
Length /
Values
Description
50 chars
Default
4
Virtual Fax User Guide – Web Services
Element Hierarchy
Instances
single_fax_info
fax_recipient
fax_recipient_name
Zero or
String
None
One
Contains the destination name which will appear in the To field on the
fax banner.
One
Container
NA
NA
Specifies the list of one or more documents to be faxed. Contains:
document.
One to 25 Encoded File
NA
NA
Contains document to be faxed as an encoded file, as defined by the
document attributes. Has attributes: document_content_type,
document_encoding_type, document_extension.
One
String
NA
NA
Defines content type of document. For example, text/plain.
single_fax_info
document_list
single_fax_info
document_list
document
single_fax_info
document_list
document
attribute:
document_content_type
single_fax_info
document_list
document
attribute:
document_encoding_type
single_fax_info
document_list
document
attribute:
document_extension
One
Type
Length /
Values
Description
50 chars
Default
Enumeration
base64 |
NA
uuencode |
quotedprintable |
bin – hex |
none
Defines encoding type used to encode the document.
One
Alphanumeric 3 chars
NA
Provides file extension of original document.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/xmlwebservices/xmlsubmitter/messaging.asmx HTTP/1.1
Host: www.protusfax.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "https://www.protus.com/WebServices/Messaging/2005/2/SendSingleFax"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SendSingleFax xmlns="https://www.protus.com/WebServices/Messaging/2005/2">
<XmlDocument>string</XmlDocument>
</SendSingleFax>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/xmlwebservices/xmlsubmitter/messaging.asmx/SendSingleFax HTTP/1.1
Host: www.protusfax.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
XmlDocument=string
PIPSUGVFWS.09.05
5
Virtual Fax User Guide – Web Services
Where “string” represents an XML file, such as:
<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">
<SchemaVersion>1.1</SchemaVersion>
<login_key>
<user_id>12345</user_id>
<user_password>abcd123</user_password>
</login_key>
<single_fax_options>
<billing_code>Cust 123</billing_code>
<from_name>John Doe</from_name>
<tiff_image_flag>false</tiff_image_flag>
<resolution>high</resolution>
<fax_recipient>
<fax_recipient_number>16135551234</fax_recipient_number>
<fax_recipient_name>Jane Doe</fax_recipient_name>
</fax_recipient>
<document_list>
<document document_content_type="text/plain" document_encoding_type="none"
document_extension="txt">Hi Jane,
Here’s the documentation you asked for.
John</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>
Outputs
Element Hierarchy
SendSingleFaxResult
SendSingleFaxResult
Header
SendSingleFaxResult
Header
ErrorFlag
SendSingleFaxResult
Header
ReturnMessage
SendSingleFaxResult
TransactionID
SendSingleFaxResult
NumberOfDestinations
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Root element of the SendSingleFax response. Contains: Header,
TransactionID, NumberOfDestinations.
One
Container
NA
NA
Status information resulting from the SendSingleFax submission.
Contains: ErrorFlag, ReturnMessage.
One
Boolean
true|false
NA
Specifies whether an error occurred. True indicates an error; false
indicates no error.
One
String
?
NA
Return message for SendSingleFax submission. See “Return
Messages” for details.
One
Numeric
7 digits
NA
String
Unique number that can be used to identify the submitted job in all
reports.
One
Integer
1
NA
Number of destinations submitted with fax request. Always 1 for
SendSingleFax.
PIPSUGVFWS.09.05
6
Virtual Fax User Guide – Web Services
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SendSingleFaxResponse
xmlns="https://www.protus.com/WebServices/Messaging/2005/2">
<SendSingleFaxResult>
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<TransactionID>string</TransactionID>
<NumberOfDestinations>int</NumberOfDestinations>
</SendSingleFaxResult>
</SendSingleFaxResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<SendResponse xmlns="https://www.protus.com/WebServices/Messaging/2005/2">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<TransactionID>string</TransactionID>
<NumberOfDestinations>int</NumberOfDestinations>
</SendResponse>
PIPSUGVFWS.09.05
7
Virtual Fax User Guide – Web Services
Reporting
Virtual Fax Messaging Services tracks faxes once a user successfully submits a fax.
The system tracks in real time from submission to successful delivery to a fax
machine and stores tracking information for up to a year after completion.
The Virtual Fax Reporting Service can be polled on a regular basis for complete
information regarding one or many fax transmissions through one simple request.
Reports can be generated based upon one master account, or on all the users within a
master account.
Detailed fax transmission reports are available based upon the following criteria:
•
The transaction identifier provided by the Virtual Fax Service
The transaction ID is returned to the user once the Virtual Fax Messaging Service
successfully receives the SendSingleFax request. The system generates detailed
reports based on one transaction ID or on a comma-separated list of up to 100
transaction IDs. Note that if any transaction IDs are specified, all other filter
specifications are ignored.
•
A unique identifier assigned to the fax transmission by the user (also
called the Billing Code and/or reference ID)
Upon fax submission, the user can assign a unique identifier to the fax
transmission. A fax transmission report can be generated based on the unique ID
assigned by the user. Note that if a billing code is specified, then a period of less
than 24 hours must also be specified for the report.
•
A specified time period
All fax transmissions within a certain period can be reported on using the Virtual
Fax Reporting Services. Note that a period of less than 24 hours must be
specified for the report.
•
The destination fax numbers
Reports can be generated based on one fax destination or on a comma-separated
list of up to 100 fax destinations. Note that if a fax number is specified, then a
period of less than 24 hours must also be specified for the report.
By default, if only the account number, password, and AllUsers flag are specified,
then the Virtual Fax Reporting Services will report on the last 24-hour period of fax
transmissions.
Web Method – GetDetailFaxStatus()
This web method is provided to request a detailed report on transmissions to
individual fax destinations. This report requires the User ID and Password for
PIPSUGVFWS.09.05
8
Virtual Fax User Guide – Web Services
authentication. For non-master account IDs, the report only contains data applicable
to that user. For master account IDs, account holder, user IDs, the report contains a
choice of data applicable only to that user or data applicable to all users associated
with that account. For master agent accounts, the report contains all master account
activities.
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/xmlreports/statusreports.asmx
Inputs
Element Hierarchy
UserID
UserPassword
AllUsersFlag
BillingCodeFilter
TransactionIDListFilter
StartTimeStampFilter
EndTimeStampFilter
FaxNumberListFilter
Instances
Type
Length / Values
Default
Description
One
integer
1 to 200000000
NA
Specifies the User ID of the user that sent the fax request.
One
String
20
NA
Specifies the password associated with the User ID.
One
Boolean
true|false
None
Specifies if the report includes data applicable to all users associated
with the account. This is a required field.
One
String
NA
None
Specifies if the report is to include transactions for a particular billing
code. If a BillingCodeFilter is specified, then a StartTimeStampFilter
and EndTimeStampFilter must be specified and must be less than a 24hour period.
One
String
None
Specifies if the report only includes details associated with a particular
transaction ID for a fax transmission. Commas should separate lists of
up to 100 transaction IDs. If transaction IDs are submitted, than all
other filters are ignored.
One
DateTime
NA
Specifies if the report only includes details associated with a
transmission that started at a particular time. If no filters are specified,
then a default of the last 24 hours is assumed.
One
DateTime
NA
None
Specifies if the report only includes details associated with a
transmission that ended at a particular time. If no filters are specified,
then a default of the last 24 hours is assumed.
One
Numeric
NA
String
Specifies if the report only includes details associated with a
transmission sent to a particular fax number. Commas should separate
lists of up to 100 fax numbers. If a FaxNumberListFilter is specified,
then a StartTimeStampFilter and EndTimeStampFilter must be
specified and must be less than a 24-hour period.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/xmlwebservices/xmlreports/statusreports.asmx HTTP/1.1
Host: www.protusfax.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "https://www.protus.com/WebServices/Reports/2005/9/GetDetailFaxStatus"
<?xml version="1.0" encoding="utf-8"?>
PIPSUGVFWS.09.05
9
Virtual Fax User Guide – Web Services
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetDetailFaxStatus xmlns="https://www.protus.com/WebServices/Reports/2005/9">
<UserID>int</UserID>
<UserPassword>string</UserPassword>
<AllUsersFlag>boolean</AllUsersFlag>
<BillingCodeFilter>string</BillingCodeFilter>
<TransactionIDListFilter>string</TransactionIDListFilter>
<StartTimeStampFilter>string</StartTimeStampFilter>
<EndTimeStampFilter>string</EndTimeStampFilter>
<FaxNumbersListFilter>string</FaxNumbersListFilter>
</GetDetailFaxStatus>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/xmlwebservices/xmlreports/statusreports.asmx/GetFaxStatusCSV HTTP/1.1
Host: www.protusfax.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
UserID=string&UserPassword=string&AllUsersFlag=string&BillingCodeFilter=string&Transac
tionIDListFilter=string&StartTimeStampFilter=string&EndTimeStampFilter=string&FaxNumbe
rsListFilter=string
Outputs
Element Hierarchy
GetDetailFaxStatusResult
GetDetailFaxStatusResult
Header
GetDetailFaxStatusResult
Header
ErrorFlag
GetDetailFaxStatusResult
Header
ReturnMessage
GetDetailFaxStatusResult
FaxDetail
GetDetailFaxStatusResult
FaxDetail
AccountID
GetDetailFaxStatusResult
FaxDetail
UserID
GetDetailFaxStatusResult
FaxDetail
TransactionType
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Root element of the GetDetailFaxStatus response.
One
Container
NA
NA
Status information resulting from the GetDetailFaxStatusResult web
method call. Contains: ErrorFlag, ReturnMessage.
One
Boolean
true|false
NA
Specifies whether an error occurred. True indicates an error; false
indicates no error.
One
String
NA
NA
Return message for fax submission. See “Virtual Fax Web Method
Return Messages” for more information.
Zero or
Container
NA
NA
More
Each instance of FaxDetail contains a list of fax detail information for
a fax transmission. Contains: AccountID, UserID, TransactionType,
TransactionID, SubTransactionID, StatusCode, ErrorCode,
ReferenceID, ReceivedTimestamp, DeliveredTimestamp,
NumberofPages, ToText, DestinationFaxNumber,
DestinationCountryCode, Duration, FileSize, Retries, Cost.
One
Integer
1 to
NA
2000000000
Specifies the master account ID. This ID is the billed entity. Multiple
UserIDs map to one AccountID.
One
Integer
1 to
NA
2000000000
Specifies the user ID. In the case where an AccountID is inputted in
the request, the UserID will equal to the AccountID.
One
String
4
NA
Indicates the type of transaction being reported, for example WFFA
indicates Web Fax with a fax attachment. For a complete list of
transaction types see the Appendix ****ADD THE REF****
10
Virtual Fax User Guide – Web Services
Element Hierarchy
GetDetailFaxStatusResult
FaxDetail
TransactionID
GetDetailFaxStatusResult
FaxDetail
SubTransactionID
GetDetailFaxStatusResult
FaxDetail
StatusCode
GetDetailFaxStatusResult
FaxDetail
ErrorCode
GetDetailFaxStatusResult
FaxDetail
ReferenceID
GetDetailFaxStatusResult
FaxDetail
ReceivedTimestamp
GetDetailFaxStatusResult
FaxDetail
DeliveredTimestamp
GetDetailFaxStatusResult
FaxDetail
NumberOfPages
GetDetailFaxStatusResult
FaxDetail
ToText
GetDetailFaxStatusResult
FaxDetail
DestinationNumber
GetDetailFaxStatusResult
FaxDetail
DestinationCountryCode
GetDetailFaxStatusResult
FaxDetail
Duration
GetDetailFaxStatusResult
FaxDetail
FileSize
GetDetailFaxStatusResult
FaxDetail
Retries
GetDetailFaxStatusResult
FaxDetail
Cost
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Integer
1 to
NA
2000000000
Indicates the unique identifier for the single fax transmission.
One
Integer
1 to
1
2000000000
Will always equal 1 for single fax transmissions.
One
Integer
1 to
One
2000000000
Indicates the status of a fax in progress. See “Status Result Codes” for
more information.
Integer
1 to
NA
2000000000
Indicates any errors that may have occurred during transmission. For
example, 0 indicates a successful fax transmission. See “Transmission
Error Codes” for more information.
One
String
1 to 128
NA
characters
Specifies the individual destination billing code or reference field.
One
Date Time
NA
Indicates the time a single fax transmission record is created on the
system.
One
Date Time
NA
Indicates the time a successful fax transmission is completed to the
destination fax number.
One
Integer
NA
Specifies the number of pages in the fax transmission.
One
String
NA
Specifies the name included in the “To” field.
String
11
NA
Specifies the destination number of a single destination fax.
One
Numeric
NA
String
Indicates the country code portion of a fax number. For fax numbers
in North America, the country code includes the country and area
codes, for example 1613.
One
Integer
1 to
NA
2000000000
Specifies the duration, in seconds, of a fax transmission.
One
Integer
1 to
NA
2000000000
Specifies the size of the file, in bytes, of the entire fax transmission.
Integer
-1 to 9
NA
Indicates the number of retries remaining for a transmission. Retries
are statically configured at the UserID level. Contact your account
representative for more information. The number of Retries defaults to
-1 for fax transmissions that have used and failed the number of retries
set at the UserID level.
One
NA
Specifies the total cost of the fax transmission including taxes if
applicable.
11
Virtual Fax User Guide – Web Services
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetDetailFaxStatusResponse
xmlns="https://www.protus.com/WebServices/Reports/2005/9">
<GetDetailFaxStatusResult xmlns="http://www.protus.com/Reports">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<FaxDetail>
<AccountID>int</AccountID>
<UserID>int</UserID>
<TransactionType>string</TransactionType>
<TransactionID>int</TransactionID>
<SubTransactionID>int</SubTransactionID>
<StatusCode>int</StatusCode>
<ErrorCodeID>int</ErrorCodeID>
<ReferenceID>string</ReferenceID>
<ReceivedTimeStamp>dateTime</ReceivedTimeStamp>
<DeliveredTimeStamp>dateTime</DeliveredTimeStamp>
<NumberOfPages>int</NumberOfPages>
<ToText>string</ToText>
<DestinationNumber>string</DestinationNumber>
<DestinationCountryCode>int</DestinationCountryCode>
<Duration>int</Duration>
<FileSize>int</FileSize>
<Retries>int</Retries>
<Cost>double</Cost>xml</FaxDetail>
<FaxDetail>
<AccountID>int</AccountID>
<UserID>int</UserID>
<TransactionType>string</TransactionType>
<TransactionID>int</TransactionID>
<SubTransactionID>int</SubTransactionID>
<StatusCode>int</StatusCode>
<ErrorCodeID>int</ErrorCodeID>
<ReferenceID>string</ReferenceID>
<ReceivedTimeStamp>dateTime</ReceivedTimeStamp>
<DeliveredTimeStamp>dateTime</DeliveredTimeStamp>
<NumberOfPages>int</NumberOfPages>
<ToText>string</ToText>
<DestinationNumber>string</DestinationNumber>
<DestinationCountryCode>int</DestinationCountryCode>
<Duration>int</Duration>
<FileSize>int</FileSize>
<Retries>int</Retries>
<Cost>double</Cost>xml</FaxDetail>
</GetDetailFaxStatusResult>
</GetDetailFaxStatusResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<FaxDetailList xmlns="http://www.protus.com/Reports">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
PIPSUGVFWS.09.05
12
Virtual Fax User Guide – Web Services
<FaxDetail>
<AccountID>int</AccountID>
<UserID>int</UserID>
<TransactionType>string</TransactionType>
<TransactionID>int</TransactionID>
<SubTransactionID>int</SubTransactionID>
<StatusCode>int</StatusCode>
<ErrorCodeID>int</ErrorCodeID>
<ReferenceID>string</ReferenceID>
<ReceivedTimeStamp>dateTime</ReceivedTimeStamp>
<DeliveredTimeStamp>dateTime</DeliveredTimeStamp>
<NumberOfPages>int</NumberOfPages>
<ToText>string</ToText>
<DestinationNumber>string</DestinationNumber>
<DestinationCountryCode>int</DestinationCountryCode>
<Duration>int</Duration>
<FileSize>int</FileSize>
<Retries>int</Retries>
<Cost>double</Cost>xml</FaxDetail>
<FaxDetail>
<AccountID>int</AccountID>
<UserID>int</UserID>
<TransactionType>string</TransactionType>
<TransactionID>int</TransactionID>
<SubTransactionID>int</SubTransactionID>
<StatusCode>int</StatusCode>
<ErrorCodeID>int</ErrorCodeID>
<ReferenceID>string</ReferenceID>
<ReceivedTimeStamp>dateTime</ReceivedTimeStamp>
<DeliveredTimeStamp>dateTime</DeliveredTimeStamp>
<NumberOfPages>int</NumberOfPages>
<ToText>string</ToText>
<DestinationNumber>string</DestinationNumber>
<DestinationCountryCode>int</DestinationCountryCode>
<Duration>int</Duration>
<FileSize>int</FileSize>
<Retries>int</Retries>
<Cost>double</Cost>xml</FaxDetail>
</FaxDetailList>
Web Method – GetDetailFaxStatusCSV()
This web method is provided to request a detailed report on transmissions to
individual and broadcast destinations in CSV format. This report requires the User
ID and Password for authentication. For non-master user IDs, the report only
contains data applicable to that user. For master user IDs, account holder, the report
contains a choice of data applicable only to that user or data applicable to all users
associated with that account. For master agent accounts, the report contains all
master account activities.
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/xmlreports/statusreports.asmx
Inputs
The inputs are the same as the inputs for the GetDetailFaxStatus web method.
Element Hierarchy
UserID
UserPassword
PIPSUGVFWS.09.05
Instances
Type
Length / Values
Default
Description
One
Integer
1 to 200000000
NA
Specifies the User ID of the user that sent the fax request.
One
String
20
NA
Specifies the password associated with the User ID.
13
Virtual Fax User Guide – Web Services
Element Hierarchy
AllUsersFlag
BillingCodeFilter
TransactionIDListFilter
StartTimeStampFilter
EndTimeStampFilter
FaxNumberListFilter
Instances
Type
Length / Values
Default
Description
One
Boolean
true|false
None
Specifies if the report includes data applicable to all users associated
with the account. This is a required field.
One
String
NA
None
Specifies if the report only includes transactions for a particular billing
code. If a BillingCodeFilter is specified, then a StartTimeStampFilter
and EndTimeStampFilter must be specified and must be less than a 24
hour time period.
One
String
None
Specifies if the report only includes details associated with a particular
transaction ID for a fax transmission. Lists of transaction IDs should
be separated by commas. A maximum of 100 transaction IDs in the
list are supported. If transaction IDs are submitted, than all other
filters are ignored.
One
DateTime
None
Specifies if the report only includes details associated with a
transmission that started at a particular time. If no filters are specified,
then a default of the last 24 hours is assumed.
One
DateTime
NA
None
Specifies if the report only includes details associated with a
transmission that ended at a particular time. If no filters are specified,
then a default of the last 24 hours is assumed.
One
Numeric
None
String
Specifies if the report is to include details associated with a
transmission sent to a particular fax number. Lists of Fax numbers
should be separated by commas. A maximum of 100 fax numbers in
the list are supported. If a FaxNumberListFilter is specified, then a
StartTimeStampFilter and EndTimeStampFilter must be specified and
must be less than a 24 hour time period.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/xmlwebservices/xmlreports/statusreports.asmx HTTP/1.1
Host: www.protusfax.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "https://www.protus.com/WebServices/Reports/2005/9/GetFaxStatusCSV"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetFaxStatusCSV xmlns="https://www.protus.com/WebServices/Reports/2005/9">
<UserID>int</UserID>
<UserPassword>string</UserPassword>
<AllUsersFlag>boolean</AllUsersFlag>
<BillingCodeFilter>string</BillingCodeFilter>
<TransactionIDListFilter>string</TransactionIDListFilter>
<StartTimeStampFilter>string</StartTimeStampFilter>
<EndTimeStampFilter>string</EndTimeStampFilter>
<FaxNumbersListFilter>string</FaxNumbersListFilter>
</GetFaxStatusCSV>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/xmlwebservices/xmlreports/statusreports.asmx/GetFaxStatusCSV HTTP/1.1
Host: www.protusfax.com
PIPSUGVFWS.09.05
14
Virtual Fax User Guide – Web Services
Content-Type: application/x-www-form-urlencoded
Content-Length: length
UserID=string&UserPassword=string&AllUsersFlag=string&BillingCodeFilter=string&Transac
tionIDListFilter=string&StartTimeStampFilter=string&EndTimeStampFilter=string&FaxNumbe
rsListFilter=string
Outputs
Element Hierarchy
Instances
GetFaxStatusCSVResponse
One
Container
NA
Root element of the
One
String
NA
NA
Results of query in CSV format. Provides the same returned values as
in the GetDetailFaxStatus Web Method in a comma separated values
string.
GetFaxStatusCSVResponse
GetFaxStatusCSVResult
Type
Length /
Values
Description
NA
Default
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetFaxStatusCSVResponse
xmlns="https://www.protus.com/WebServices/Reports/2005/9">
<GetFaxStatusCSVResult>string</GetFaxStatusCSVResult>
</GetFaxStatusCSVResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<string xmlns="https://www.protus.com/WebServices/Reports/2005/9">string</string>
Status and Error Code Descriptions
Status Result Codes
Status
Code
10
15
16
17
20
25
30
40
Description
Fax Received
Fax Waiting for application conversion process to begin.
Awaiting Approval
Broadcast on Hold until future release date.
Done Lead/Tiff
Checking Credit
Failed Lead
Locked Mail
PIPSUGVFWS.09.05
15
Virtual Fax User Guide – Web Services
50
60
70
80
90
100
110
115
120
125
130
140
145
150
160
170
180
190
Done Mail
Failed Mail
Done Fax Away
Failed Fax Away
Failed Err
Statement
Faxing Err
Email Broadcast
Ready
Checking Progress
Fax transmission was completed successfully.
Failure Mail To Fax
Broadcast Suspended
Reject Mail To Fax
Out Faxing
In Faxing
In Faxed
Fax transmission failed.
Transmission Result Codes
Error
Code
0
1
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
21
22
Description
Successful Transmission
Unspecified Error Occurred
Line is Busy
No Answer
No Dial tone on Call Attempt
Voice (Human) Answered Call instead of Fax Tone
Unspecified Error Occurred
Fax TIFF File Bad Format or Corrupt
Fax Transmission Error (Cutoff)
Telco Error (Reorder Busy)
Telco Error (T1 Cannot Provide Dialing Allow)
Attachment Failed Conversion
Excluded Number or Number Blocked from Receiving
Answering Machine instead of Fax Tone
Invalid Number
Incorrect Password Used in Email Request
Unknown Error
Fax Transmission was Cut Off
Account Requires Billing Code and Billing Code was not
Used
PIPSUGVFWS.09.05
16
Virtual Fax User Guide – Web Services
Receiving
Electronic documents received on a Virtual Fax number can be stored in a temporary
on-line secure archive until they need to be retrieved. Virtual Fax web methods
provide easy and immediate access to download these fax documents. Online faxes
can be retrieved by their identification number, or by the date and time received.
Complementary web methods are provided to access a listing of available faxes
stored online, or to delete faxes once they are no longer required.
Web Method - DownloadAvailableFaxesInfo()
This web method is provided to identify what faxes are available to the user to
download or delete as required. Since a user can have more than one fax number, it
allows for specification of faxes received on one or more fax numbers, or all fax
numbers at once. The information provided is intended to help the user make
decisions about what action to take next; for example, knowing the fax ID of the
available faxes lets the user determine whether a specific fax has previously been
downloaded. In addition, knowing the number of pages or duration of a fax helps in
the decision of whether to download the fax individually or as part of a larger group.
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/archivingfaxes/archiving.asmx
Inputs
Element Hierarchy
UserID
UserPassword
FaxNumbersCSVList
Instances
Type
Length /
Default
Values
Description
One
Integer
1 to
NA
2000000000
Contains the account user id number.
One
Alphanumeric 20
NA
Contains the password associated with the account user id.
One
CSV List
NA
NA
Contains zero or more comma separated fax numbers; ie.
6135551234,6135551111. Data is returned on each fax number given.
May be empty, in which case, data is returned on all fax numbers
available to the user.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx HTTP/1.1
Host: www.protusfax.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction:
"https://www.protus.com/WebServices/ArchivingFaxes/2004/11/DownloadAvailableFaxesInfo"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
PIPSUGVFWS.09.05
17
Virtual Fax User Guide – Web Services
<DownloadAvailableFaxesInfo
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<UserID>long</UserID>
<UserPassword>string</UserPassword>
<FaxNumbersCSVList>string</FaxNumbersCSVList>
</DownloadAvailableFaxesInfo>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx/DownloadAvailableFaxesInfo
HTTP/1.1
Host: www.protusfax.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
UserID=string&UserPassword=string&FaxNumbersCSVList=string
Outputs
Element Hierarchy
Header
Header
ErrorFlag
Header
ReturnMessage
FaxNumberFaxInfoList
FaxNumberFaxInfoList
attribute FaxNumber
FaxNumberFaxInfoList
FaxInfo
FaxNumberFaxInfoList
FaxInfo
FaxID
FaxNumberFaxInfoList
FaxInfo
ReceivedTime
FaxNumberFaxInfoList
FaxInfo
NumOfPages
FaxNumberFaxInfoList
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Header information providing status of request. Contains: ErrorFlag,
ReturnMessage
One
Boolean
true | false
NA
Indicates whether the request succeeded or failed. A value of “true”
indicates that the request failed.
One
Alphanumeric ?
NA
Status message describing result of request. See “Return Messages”
for details.
Zero or
Container
NA
NA
More
Each instance of FaxNumberInfoList contains a list of fax information
for a specific fax number. If no instances exist, it means that there are
no faxes stored, or the request failed. Has attributes: FaxNumber.
Contains: FaxInfo.
One
Numeric
?
NA
String
Identifies the receiving fax number for which the FaxNumberInfoList
contains information.
One or
Container
NA
NA
More
Each instance of FaxInfo contains information for a single fax
document received on the fax number defined by the encapsulating
FaxNumberInfoList. Contains: FaxID, ReceivedTime, NumOfPages,
Duration, SendingFax.
One
Numeric
?
NA
String
The Protus generated ID of the received fax. This value may be used
to later specify the fax for download or deletion.
One
DateTime
NA
NA
String
The date-time the fax was received by the Protus system.
One
Integer
?
NA
The number of pages in the received fax document.
One
Integer
?
NA
18
Virtual Fax User Guide – Web Services
Element Hierarchy
Instances
Type
Length /
Default
Values
Description
The duration of the received fax document in seconds.
FaxInfo
Duration
FaxNumberFaxInfoList
FaxInfo
SendingFax
One
Alphanumeric
?
NA
The identifier of the fax sender.
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadAvailableFaxesInfoResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<DownloadAvailableFaxesInfoResult>
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<FaxNumberFaxInfoList FaxNumber="string">
<FaxInfo>
<FaxID>string</FaxID>
<ReceivedTime>string</ReceivedTime>
<NumOfPages>int</NumOfPages>
<Duration>int</Duration>
<SendingFax>string</SendingFax>
</FaxInfo>
<FaxInfo>
<FaxID>string</FaxID>
<ReceivedTime>string</ReceivedTime>
<NumOfPages>int</NumOfPages>
<Duration>int</Duration>
<SendingFax>string</SendingFax>
</FaxInfo>
</FaxNumberFaxInfoList>
<FaxNumberFaxInfoList FaxNumber="string">
<FaxInfo>
<FaxID>string</FaxID>
<ReceivedTime>string</ReceivedTime>
<NumOfPages>int</NumOfPages>
<Duration>int</Duration>
<SendingFax>string</SendingFax>
</FaxInfo>
<FaxInfo>
<FaxID>string</FaxID>
<ReceivedTime>string</ReceivedTime>
<NumOfPages>int</NumOfPages>
<Duration>int</Duration>
<SendingFax>string</SendingFax>
</FaxInfo>
</FaxNumberFaxInfoList>
</DownloadAvailableFaxesInfoResult>
</DownloadAvailableFaxesInfoResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
PIPSUGVFWS.09.05
19
Virtual Fax User Guide – Web Services
<DownloadFaxesInfoResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<FaxNumberFaxInfoList FaxNumber="string">
<FaxInfo>
<FaxID>string</FaxID>
<ReceivedTime>string</ReceivedTime>
<NumOfPages>int</NumOfPages>
<Duration>int</Duration>
<SendingFax>string</SendingFax>
</FaxInfo>
<FaxInfo>
<FaxID>string</FaxID>
<ReceivedTime>string</ReceivedTime>
<NumOfPages>int</NumOfPages>
<Duration>int</Duration>
<SendingFax>string</SendingFax>
</FaxInfo>
</FaxNumberFaxInfoList>
<FaxNumberFaxInfoList FaxNumber="string">
<FaxInfo>
<FaxID>string</FaxID>
<ReceivedTime>string</ReceivedTime>
<NumOfPages>int</NumOfPages>
<Duration>int</Duration>
<SendingFax>string</SendingFax>
</FaxInfo>
<FaxInfo>
<FaxID>string</FaxID>
<ReceivedTime>string</ReceivedTime>
<NumOfPages>int</NumOfPages>
<Duration>int</Duration>
<SendingFax>string</SendingFax>
</FaxInfo>
</FaxNumberFaxInfoList>
</DownloadFaxesInfoResponse>
Web Method - DownloadZipFaxesByTime()
This web method will return all available faxes that were received between the start
and end times specified, for one or more fax numbers. The fax documents will be
returned in base64 encoded zip files, one per fax number.
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/archivingfaxes/archiving.asmx
Inputs
Element Hierarchy
UserID
UserPassword
FaxNumbersCSVList
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Integer
1 to
NA
2000000000
Contains the account user id number.
One
Alphanumeric 20
None
Contains the password associated with the account user id.
One
CSV List
NA
None
Contains zero or more comma separated fax numbers; ie.
6135551234,6135551111. Data is returned on each fax number given.
May be empty, in which case, data is returned on all fax numbers
20
Virtual Fax User Guide – Web Services
Element Hierarchy
Instances
Type
Length /
Values
Description
Default
available to the user.
StartTimestamp
EndTimestamp
One
DateTime
NA
None
The StartTimestamp should be between today’s date and today’s date
minus the number of days in the user account received fax archive
period.
One
DateTime
NA
None
The EndTimestamp should be between today’s date and today’s date
minus the number of days in the user account received fax archive
period.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx HTTP/1.1
Host: www.protusfax.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction:
"https://www.protus.com/WebServices/ArchivingFaxes/2004/11/DownloadZipFaxesByTime"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadZipFaxesByTime
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<UserID>long</UserID>
<UserPassword>string</UserPassword>
<FaxNumbersCSVList>string</FaxNumbersCSVList>
<StartTimestamp>dateTime</StartTimestamp>
<EndTimestamp>dateTime</EndTimestamp>
</DownloadZipFaxesByTime>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx/DownloadZipFaxesByTime
HTTP/1.1
Host: www.protusfax.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
UserID=string&UserPassword=string&FaxNumbersCSVList=string&StartTimestamp=string&EndTi
mestamp=string
Outputs
Element Hierarchy
Header
Header
ErrorFlag
Header
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Header information providing status of request. Contains: ErrorFlag,
ReturnMessage
One
Boolean
true | false
NA
Indicates whether the request succeeded or failed. A value of “true”
indicates that the request failed.
One
Alphanumeric ?
NA
21
Virtual Fax User Guide – Web Services
Element Hierarchy
ReturnMessage
ZipFile
ZipFile
NumberOfZippedFiles
ZipFile
FileName
ZipFile
FileExtension
ZipFile
FileContent
Instances
Type
Length /
Default
Values
Description
Status message describing result of request. See “Return Messages”
for details.
Zero or
Container
NA
NA
More
One instance of ZipFile will exist for each fax number that had
received faxes available under the specifications given in the request.
Contains NumberOfZippedFiles, FileName, FileExtension,
FileContent.
One
Integer
?
NA
Specifies how many individual files (fax documents) are contained
within the zip file.
One
Alphanumeric ?
NA
Suggested zip file name. This will be the same as the receiving fax
number.
One
Alphanumeric ?
NA
Suggested zip file extension. Will always be “.zip”.
One
base64 Binary NA
NA
Base64 encoded zip file. You will need to decode the contents of this
element and save the result as FileName+FileExtension.
The identifier of the fax sender.
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadZipFaxesByTimeResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<DownloadZipFaxesByTimeResult>
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
</DownloadZipFaxesByTimeResult>
</DownloadZipFaxesByTimeResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
PIPSUGVFWS.09.05
22
Virtual Fax User Guide – Web Services
<?xml version="1.0" encoding="utf-8"?>
<DownloadFaxesResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
</DownloadFaxesResponse>
Web Method - DownloadZipFaxesByTime()
This web method will return all available faxes that were received between the start
and end times specified, for one or more fax numbers. The fax documents will be
returned in base64 encoded zip files, one per fax number.
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/archivingfaxes/archiving.asmx
Inputs
Element Hierarchy
UserID
UserPassword
FaxNumbersCSVList
StartTimestamp
EndTimestamp
Instances
Type
Length /
Default
Values
Description
One
Integer
1 to
NA
2000000000
Contains the account user id number.
One
Alphanumeric 20
None
Contains the password associated with the account user id.
One
CSV List
NA
None
Contains zero or more comma separated fax numbers; ie.
6135551234,6135551111. Data is returned on each fax number given.
May be empty, in which case, data is returned on all fax numbers
available to the user.
One
DateTime
NA
None
The StartTimestamp should be between today’s date and today’s date
minus the number of days in the user account received fax archive
period.
One
DateTime
NA
None
The EndTimestamp should be between today’s date and today’s date
minus the number of days in the user account received fax archive
period.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx HTTP/1.1
Host: www.protusfax.com
PIPSUGVFWS.09.05
23
Virtual Fax User Guide – Web Services
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction:
"https://www.protus.com/WebServices/ArchivingFaxes/2004/11/DownloadZipFaxesByTime"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadZipFaxesByTime
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<UserID>long</UserID>
<UserPassword>string</UserPassword>
<FaxNumbersCSVList>string</FaxNumbersCSVList>
<StartTimestamp>dateTime</StartTimestamp>
<EndTimestamp>dateTime</EndTimestamp>
</DownloadZipFaxesByTime>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx/DownloadZipFaxesByTime
HTTP/1.1
Host: www.protusfax.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
UserID=string&UserPassword=string&FaxNumbersCSVList=string&StartTimestamp=string&EndTi
mestamp=string
Outputs
Element Hierarchy
Header
Header
ErrorFlag
Header
ReturnMessage
ZipFile
ZipFile
NumberOfZippedFiles
ZipFile
FileName
ZipFile
FileExtension
ZipFile
FileContent
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Header information providing status of request. Contains: ErrorFlag,
ReturnMessage
One
Boolean
true | false
NA
Indicates whether the request succeeded or failed. A value of “true”
indicates that the request failed.
One
Alphanumeric ?
NA
Status message describing result of request. See “Return Messages”
for details.
Zero or
Container
NA
NA
More
One instance of ZipFile will exist for each fax number that had
received faxes available under the specifications given in the request.
Contains NumberOfZippedFiles, FileName, FileExtension,
FileContent.
One
Integer
?
NA
Specifies how many individual files (fax documents) are contained
within the zip file.
One
Alphanumeric ?
NA
Suggested zip file name. This will be the same as the receiving fax
number.
One
Alphanumeric ?
NA
Suggested zip file extension. Will always be “.zip”.
One
base64 Binary NA
NA
Base64 encoded zip file. You will need to decode the contents of this
element and save the result as FileName+FileExtension.
The identifier of the fax sender.
24
Virtual Fax User Guide – Web Services
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadZipFaxesByTimeResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<DownloadZipFaxesByTimeResult>
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
</DownloadZipFaxesByTimeResult>
</DownloadZipFaxesByTimeResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<DownloadFaxesResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
</DownloadFaxesResponse>
Web Method - DownloadZipFaxesByTime()
This web method will return all available faxes that were received between the start
and end times specified, for one or more fax numbers. The fax documents will be
returned in base64 encoded zip files, one per fax number.
PIPSUGVFWS.09.05
25
Virtual Fax User Guide – Web Services
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/archivingfaxes/archiving.asmx
Inputs
Element Hierarchy
UserID
UserPassword
FaxNumbersCSVList
StartTimestamp
EndTimestamp
Instances
Type
Length /
Default
Values
Description
One
Integer
1 to
NA
2000000000
Contains the account user id number.
One
Alphanumeric 20
None
Contains the password associated with the account user id.
One
CSV List
NA
None
Contains zero or more comma separated fax numbers; ie.
6135551234,6135551111. Data is returned on each fax number given.
May be empty, in which case, data is returned on all fax numbers
available to the user.
One
DateTime
NA
None
The StartTimestamp should be between today’s date and today’s date
minus the number of days in the user account received fax archive
period.
One
DateTime
NA
None
The EndTimestamp should be between today’s date and today’s date
minus the number of days in the user account received fax archive
period.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx HTTP/1.1
Host: www.protusfax.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction:
"https://www.protus.com/WebServices/ArchivingFaxes/2004/11/DownloadZipFaxesByTime"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadZipFaxesByTime
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<UserID>long</UserID>
<UserPassword>string</UserPassword>
<FaxNumbersCSVList>string</FaxNumbersCSVList>
<StartTimestamp>dateTime</StartTimestamp>
<EndTimestamp>dateTime</EndTimestamp>
</DownloadZipFaxesByTime>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx/DownloadZipFaxesByTime
HTTP/1.1
Host: www.protusfax.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
UserID=string&UserPassword=string&FaxNumbersCSVList=string&StartTimestamp=string&EndTi
mestamp=string
PIPSUGVFWS.09.05
26
Virtual Fax User Guide – Web Services
Outputs
Element Hierarchy
Header
Header
ErrorFlag
Header
ReturnMessage
ZipFile
ZipFile
NumberOfZippedFiles
ZipFile
FileName
ZipFile
FileExtension
ZipFile
FileContent
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Header information providing status of request. Contains: ErrorFlag,
ReturnMessage
One
Boolean
true | false
NA
Indicates whether the request succeeded or failed. A value of “true”
indicates that the request failed.
One
Alphanumeric ?
NA
Status message describing result of request. See “Return Messages”
for details.
Zero or
Container
NA
NA
More
One instance of ZipFile will exist for each fax number that had
received faxes available under the specifications given in the request.
Contains NumberOfZippedFiles, FileName, FileExtension,
FileContent.
One
Integer
?
NA
Specifies how many individual files (fax documents) are contained
within the zip file.
One
Alphanumeric ?
NA
Suggested zip file name. This will be the same as the receiving fax
number.
One
Alphanumeric ?
NA
Suggested zip file extension. Will always be “.zip”.
One
base64 Binary NA
NA
Base64 encoded zip file. You will need to decode the contents of this
element and save the result as FileName+FileExtension.
The identifier of the fax sender.
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadZipFaxesByTimeResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<DownloadZipFaxesByTimeResult>
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
</DownloadZipFaxesByTimeResult>
PIPSUGVFWS.09.05
27
Virtual Fax User Guide – Web Services
</DownloadZipFaxesByTimeResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<DownloadFaxesResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
<ZipFile>
<NumberOfZippedFiles>int</NumberOfZippedFiles>
<FileName>string</FileName>
<FileExtension>string</FileExtension>
<FileContent>base64Binary</FileContent>
</ZipFile>
</DownloadFaxesResponse>
Web Method - DeleteFaxesByTime()
This web method will delete all available faxes that were received between the start
and end times specified, for one or more fax numbers.
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/archivingfaxes/archiving.asmx
Inputs
The inputs are the same as the inputs for the DownloadZipFaxesByTime web method.
Element Hierarchy
UserID
UserPassword
FaxNumbersCSVList
StartTimestamp
EndTimestamp
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Integer
1 to
NA
2000000000
Contains the account user id number.
One
Alphanumeric 20
None
Contains the password associated with the account user id.
One
CSV List
NA
None
Contains zero or more comma separated fax numbers; ie.
6135551234,6135551111. Data is returned on each fax number given.
May be empty, in which case, data is returned on all fax numbers
available to the user.
One
DateTime
NA
None
The StartTimestamp should be between today’s date and today’s date
minus the number of days in the user account received fax archive
period.
One
DateTime
NA
None
28
Virtual Fax User Guide – Web Services
Element Hierarchy
Instances
Type
Length /
Default
Values
Description
The EndTimestamp should be between today’s date and today’s date
minus the number of days in the user account received fax archive
period.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx HTTP/1.1
Host: www.protusfax.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction:
"https://www.protus.com/WebServices/ArchivingFaxes/2004/11/DeleteFaxesByTime"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DeleteFaxesByTime
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<userID>long</userID>
<UserPassword>string</UserPassword>
<FaxNumbersCSVList>string</FaxNumbersCSVList>
<StartTimestamp>dateTime</StartTimestamp>
<EndTimestamp>dateTime</EndTimestamp>
</DeleteFaxesByTime>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx/DeleteFaxesByTime HTTP/1.1
Host: www.protusfax.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
userID=string&UserPassword=string&FaxNumbersCSVList=string&StartTimestamp=string&EndTi
mestamp=string
Outputs
Element Hierarchy
Header
Header
ErrorFlag
Header
ReturnMessage
DeletedFaxesList
DeletedFaxesList
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Header information providing status of request. Contains: ErrorFlag,
ReturnMessage
One
Boolean
true | false
NA
Indicates whether the request succeeded or failed. A value of “true”
indicates that the request failed.
One
Alphanumeric ?
NA
Status message describing result of request. See “Return Messages”
for details.
Zero or
Container
NA
NA
More
List of fax IDs that were deleted. Each fax ID is contained by an
instance of the FaxID element. If no faxes were found to be deleted,
the DeletedFaxesList element will not be returned. Has attributes:
NumberOfDeletedFaxes. Contains: FaxID.
One
Integer
?
NA
29
Virtual Fax User Guide – Web Services
Element Hierarchy
attribute
NumberOfDeletedFaxes
DeletedFaxesList
FaxID
Instances
Type
Length /
Default
Values
Description
Specifies how many individual faxes were deleted.
One or
Numeric
?
More
String
Fax ID number of a deleted fax.
NA
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DeleteFaxesByTimeResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<DeleteFaxesByTimeResult>
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<DeletedFaxesList NumberOfDeletedFaxes="int">
<FaxID>string</FaxID>
<FaxID>string</FaxID>
</DeletedFaxesList>
</DeleteFaxesByTimeResult>
</DeleteFaxesByTimeResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<DeleteFaxesResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<DeletedFaxesList NumberOfDeletedFaxes="int">
<FaxID>string</FaxID>
<FaxID>string</FaxID>
</DeletedFaxesList>
</DeleteFaxesResponse>
Web Method - DeleteFaxesByID()
This web method will delete faxes specified by a comma delimited fax ID list.
Location
This Web Service is located at:
https://www.protusfax.com/protus/xmlwebservices/archivingfaxes/archiving.asmx
PIPSUGVFWS.09.05
30
Virtual Fax User Guide – Web Services
Inputs
The inputs are the same as the inputs for the DownloadZipFaxesByID web method.
Element Hierarchy
UserID
UserPassword
FaxIDList
Instances
Type
Length /
Default
Values
Description
One
Integer
1 to
NA
2000000000
Contains the account user id number.
One
Alphanumeric 20
None
Contains the password associated with the account user id.
One
CSV List
NA
None
Contains one or more comma separated received fax ID numbers; ie.
7034756,7034757.
HTTP Post Requests
Follow this guideline when posting with SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx HTTP/1.1
Host: www.protusfax.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction:
"https://www.protus.com/WebServices/ArchivingFaxes/2004/11/DeleteFaxesByID"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DeleteFaxesByID
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<userID>long</userID>
<UserPassword>string</UserPassword>
<FaxIDList>string</FaxIDList>
</DeleteFaxesByID>
</soap:Body>
</soap:Envelope>
Follow this guideline when posting without SOAP:
POST /protus/XMLWebServices/archivingfaxes/archiving.asmx/DeleteFaxesByID HTTP/1.1
Host: www.protusfax.com
Content-Type: application/x-www-form-urlencoded
Content-Length: length
userID=string&UserPassword=string&FaxIDList=string
Outputs
The outputs of the DeleteFaxesByID method are identical to the DeleteFaxesByTime
method. They are shown here again for consistency.
Element Hierarchy
Header
Header
ErrorFlag
Header
PIPSUGVFWS.09.05
Instances
Type
Length /
Default
Values
Description
One
Container
NA
NA
Header information providing status of request. Contains: ErrorFlag,
ReturnMessage
One
Boolean
true | false
NA
Indicates whether the request succeeded or failed. A value of “true”
indicates that the request failed.
One
Alphanumeric ?
NA
31
Virtual Fax User Guide – Web Services
Element Hierarchy
ReturnMessage
DeletedFaxesList
DeletedFaxesList
attribute
NumberOfDeletedFaxes
DeletedFaxesList
FaxID
Instances
Type
Length /
Default
Values
Description
Status message describing result of request. See “Return Messages”
for details.
Zero or
Container
NA
NA
More
List of fax IDs that were deleted. Each fax ID is contained by an
instance of the FaxID element. If no faxes were found to be deleted,
the DeletedFaxesList element will not be returned. Has attributes:
NumberOfDeletedFaxes. Contains: FaxID.
One
Integer
?
NA
Specifies how many individual faxes were deleted.
One or
Numeric
?
More
String
Fax ID number of a deleted fax.
NA
HTTP Post Response
The response to a SOAP over HTTP post will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DeleteFaxesByIDResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<DeleteFaxesByIDResult>
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<DeletedFaxesList NumberOfDeletedFaxes="int">
<FaxID>string</FaxID>
<FaxID>string</FaxID>
</DeletedFaxesList>
</DeleteFaxesByIDResult>
</DeleteFaxesByIDResponse>
</soap:Body>
</soap:Envelope>
The response to an HTTP post without SOAP will look like the following:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<DeleteFaxesResponse
xmlns="https://www.protus.com/WebServices/ArchivingFaxes/2004/11">
<Header>
<ErrorFlag>boolean</ErrorFlag>
<ReturnMessage>string</ReturnMessage>
</Header>
<DeletedFaxesList NumberOfDeletedFaxes="int">
<FaxID>string</FaxID>
<FaxID>string</FaxID>
</DeletedFaxesList>
</DeleteFaxesResponse>
PIPSUGVFWS.09.05
32
Virtual Fax User Guide – Web Services
Appendix A – Return Codes and Messages
Virtual Fax Web Method Return Messages
The return messages are divided in three categories:
1. Successful Return Messages – The user request has been validated and received
successfully.
2. User Error Messages – The user request contains errors. The request needs to be
corrected before re-submitting.
3. Internal Error Messages – An error has occurred that does not appear to be a
User error. Please, notify support.
Successful Return
Messages
Description
Action
M2000: Faxes Received
Successfully
Faxes were found that
match the specification
in the request.
None
M2001: Faxes Deleted
Successfully
The faxes that were
specified were
successfully deleted as
requested.
None
M2003: No Received
Faxes Found
No faxes were found
that match the
specification in the
request.
None
Your single fax request
has been received
successfully.
None
M2008: The Requested
Report Was Generated
Successfully
The requested report
was generated
successfully.
None
M2009: An Empty Report
Was Generated
Successfully
The requested report
did not return any
results. This may
happen if the
Transaction ID
specified was not
found.
Verify that the correct
Transaction ID was
specified in the
request and try again.
User Error Messages
Description
Action
U1006: Invalid Fax
Number
The Fax Number
specified in the
request is invalid or
does not exist.
Specify a valid Fax
Number.
U1007: Start and End
Timestamps Should Be
Between <min>,<max>
The date range
specified must be
within the date range
for faxes archived by
the account. <min> and
<max> will be replaced
by the actual
corresponding
timestamps.
Ensure that the date
range being specified
is within the date
range for which
received faxes are
being archived.
U1011: Invalid User ID
The user specified an
invalid User ID.
Specify a valid User
ID.
M2005: Single Fax
Request Received
Successfully
PIPSUGVFWS.09.05
33
Virtual Fax User Guide – Web Services
User Error Messages
Description
Action
U1012: Invalid Master
Account ID
The user specified an
invalid Master Account
ID.
Specify a valid Master
ID.
U1013: Invalid Password
The user specified an
invalid Password.
Specify a valid
Password.
U1014: The Sent
TimeStamp Format is
Invalid
The user specified Sent
TimeStamp Format is
invalid.
Specify a valid Sent
TimeStamp.
U1015: Requested Faxes
Size Exceed The Limit
<size> Bytes
The size of the
requested faxes exceeds
the limit for
downloading. <size>
will be replaced by the
actual size of the
limit in bytes.
If requesting multiple
faxes, try requesting
them individually or
contact Support for
alternative means of
obtaining the fax(es).
U1018: Invalid User
Email
The user specified an
invalid email.
Specify a valid email.
U1022: The Input Xml
File Is Not Valid
The user sent an
invalid Xml file.
Fix the Xml file. The
return message will
contain additional
information to pinpoint
the location of the
error.
U1023: The Xml Input
File Does Not Confirm
To The Schema
The user sent a valid
Xml file, but this file
does not conform to
Protus XML Schemas.
Fix the Xml file. The
return message will
contain additional
information to pinpoint
the location of the
error.
U1027: The Fax Number
Is Not Numeric
The user specified a
non-numeric fax number.
Use only numeric fax
numbers.
U1028: No Attached
Documents To Fax
The user did not attach
any documents to fax.
Attach at least one
document to fax.
U1037: The
SchemaVersion Value is
Invalid
The Schema version was
not recognized.
Currently, the only two
valid schema versions
are “1.0” and "1.1".
U1038: The Start
TimeStamp Should be
less than the End
TimeStamp
The Start TimeStamp
should be less than the
End TimeStamp.
Use a Start Timestamp
that occurs before the
End TimeStamp.
U1039: The Difference
Between Start and End
TimeStamp Should be
less than 744 hours
For Summary Reports,
the specified Start and
End TimeStamps have
more that 744 hours
(one month) difference
between them.
For Summary Reports,
specify Start and End
TimeStamps that have a
difference less than
744 hours (one month).
U1039: The Difference
Between Start and End
TimeStamp Should be
less than 24 hours
For Detailed Reports,
the specified Start and
End TimeStamps have
more that 24 hours
difference between
them.
For Detailed Reports,
specify Start and End
TimeStamps that have a
difference less than 24
hours.
U1041: The User
Submitted One Or More
Empty Documents
The user has submitted
one or more empty
documents.
No attached documents
can be empty. Remove
an empty document tag
or add a valid
document.
PIPSUGVFWS.09.05
34
Virtual Fax User Guide – Web Services
User Error Messages
Description
Action
U1102: The Comma
Delimited List Contains
Invalid Characters or
is Improperly
Formatted.
The CSV, comma
delimited, list
contains invalid
characters or improper
formatting.
Remove any invalid
characters and correct
formatting in the CSV
list.
U1105: You Have
Exceeded the Maximum
Allowed Items Of
TransactionIDListFilter
100.
The user has sent more
than 100 transaction
ids.
Use an additional
filter or input field
to narrow the report
results.
U1105: You Have
Exceeded the Maximum
Allowed Items Of
NumbersListFilter 100.
The user has sent more
than 100 phone or fax
numbers.
Use an additional
filter or input field
to narrow the report
results.
Internal Error Messages
Description
Action
An internal error
occurred from Protus
side
Please, notify support
and provide the Error
Code where XXXX
represents the actual
number. The phone
number and email for
support can be located
at www.protus.com.
EXXXX: An Internal
Error Occurred.
PIPSUGVFWS.09.05
35
Virtual Fax User Guide – Web Services
Appendix B – Locations of Resources
Sending
https://www.protusfax.com/protus/xmlwebservices/xmlsubmitter/messaging.asmx
https://www.protusfax.com/protus/xmlwebservices/xmlsubmitter/MessagingFeb2005.wsdl
https://www.protusfax.com/protus/xmlwebservices/xmlsubmitter/Schemas/SingleFaxSchemaSep2005.
xsd
Reporting
https://www.protusfax.com/protus/xmlwebservices/xmlreports/statusreports.asmx
Receiving
https://www.protusfax.com/protus/xmlwebservices/archivingfaxes/archiving.asmx
https://www.protusfax.com/protus/xmlwebservices/archivingfaxes/ArchivingFeb2005.wsdl
PIPSUGVFWS.09.05
36
Virtual Fax User Guide – Web Services
Appendix C – Supported File Formats
Virtual Fax supports the following file formats for use as attachments.
PIPSUGVFWS.09.05
•
Adobe PDF
•
AMI Draw Graphics
•
ANSI Text
•
Applix Graphics
•
Applix Spreadsheets
•
Applix Words
•
ASCII Text
•
Computer Graphics Metafile (CGM)
•
Corel Draw CDR (TIFF Header)
•
Corel QuattroPro
•
DCX
•
Encapsulated PostScript (EPS)
•
Enhanced Metafile (EMF)
•
HTML
•
IBM DCA/RFT
•
IBM Displaywrite
•
JPEG File Interchange Format
•
Lotus 1-2-3*
•
Lotus AMI Pro
•
Lotus AMI Professional Write Plus
•
Lotus Freelance*
•
Lotus Pic (PIC)
•
Lotus Word Pro*
•
Mac PICT (raster content)
•
MacPaint (MAC)
•
Maker Interchange Format (MIF)
•
Microsoft Excel
•
Microsoft Excel for Mac
•
Microsoft PowerPoint
•
Microsoft RTF
37
Virtual Fax User Guide – Web Services
•
Microsoft Windows Bitmap (BMP)
•
Microsoft Windows Write
•
Microsoft Word
•
Microsoft Word for Macintosh
•
Microsoft Works Spreadsheet
•
Microsoft Works
•
PC PaintBrush (PCX)
•
Portable Network Graphics (PNG)
•
SGI RGB
•
Sun Raster
•
TIFF
•
Truevision Targa
•
Unicode Text
•
WordPerfect
•
WordPerfect for Macintosh
•
WordPerfect Graphics (WPG)
•
XyWrite
* Supports a restricted set of features
PIPSUGVFWS.09.05
38
PIPSUGVFWS.09.05