Multitech FaxFinder FF240-IP Instruction Manual

COPYRIGHT AND TECHNICAL SUPPORT
1 Multi-Tech Systems, Inc. FaxFinder Web Service API Developer Guider
FaxFinder® Web Services API
FF240-IP, FF240, FF440, FF840 Developer Guide

LEGAL NOTICES AND CONTACT INFORMATION
FaxFinder Web Services API Developer Guide
2
FaxFinder Web Services API Developer Guide
FF240, FF440, FF840, FF240-IP
S000578, Version 1.1.02
Copyright
This publication may not be reproduced, in whole or in part, without prior expressed written permission from Multi-Tech Systems, Inc. All rights reserved.
Copyright © 2014, by Multi-Tech Systems, Inc.
Multi-Tech Systems, Inc. makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of
merchantability or fitness for any particular purpose. Furthermore, Multi-Tech Systems, Inc. reserves the right to revise this publication and to make
changes from time to time in the content hereof without obligation of Multi-Tech Systems, Inc. to notify any person or organization of such revisions or
changes. Check Multi-Tech’s web site for current versions of our product documentation.
Trademarks
Multi-Tech Registered Trademarks: FaxFinder, Multi-Tech, and the Multi-Tech logo.
All other products and technologies are the trademarks or registered trademarks of their respective holders.
Contacting Multi-Tech
Knowledge Base
The Knowledge Base provides immediate access to support information and resolutions for all Multi-Tech products. Visit
http://www.multitech.com/kb.go.
Support Portal
To create an account and submit a support case directly to our technical support team, visit: https://support.multitech.com
Support
Business Hours: M-F, 9am to 5pm CT
Country
By Email
By Phone
Europe, Middle East, Africa:
[e-mail]
+(44) 118 959 7774
U.S., Canada, all others:
[e-mail]
[phone] or [phone]
World Headquarters
Multi-Tech Systems, Inc.
2205 Woodale Drive
Mounds View, Minnesota 55112
Phone: [phone] or 800-328-9717
Fax: [phone]
Warranty
To read the warranty statement for your product, please visit: http://www.multitech.com/warranty.go.

CONTENTS
3
FaxFinder Web Services API Developer Guide
Contents
General Information ..................................................................................................................................................5
Authorization ...................................................................................................................................................................... 5
HTTPS .................................................................................................................................................................................. 5
Examples ............................................................................................................................................................................. 5
Additional Information........................................................................................................................................................ 5
Faxing........................................................................................................................................................................6
Scheduling a Fax.................................................................................................................................................................. 6
Viewing Fax Entries ............................................................................................................................................................. 8
Aborting a Fax Entry............................................................................................................................................................ 9
Rescheduling a Fax Entry .................................................................................................................................................. 10
User Functions .........................................................................................................................................................11
Viewing User Information ................................................................................................................................................. 11
Verify User......................................................................................................................................................................... 11
Adding a User.................................................................................................................................................................... 12
Editing a User .................................................................................................................................................................... 13
Contact and Group Functions ...................................................................................................................................14
Viewing Contacts............................................................................................................................................................... 14
Adding New Contacts........................................................................................................................................................ 15
Editing Contacts ................................................................................................................................................................ 15
Deleting Contacts.............................................................................................................................................................. 16
Viewing Contact IDs .......................................................................................................................................................... 16
Viewing Groups ................................................................................................................................................................. 17
Creating a New Group....................................................................................................................................................... 18
Editing Groups................................................................................................................................................................... 19
Deleting Groups ................................................................................................................................................................ 20
Viewing Group IDs............................................................................................................................................................. 20
Cover Page...............................................................................................................................................................22
Viewing Cover Pages ......................................................................................................................................................... 22
Fax Status ................................................................................................................................................................23
Viewing Modem, Channel, System, Printer, and Share Status ......................................................................................... 23
Viewing Channel Status (FF240-IP only) ........................................................................................................................... 24
Viewing Modem Status (FF240, FF440, FF840)................................................................................................................. 25
Viewing Inbound Fax Status.............................................................................................................................................. 25
Viewing Outbound Fax Status........................................................................................................................................... 26

