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

USER FUNCTIONS
11
FaxFinder Web Services API Developer Guide
User Functions
Viewing User Information
HTTP Request
Line
GET /ffws/v1/users/USERNAME HTTP/1.1
HTTP Response
Status Codes
200 OK
Shows user information.
403 Forbidden
Authenticated user does not have permission to view data
associated with username.
404 Not Found
No user found with that username.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
GET /ffws/v1/users/admin 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>
<user>
<user_url>https://dot3/ffws/v1/users/admin</user_url>
<name>Administrator</name>
<username>admin</username>
<email_address>[email protected]</email_address>
<phone_number>1234</phone_number>
<fax_number>2345</fax_number>
<organization>MTS</organization>
<default_cover_page_enabled>true</default_cover_page_enabled>
<default_cover_page_name>mts_template3.pdf</default_cover_page_name>
<priority>3</priority>
<max_attempts>3</max_attempts>
<interval>300</interval>
<receipt>failure</receipt>
<receipt_attachment>pdf</receipt_attachment>
</user>
</response>
Verify User
Authenticates the user and then simply returns 200 OK.
HTTP Request Line
GET /ffws/v1/verify HTTP/1.1
HTTP Response Status
Codes
200 OK
Verified

USER FUNCTIONS
FaxFinder Web Services API Developer Guide
12
Example
1
2
3
4
5
6
7
8
9
10
GET /ffws/v1/verify 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>Verified</message>
</response>
Adding a User
HTTP Request
Line
POST /ffws/v1/users HTTP/1.1
HTTP Response
Status Codes
200 OK
Created user.
403 Forbidden
Authenticated user does not have permission to change data
associated with username.
400 Bad Request
The provided XML is not valid.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
POST /ffws/v1/users HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
<?xml version=”1.0” encoding=”UTF-8”?>
<user>
<name>New User 1</name>
<username>user1</username>
<password>user1</password>
<email_address>[email protected]</email_address>
<phone_number>218-555-3333</phone_number>
<fax_number>218-555-3334</fax_number>
<organization>Example Org</organization>
<priority>1</priority>
<max_attempts>2</max_attempts>
<interval>600</interval>
<receipt>never</receipt>
<receipt_attachment>none</receipt_attachment>
</user>
-----------------------------------
<?xml version=”1.0” encoding=”UTF-8”?>
<response>
<message>Created</message>
<user>
<user_url>https://172.16.0.3/ffws/v1/users/user1</user_url>
<name>New User 1</name>
<username>user1</username>
<email_address>[email protected]</email_address>
<phone_number>218-555-3333</phone_number>
<fax_number>218-555-3334</fax_number>
<organization>Example Org</organization>
<default_cover_page_enabled>false</default_cover_page_enabled>
<default_cover_page_name></default_cover_page_name>
<priority>1</priority>

USER FUNCTIONS
13
FaxFinder Web Services API Developer Guide
34
35
36
37
38
39
<max_attempts>2</max_attempts>
<interval>600</interval>
<receipt>never</receipt>
<receipt_attachment>none</receipt_attachment>
</user>
</response>
Editing a User
HTTP Request
Line
PUT /ffws/v1/users/USERNAME HTTP/1.1
HTTP Response
Status Codes
200 OK
Modified successfully.
403 Forbidden
Authenticated user does not have permission to change data.
404 Not Found
User not found.
400 Bad Request
The provided XML is not valid.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
PUT /ffws/v1/users/USERNAME HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
<?xml version=”1.0”encoding=”UTF-8”?>
<user>
<name>Edit User</name>
<username>user1</username>
<password>user1</password>
<email_address>[email protected]</email_address>
<phone_number>218-555-3333</phone_number>
<fax_number>218-555-3334</fax_number>
<organization>Example Org</organization>
<priority>1</priority>
<max_attempts>2</max_attempts>
<interval>600</interval>
<receipt>never</receipt>
<receipt_attachment>none</receipt_attachment>
</user>
-----------------------------------
HTTP/1.1 200 OK
content-type: application/xml
<?xml version=”1.0”encoding=”UTF-8”?>
<response>
<message>Modified</message>
</response>

