Web Service API
The GFI FaxMaker Web Service API enables you to develop your own applications that can connect and send/receive faxes via GFI FaxMaker.
NOTE
This topic is aimed at users that are familiar with Visual Studio, XML Web Services and SOAP technologies.
Requirements and important notes
- To create the API, use a development environment that supports XML Web Services and SOAP.
- GFI FaxMaker Web Services API uses port 8555 for HTTPHypertext Transfer Protocol communication between the application and GFI FaxMaker. This port can be opened automatically when running the GFI FaxMaker Configuration Wizard. For more information refer to Web Services API port.
- Access the GFI FaxMaker Web Service through XML Web Services over HTTP port 8555, using the URLThe Uniform Resource Locator is the address of a web page on the world wide web.:
http://<GFI FaxMaker Server>:8555/faxmaker/wsapi
Replace<GFI FaxMaker Server>with the name or IP address of the GFI FaxMaker server. For examplehttp://myfaxserver.mydomain.local:8555/faxmaker/wsapi. - Alternatively you may use a secure connection over HTTPS. For more information refer to Using Web Services API over a secure HTTPS connection.
- From the Licensed Users node register users that will use the Web Service API. Use these users' credentials in API calls. For more information refer to Web Service API users.
- Received faxes that are routed to users registered for Web Service API are stored in the Web Service API queue and not forwarded to the user via email. Configure routing rules to route faxes that are to be picked up by the Web Service API to the registered users. For more information refer to Fax routing.
- GFI FaxMaker retains received faxes in the Web Service API queue for 30 days. Expired faxes cannot be fetched by the Web Service API. For more information refer to Managing the Web Service API queue.
Getting started
In Visual Studio, create a C# Windows or Console Application and from Solution Explorer, add a web or service reference (depending on the Visual Studio version).
When prompted to enter the service URL, key in the GFI FaxMaker Web Service URL WSDL link. This is composed of the GFI FaxMaker Web Service URL as defined in the Requirements section above and add ?singleWsdl. For example, http://myfaxserver.mydomain.com:8555/faxmaker/wsapi?singleWsdl
When prompted to enter the namespace or a web reference name, key in FMWSAPI.
After creating the application, open app.config. Find the address http://127.0.0.1:8555/faxmaker/wsapi and change it with the value of your GFI FaxMaker Web Service URL. For example, http://myfaxserver.mydomain.com:8555/faxmaker/wsapi
Save changes and proceed to use the following namespace classes as typical C# classes.
API Functions
SendFax
Use this function to send a fax. The function returns an array of FaxJobIDs. For every recipient specified, a FaxJobID is created. This ID gives the ability to monitor the status of that fax sent to that particular recipient.
FMResult SendFax
(
FMUser user,
UserDetails senderdetails,
List<UserDetails> recipients,
MessageDetails messagedetails,
out FaxJobID[] faxjobids
);
Parameters:
| Parameter | Description |
|---|---|
|
The web API user credentials. |
|
|
senderdetails |
The details of the user. |
|
recipients[] |
List of recipients of the fax. |
|
messagedetails |
The fax to be send. |
Return Values:
| Parameter | Description |
|---|---|
|
Return the result of the function. |
|
|
Faxjobids |
An array of |
CheckForUnreadFaxes
Use this function to get the list of faxes in the queue. This queue contains all those faxes which were not previously downloaded.
Every element in this list contains only the details of that fax and not the actual fax image. To download the fax use GetNextFax().
Parameters:
| Parameter | Description |
|---|---|
|
The web API user credentials. |
Return Values:
| Parameter | Description |
|---|---|
|
Return the result of the function. |
|
|
receivedfaxes |
An array of |
GetSendingFaxStatusUpdates
Use this function to obtain the status of a fax which was previously submitted using the SendFax API.
Parameters:
| Parameter | Description |
|---|---|
|
The web API user credentials. |
|
| The unique identifier assigned to each recipient of an outbound fax. |
Return Values:
| Parameter | Description |
|---|---|
|
Return the result of the function. |
|
|
Returns the status of the fax. |
GetNextFax
Use this method to get the oldest fax from the queue. This queue contains all those faxes which were not previously downloaded.
When getting the oldest fax, it is not automatically deleted from queue. Call DeleteFax() to delete the oldest fax, enabling you to get the next fax. If the oldest fax is not deleted you will receive the same fax again.
Parameters:
| Parameter | Description |
|---|---|
|
The web API user credentials. |
Return Values:
| Parameter | Description |
|---|---|
|
Return the result of the function. |
|
|
faxdetails |
A ReceivedFaxDetails which hold the details of the fax |
|
fax |
The fax image. |
GetNextFaxByCriteria
Use this method to get the oldest fax from the queue, according to the criteria specified. This queue contains all those faxes which were not previously downloaded.
When getting the oldest fax, it is not automatically deleted from queue. Call DeleteFax() to delete the oldest fax, enabling you to get the next fax. If the oldest fax is not deleted you will receive the same fax again.
FMResult GetNextFaxByCriteria
(
FMUser user,
SearchCriteria criteria,
stringcriteriavalue,
out ReceivedFaxDetails faxdetails,
out FileData fax
);
Parameters:
| Parameter | Description |
|---|---|
|
The web API user credentials. |
|
|
Criteria |
DTMFDual-tone multi-frequency signalling or Remote ID |
|
Criteriavalue |
The value of the criteria |
Return Values:
| Parameter | Description |
|---|---|
|
Return the result of the function. |
|
|
faxdetails |
A ReceivedFaxDetails which hold the details of the fax |
|
Fax |
A FileData contains the actual fax image data. |
DeleteFax
Use this function to delete a particular fax.
Parameters:
| Parameter | Description |
|---|---|
|
The web API user credentials. |
|
|
FaxID |
The ID of the fax to delete. This value can be retrieved from the output of |
Return Values:
| Parameter | Description |
|---|---|
|
Return the result of the function. |
Classes
UserDetails
This class contains the details of a recipient/sender.
All fields are optional, except for Faxnumber property when used as a recipient.
| Data members | Type | Description |
|---|---|---|
|
Firstname |
String | The first name. |
|
Lastname |
String | The last name. |
|
Company |
String | Company name. |
|
Department |
String | Department name. |
|
Faxnumber |
String | The fax number. |
|
|
String | The email address. |
MessageDetails
An object of this class holds the details of a new fax.
All fields are optional, except for the BillingCode when Billing is enabled.
| Data members | Type | Description |
|---|---|---|
|
Subject |
String | The fax subject. |
|
Schedule |
DateTime | A specific date & time when to send the fax. |
|
Priority |
FaxPriority |
Set the fax's priority. |
|
BillingCode |
String |
Specifies the billing code. Required when Billing is enabled. |
|
Resolution |
FaxResolution | The resolution to use. |
| String | By default, a fax is sent using the default coverpage configured in GFI FaxMaker. Use this parameter to send fax using a particular coverpage. | |
|
FrontCoverNote |
String | By default, fax is sent using the default Front covernote configured in GFI FaxMaker. Use this parameter to send fax using a particular Front covernote. |
|
FaxLine |
Integer | Use this parameter to request the fax to be sent on a particular fax line. Specify the fax line number as configured in GFI FaxMaker Configuration. |
|
UseFaxLine |
FaxLineType | Set to FaxLine or demand line if required. Otherwise, set to none. The line to be used has to be specified with the FaxLine property. |
| String | Enter a custom personal header that is added to the fax header at the top of the fax. | |
| String |
Specifies a single line of TextAPI command. For a list of TextAPI commands, refer to TextAPI commands. |
|
|
MessageBodyFile. |
FileData | An instance of FileData, holding a text file containing the message body of the fax. |
|
Attachments |
List<FileData> | Array of attachments. |
FMUser
A Web API user.
| Data members | Type | Description |
|---|---|---|
|
|
String |
The user's email address as configured in Licensed users. The user must be a registered Web API user. |
|
Password |
String |
In Active Directory, this is the configured user's password. In SMTPSimple Mail Transport Protocol environments the password is an auto generated GUID available from the Licensed users node for registered Web API users. |
FaxJobID
GFI FaxMaker assigns a unique identifier to each recipient of an outbound fax. Use this identifier to monitor the status of a fax.
| Data members | Type | Description |
|---|---|---|
|
Recipient |
String | The recipient's fax number. |
|
ID |
String | The unique identifier assigned by GFI FaxMaker. |
ReceivedFaxDetails
An object of this class is received when GetNextFax() is called.
| Data members | Type | Description |
|---|---|---|
|
FaxUID |
String | Fax unique identifier. Use this identifier when deleting a fax. |
|
WhenReceived |
DateTime | Date and time when fax was received. |
|
NosPages |
String | Number of pages received. |
|
Resolution |
FaxResolution | The received fax resolution. |
|
RemoteID |
String | The sender's fax machine name. |
| String | The DTMF/DID extension number of the receiving line. |
FileData
An object of such class holds the actual data of a file.
| Data members | Type | Description |
|---|---|---|
|
Filename |
String |
The file name of the file; mainly used to determine the file format. |
|
Data |
Byte[] |
The file data in a byte array. |
FaxSendingStatus
An object of this class is returned when GetSendingFaxStatusUpdates() is called.
| Data members | Type | Description |
|---|---|---|
|
FaxUID |
String | Fax unique identifier. |
|
RemoteID |
String | The sender's fax machine name. |
|
CurrentTransmissionPage |
Integer | The page that is currently being transmitted. After a fax is sent, this returns the total number of pages transmitted. |
| TotalPages | Integer | The total number of pages that make up the fax. |
| Status | SendingStatus | The current status of the fax. |
Enums
FaxPriority
| Value | Description |
|---|---|
|
None |
No priority specified. |
|
Low |
Low priority. |
|
Normal |
Normal priority. |
|
High |
High priority. |
|
VeryHigh |
Very high priority. |
FaxLineType
| Value | Description |
|---|---|
|
None |
No demand fax line required. |
|
Faxline |
Reserved. |
|
Demand |
Send the fax strictly from a particular line (FaxLine attribute) |
FaxResolution
| Value | Description |
|---|---|
|
NonSet |
No custom fax resolution specified. |
|
High |
High resolution. |
|
Normal |
Normal fax resolution. |
SearchCriteria
| Value | Description |
|---|---|
|
RemoteID |
Search faxes by caller ID or fax machine name. |
|
DTMF |
Search faxes by the extension number of the receiving line. |
SendingStatus
| Value | Description |
|---|---|
|
Preparing |
Processing and converting the content to fax. |
|
ConvertingAttachment |
Converting the attachment to fax format. |
|
Pending |
The fax is in queue, ready to be faxed. |
|
Sending |
Fax in transmission. |
|
Sent |
Fax was sent. |
|
Failed |
Transmission failed. |
|
Cancelled |
The fax job was cancelled. |
FMResult
| Value | Description |
|---|---|
|
Success |
Function completed successfully. |
|
Failure |
Function failed. |
|
UserNotValid |
The user details are not valid. |
|
DBError |
Error writing to or reading from database. |
|
FaxImageNotFound |
The required fax image was not found. |
|
NoSender |
No or invalid sender specified. |
|
NoRecipients |
No or invalid recipient specified. |
|
InvalidFaxDescription |
One or more required fields were not supplied. |
To help you get started with developing custom applications for GFI FaxMaker Web Service API, refer to the samples provided.