CONTENTS
FaxFinder Web Services API Developer Guide
4
Logs.........................................................................................................................................................................29
Viewing Inbound Fax Logs................................................................................................................................................. 29
Viewing Outbound Fax Logs.............................................................................................................................................. 30
Viewing Call Log ................................................................................................................................................................ 32
Viewing Inbound or Outbound Log Count ........................................................................................................................ 34
FaxFinder Configuration ...........................................................................................................................................35
Viewing Inbound Routes ................................................................................................................................................... 35
Deleting Inbound Routes .................................................................................................................................................. 37
Editing Inbound Routes..................................................................................................................................................... 37
Viewing Store and Forward (T.37) Settings....................................................................................................................... 38
Editing Store and Forward (T.37) Settings ........................................................................................................................ 39
Viewing Modem Settings (FF240, FF440, or FF840) ......................................................................................................... 39
Editing Modem Settings (FF240, FF440, or FF840) ........................................................................................................... 40
Viewing SIP Settings (FF240-IP only)................................................................................................................................. 41
Editing SIP Settings (FF240-IP only)................................................................................................................................... 42
Viewing T38 Settings (FF240-IP only)................................................................................................................................ 42
Editing T38 Settings (FF240-IP only).................................................................................................................................. 43
Viewing Add Global Contacts Status of Non-Admin Users ............................................................................................... 44
About FaxFinder ......................................................................................................................................................45
Viewing Information about the FaxFinder ........................................................................................................................ 45
Elements .................................................................................................................................................................46
General Status Codes ........................................................................................................................................................ 46
Schedule Fax Element ....................................................................................................................................................... 46
Fax Entry Element ............................................................................................................................................................. 49
User Element..................................................................................................................................................................... 51
Contact Element................................................................................................................................................................ 52
Group Element .................................................................................................................................................................. 52
Inbound Routing Fax Element........................................................................................................................................... 53

GENERAL INFORMATION
5
FaxFinder Web Services API Developer Guide
General Information
This document illustrates the HTTP/XML communication between the FaxFinder Web Service (FFWS) and a client.
FFWS provides an interface to FFx40 and FF240-IP FaxFinders for client applications. Client applications can use
FFWS for sending faxes, managing contacts and monitoring fax status.
Authorization
All request requiring authorization must have the Authorization header set using Basic authentication. If this is not
set or the username or password are incorrect then “401 Unauthorized” is returned. See RFC 2617 for
implementation
HTTPS
The server supports HTTPS. Secure requests can be sent to the default HTTPS port 443.
Examples
Examples included in this document are also available through the Multi-Tech System Developer Resources
website at multitech.net. This site includes a developer forum.
Additional Information
For more information about these functions, consult your FaxFinder Administrator Guide or Help File.