CONTACT AND GROUP FUNCTIONS
FaxFinder Web Services API Developer Guide
14
Contact and Group Functions
Viewing Contacts
Query
Parameters
limit=LIMIT
Limit the number of results to LIMIT.
offset=OFFSET
Skip OFFSET entries from the start. Only valid when limit is specified.
name=SUBSTR
fax_number=SUBSTR
phone_number=SUBSTR
organization=SUBSTR
Search for contacts by field name. If you specify more than one, they are
concatenated with AND.
order=field name
Sort contacts by field name. Not available for FFx30 models.
HTTP Request
Line
GET /ffws/v1/contacts/USERNAME HTTP/1.1
GET /ffws/v1/contacts/USERNAME/ID HTTP/1.1
GET /ffws/v1/contacts/global_contact_list HTTP/1.1
GET /ffws/v1/contacts/global_contact_list/ID HTTP/1.1
HTTP Response
Status Codes
200 OK
Shows contact information.
403 Forbidden
Authenticated user does not have permission to view data
associated with username.
404 Not Found
No user found with that username.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
GET /ffws/v1/contacts/admin 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>
<contact>
<contact_url>https://192.168.2.1/ffws/v1/contacts/admin/3</contact_url>
<name>Contact Name</name>
<fax_number>218-555-3335</fax_number>
<phone_number>218-555-3336</phone_number>
<organization>Contacts Org</organization>
</contact>
</response>

CONTACT AND GROUP FUNCTIONS
15
FaxFinder Web Services API Developer Guide
Adding New Contacts
HTTP Request
Line
POST /ffws/v1/contacts/USERNAME HTTP/1.1
HTTP Response
Status Codes
200 OK
Created
403 Forbidden
Authenticated user does not have permission to change data
associated with username.
404 Not Found
No user found with that username.
400 Bad Request
The provided XML is not valid.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
POST /ffws/v1/contacts/admin HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
<?xml version=”1.0”encoding=”UTF-8”?>
<contact>
<name>Test Contact</name>
<fax_number>218-555-3335</fax_number>
<phone_number>218-555-3336</phone_number>
<organization>Some org</organization>
</contact>
-----------------------------------
HTTP/1.1 200 OK
content-type: application/xml
<?xml version=”1.0”encoding=”UTF-8”?>
<response>
<message>Created</message>
<contact>
<contact_url>https://192.168.2.1/ffws/v1/contacts/admin/6</contact_url>
<name>Test Contact</name>
<fax_number>218-555-3335</fax_number>
<phone_number>218-555-3336</phone_number>
<organization>Some org</organization>
</contact>
</response>
Editing Contacts
HTTP Request
Line
PUT /ffws/v1/contacts/USERNAME/id HTTP/1.1
HTTP Response
Status Codes
200 OK
Modified successfully.
403 Forbidden
Authenticated user does not have permission to change data.
404 Not Found
Contact not found.
400 Bad Request
The provided XML is not valid.

CONTACT AND GROUP FUNCTIONS
FaxFinder Web Services API Developer Guide
16
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
PUT /ffws/v1/contacts/admin/6 HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
<?xml version=”1.0”encoding=”UTF-8”?>
<contact>
<name> Change name </name>
<fax_number>218-555-3335</fax_number>
<phone_number>218-555-3336</phone_number>
<organization>Some org</organization>
</contact>
-----------------------------------
HTTP/1.1 200 OK
content-type: application/xml
<?xml version=”1.0”encoding=”UTF-8”?>
<response>
<message>Modified</message>
</response>
Deleting Contacts
HTTP Request
Line
DELETE /ffws/v1/contacts/USERNAME/id HTTP/1.1
HTTP Response
Status Codes
200 OK
Deleted
403 Forbidden
Authenticated user does not have permission to change data.
404 Not Found
Contact not found.
Example
1
2
3
4
5
6
7
8
9
10
DELETE /ffws/v1/contacts/admin/ 6 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>Deleted</message>
</response>
Viewing Contact IDs
HTTP Request Line
GET /ffws/v1/contact_oids/USERNAME HTTP/1.1
HTTP Response Status
Codes
200 OK
Shows contact IDs.
404 Not Found
Contact not found.

CONTACT AND GROUP FUNCTIONS
17
FaxFinder Web Services API Developer Guide
Example
1
2
3
4
5
6
7
8
9
10
11
GET /ffws/v1/contact_oids/admin 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>
<oids>1,2,3,4,5,6,7,8,9,10,11,12,13,14,33,34,35</oids>
</response>
Viewing Groups
Query
Parameters
limit=LIMIT
Limit the number of results to LIMIT.
offset=OFFSET
Skip OFFSET entries from the start. Only valid when limit is specified.
name=SUBSTR
description=SUBSTR
Search for groups by field name. If you specify more than one, they are concatenated
with AND.
order=field name
Sort groups by field name. Not available for FFx30 models.
HTTP Request
Line
GET /ffws/v1/contact_groups/USERNAME HTTP/1.1
GET /ffws/v1/contact_groups/global_contact_list HTTP/1.1
HTTP Response
Status Codes
200 OK
Shows group information.
403 Forbidden
Authenticated user does not have permission to view data
associated with username.
404 Not Found
No user found with that username.