FAXING
FaxFinder Web Services API Developer Guide
6
Faxing
Scheduling a Fax
An application can schedule a fax by posting the schedule fax XML to the ofax resource. If the fax is scheduled
successfully, a response is returned with the scheduled entries.
Notes:
Place each file that you want to attach as fax pages in an attachment element.
Inline attachments are attachments with the file contents inserted in the content tag.
Use base64 to encode inline attachments.
Unless the file basename is not unique among the attachments, the attachment name can usually be set to the
file basename.
The name is used primarily for error responses, so if you want to know which attachment failed, make this field
unique.
Set the attachment content type to match the type of the file being transferred. For Example, if attaching a PDF,
set the content type to “application/pdf”. FaxFinder uses content type to convert the file into fax pages. It does
not attempt to guess the content type.
Limits
Request size: 36MB
Maximum Recipients per Fax: 400
Query Parameters
None
HTTP Request Line
POST /ffws/v1/ofax HTTP/1.1
HTTP Response
Status Codes
201 Created
The fax has been created successfully.
400 Bad Request
Invalid request. The fax has not been scheduled. The response
message may provide more details.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
POST /ffws/v1/ofax HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
<?xml version=”1.0”encoding=”UTF-8”?>
<schedule_fax>
<cover_page>
<url>https://192.168.2.1/ffws/v1/data/cover_pages/default.pdf</url>
<enabled>true</enabled>
<subject>Test Subject</subject>
<comments>Test Message</comments>
</cover_page>
<sender>
<name>Sender Name</name>
<organization>Sender Org</organization>
<phone_number>218-555-3333</phone_number>
<fax_number>218-555-3334</fax_number>
<email_address>[email protected]</email_address>
</sender>
<recipient>
<name>Rcpt 1 Name</name>
<organization>Rcpt 1 Org</organization>
<fax_number>-218-555-3335</fax_number>

FAXING
7
FaxFinder Web Services API Developer Guide
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
<phone_number>218-555-3336</phone_number>
</recipient>
<attachment>
<location>inline</location>
<name>attachment1.txt</name>
<content_type>text/plain</content_type>
<content_transfer_encoding>base64</content_transfer_encoding>
<content>dGVzdA==</content>
</attachment>
<max_tries>3</max_tries>
<priority>3</priority>
<try_interval>30</try_interval>
<receipt>failure</receipt>
<receipt_attachment>none</receipt_attachment>
<schedule_all_at>2008-08-07T20:30:00</schedule_all_at>
</schedule_fax>
-----------------------------------
HTTP/1.1 201 Created
content-type: application/xml
<?xml version=”1.0”encoding=”UTF-8”?>
<response>
<message>Success</message>
<fax_entry>
<fax_entry_url>https://192.168.2.1/ffws/v1/ofax/0000001B/0000</fax_entry_url>
<fax_url>https://192.168.2.1/ffws/v1/ofax/0000001B</fax_url>
<state>preprocessing</state>
<schedule_message>New fax entry</schedule_message>
<created>2008-08-01 08:43:29</created>
<stime>2008-08-01 08:52:29</stime>
<try_number>1</try_number>
<agent>FFWS</agent>
<preview>https://192.168.2.1/ffws/v1/data/preview/0000001B-0000.pdf</preview>
<cover_page>
<url>https://192.168.2.1/ffws/v1/data/cover_pages/default.pdf</url>
<enabled>true</enabled>
<subject>Test Subject</subject>
<comments>Test Message</comments>
</cover_page>
<sender>
<username>admin</username>
<name>Sender Name</name>
<organization>Sender Org</organization>
<phone_number>218-555-3333</phone_number>
<fax_number>218-555-3334</fax_number>
<email_address>[email protected]</email_address>
</sender>
<recipient>
<name>Rcpt 1 Name</name>
<organization>Rcpt 1 Org</organization>
<fax_number>218-555-3335</fax_number>
<phone_number>218-555-3336</phone_number>
</recipient>
<max_tries>3</max_tries>
<priority>3</priority>
<try_interval>30</try_interval>
<receipt>failure</receipt>
<receipt_attachment>none</receipt_attachment>
<pages>0</pages>
<approver></approver>