CONTACT AND GROUP FUNCTIONS
FaxFinder Web Services API Developer Guide
18
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
GET /ffws/v1/contact_groups/admin 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>
<contact_group>
<contact_group_url>https://172.16.128.5/ffws/v1/contact_groups/admin/4</contact_group_url>
<name>g one</name>
<description>g one</description>
<contact>https://172.16.128.5/ffws/v1/contacts/admin/1</contact>
<contact>https://172.16.128.5/ffws/v1/contacts/admin/2</contact>
<contact>https://172.16.128.5/ffws/v1/contacts/global_contact_list/3</contact>
</contact_group>
<contact_group>
<contact_group_url>https://172.16.128.5/ffws/v1/contact_groups/admin/6</contact_group_url>
<name>g two</name>
<description>g two org</description>
<contact>https://172.16.128.5/ffws/v1/contacts/admin/2</contact>
<contact>https://172.16.128.5/ffws/v1/contacts/global_contact_list/4</contact>
</contact_group>
</response>
Creating a New Group
HTTP Request
Line
POST /ffws/v1/contact_groups/admin HTTP/1.1
HTTP Response
Status Codes
200 OK
Created new group.
403 Forbidden
Authenticated user does not have permission to change data
associated with username.
400 Bad Request
The provided XML is not valid.

CONTACT AND GROUP FUNCTIONS
19
FaxFinder Web Services API Developer Guide
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
POST /ffws/v1/contact_groups/admin HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
<?xml version=”1.0” encoding=”UTF-8”?>
<contact_group>
<name>New Group from API</name>
<description>Can I create one from the API</description>
<contact>https://dot3/ffws/v1/contacts/admin/23</contact>
<contact>https://dot3/ffws/v1/contacts/admin/24</contact>
<contact>https://dot3/ffws/v1/contacts/admin/25</contact>
<contact>https://dot3/ffws/v1/contacts/admin/26</contact>
</contact_group>
----------------------
<?xml version=”1.0” encoding=”UTF-8”?>
<response>
<message>Created</message>
<contact_group>
<contact_group_url>https://dot3/ffws/v1/contact_groups/admin/14</contact_group_url>
<name>New Group from API</name>
<description>Can I create one from the API</description>
<contact>https://dot3/ffws/v1/contacts/admin/23</contact>
<contact>https://dot3/ffws/v1/contacts/admin/24</contact>
<contact>https://dot3/ffws/v1/contacts/admin/25</contact>
<contact>https://dot3/ffws/v1/contacts/admin/26</contact>
</contact_group>
</response>
Editing Groups
HTTP Request
Line
PUT /ffws/v1/contact_groups/USERNAME/id HTTP/1.1
HTTP Response
Status Codes
200 OK
Modified successfully.
403 Forbidden
Authenticated user does not have permission to change data
associated with username.
404 Not Found
No user found with that username.
400 Bad Request
The provided XML is not valid.

CONTACT AND GROUP FUNCTIONS
FaxFinder Web Services API Developer Guide
20
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
PUT /ffws/v1/contact_groups/admin/6 HTTP/1.1
content-type: application/xml
authorization: Basic YWRtaW46YWRtaW4=
<?xml version=”1.0”encoding=”UTF-8”?>
<contact_group>
<contact_group_url>https://172.16.128.5/ffws/v1/contact_groups/admin/4</contact_group_url>
<name>Change name</name>
<description>change description</description>
<contact>https://172.16.128.5/ffws/v1/contacts/admin/1</contact>
<contact>https://172.16.128.5/ffws/v1/contacts/admin/2</contact>
<contact>https://172.16.128.5/ffws/v1/contacts/global_contact_list/3</contact>
</contact_group>
-----------------------------------
HTTP/1.1 200 OK
content-type: application/xml
<?xml version=”1.0”encoding=”UTF-8”?>
<response>
<message>Modified</message>
</response>
Deleting Groups
HTTP Request
Line
DELETE /ffws/v1/contact_groups/USERNAME/id HTTP/1.1
HTTP Response
Status Codes
200 OK
Deleted group.
403 Forbidden
Authenticated user does not have permission to change data
associated with username.
404 Not Found
No group found with that username.
Example
1
2
3
4
5
6
7
8
9
10
DELETE /ffws/v1/contact_groups/admin/6 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>Deleted</message>
</response>
Viewing Group IDs
HTTP Request Line
GET /ffws/v1/contact_group_oids/USERNAME HTTP/1.1
HTTP Response Status
Codes
200 OK
Shows group IDs.
404 Not Found
No group found for that username.