FAXING
FaxFinder Web Services API Developer Guide
8
83
84
85
<approval_time></approval_time>
</fax_entry>
</response>
Viewing Fax Entries
Query
Parameters
all_users=true|false
An Admin level user can set this option to query all users instead of just faxes belonging
to the authenticated user.
complete_limit=LIMIT
Limit the number of completed faxes returned in a general query (/ffws/v1/ofax) to
LIMIT. By default the limit is 10. Faxes displayed in the completed list are (pre)viewable
and reschedulable.
class=pending|sending|complete
Retrieve faxes by class.
include_modem_info=true|false
Include modem level information in the response (init_time, connect_time, ...).
Requesting this information increases the response size. Modem information only
exists after the modem has completed at least one full attempt.
HTTP Request
Line
GET /ffws/v1/ofax HTTP/1.1
GET /ffws/v1/ofax/FAXKEY HTTP/1.1
GET /ffws/v1/ofax/FAXKEY/ENTRYKEY HTTP/1.1
HTTP Response
Status Codes
200 OK
Shows the fax entries.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
GET /ffws/v1/ofax HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
-----------------------------------
HTTP/1.1 200 OK
content-type: application/xml
<?xml version=”1.0” encoding=”UTF-8”?>
<response>
<message>Success</message>
<fax_entry>
<fax_entry_url>https://192.168.2.1/ffws/v1/ofax/0000001B/0000</fax_entry_url>
<fax_url>https://192.168.2.1/ffws/v1/ofax/0000001B</fax_url>
<state>aborted</state>
<schedule_message>Fax aborted by user</schedule_message>
<created>2008-08-01 08:43:29</created>
<stime>2008-08-01 08:52:29</stime>
<try_number>1</try_number>
<agent>FFWS</agent>
<preview>https://192.168.2.1/ffws/v1/data/preview/0000001B-0000.pdf</preview>
<cover_page>
<url>https://192.168.2.1/ffws/v1/data/cover_pages/default.pdf</url>
<enabled>true</enabled>
<subject>Test Subject</subject>

FAXING
9
FaxFinder Web Services API Developer Guide
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
<comments>Test Message</comments>
</cover_page>
<sender>
<username>admin</username>
<name>Sender Name</name>
<organization>Sender Org</organization>
<phone_number>218-555-3333</phone_number>
<fax_number>-218-555-3334</fax_number>
<email_address>[email protected]</email_address>
</sender>
<recipient>
<name>Rcpt 1 Name</name>
<organization>Rcpt 1 Org</organization>
<fax_number>218-555-3335</fax_number>
<phone_number>218-555-3336</phone_number>
</recipient>
<max_tries>3</max_tries>
<priority>3</priority>
<try_interval>30</try_interval>
<receipt>failure</receipt>
<receipt_attachment>none</receipt_attachment>
<pages>1</pages>
</fax_entry>
</response>
Aborting a Fax Entry
HTTP Request
Line
DELETE /ffws/v1/ofax/FAXKEY HTTP/1.1
DELETE /ffws/v1/ofax/FAXKEY/ENTRYKEY HTTP/1.1
HTTP Response
Status Codes
202 Accepted
An abort has been sent. The fax entry will be aborted if possible.
400 Bad Request
The fax specified could not be aborted. The user may not be the
owner of the fax or the fax could not be found.
Example
1
2
3
4
5
6
DELETE /ffws/v1/ofax/0000001B/0000 HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
-----------------------------------
HTTP/1.1 202 Accepted
content-type: application/xml

FAXING
FaxFinder Web Services API Developer Guide
10
Rescheduling a Fax Entry
Query
Parameters
at=TIME
TIME := now | DATETIME_UTC_URLENCODED
DATETIME_UTC_URLENCODED := YYYY-MM-DDTHH%3AMM%3ASS
HTTP Request
Line
PUT /ffws/v1/ofax/FAXKEY/ENTRYKEY?at=TIME HTTP/1.1
HTTP Response
Status Codes
202 Accepted
Attempting to reschedule faxes. There is no guarantee that all
entries will be rescheduled. For instance, entries that are
sending when the reschedule is received will not be
rescheduled.
400 Bad Request
The fax specified could not be rescheduled. The user may not be
the owner of the fax or the fax could not be found
Example
1
2
3
4
5
6
PUT /ffws/v1/ofax/0000001B/0000?at=2008-08-09T22%3A30%3A00 HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
-----------------------------------
HTTP/1.1 202 Accepted
content-type: application/xml