Interfax Admin Web service v1.0 - Documentation
Note:
These are OPTIONAL, advanced methods which allow management of user accounts.
They are NOT necessary for regular faxing of documents.
Overview - Basic Terms
Concepts of Operation
Method Reference
Account & User Related Methods
GetAccountPPCardsBalance
OpenUser
CloseUser
SetUserProperties
GetUserProperties
Fax Reception Related Methods
GetInboundNodes
AddRxService
RemoveRxService
SetRxServiceProperties
GetRxServiceProperties
AddRxEmailProperties
SetRxEmailProperties
GetRxEmailProperties
Fax Transmission Related Methods
AddTxService
RemoveTxService
SetUserTxProperties
GetUserTxProperties
Utility Methods
GetTimeZones
GetTimeZonesXML
Transaction & Cost Summary Methods
GetOutboundActivity
GetInboundActivity
Appendix A - Error codes
Appendix B - Structures
User_General
User_Rx
User_Tx
TimeZoneElement
Appendix C - ISO Country codes
Introduction
The Admin Web service enables customers to handle many aspects of account and
users' management programmatically.
Overview - basic terms
In the Interfax service, there are three main entities, with parent-child relationships:
- Account
- User (Child of Account; no limit on number)
- Service (Child of User; can be one each of: inbound fax or outbound fax)
Account
An Account is the administrative and paying entity. It holds billing and payment
information, as well as the balance available for sending faxes. Each Account
can have one or more Users.
Accounts can be configured by Interfax staff to enable programmatic opening
of new users. By default, Accounts are not configured to enable this.
Accounts may be added manually by Interfax staff, or by registering online
for service. They cannot be added through these administration methods.
User
A User is an operational entity. It is identified by a username and a password.
Under each User, services may be defined which are available for the user, and
service properties may be set. Each user can have a sending service (alternatively
referred to as "TX") or a reception service (alternatively referred to as "RX").
The User properties are specified in Appendix B - structures.
One important property of the User is whether it is a 'Primary user' (as opposed
to a 'Normal user'). A Primary user has certain privileges in the scope of the
Account and its users, e.g. can view other users' activity and can manage billing
details.
A User's namespace is a prefix assigned to an account, which
restrict new users' usernames to start with it followed by a dot. For example:
If a User's namespace is 'somecompany', then all new usernames must
take on the form of 'somecompany.someuser'. A username like 'otheruser'
(note no preceding namespace) is not valid for such an account.
Services
Rx Service and Tx Service hold properties relevant to receiving and sending faxes, respectively. Please refer to
Appendix B - Structures for an extensive description
of these properties.
Concepts of operation
The Admin Web Service WSDL may be accessed at http://ws.interfax.net/admin.asmx?WSDL.
The Admin web service allows for the following operations:
| Operation |
Method Name |
Required permissions |
Comments |
| Get Account balance |
GetAccountPPCardsBalance |
Primary user |
|
| Open a new user |
OpenUser |
Primary user
Only to manually pre-configured accounts (limit on number of users
applies). |
All new usernames must conform to the Account's
'user namespace' |
| Close user |
CloseUser |
Primary user |
Automatically closes all services under that
user. Makes user inaccessible. |
| Update user properties |
SetUserProperties |
Normal User |
Any user may update own service properties |
| Get user properties |
GetUserProperties |
Normal User |
|
| Get available inbound fax nodes (countries) required to open inbound service for a user. |
GetInboundNodes |
Primary user |
|
| Add inbound service to an existing user |
AddRxService |
Primary user |
Subject to charge (if applicable) |
| Drop inbound service from an existing user |
RemoveRxService |
Primary user |
Will cease charge (if applicable) |
| Get inbound service properties |
GetRxServiceProperties |
Normal User |
|
| Update user's inbound properties |
SetRxServiceProperties |
Normal User |
|
| Add an email forwarding address to an inbound user |
AddRxEmailProperties |
Normal User |
|
| Set inbound forwarding properties |
SetRxEmailProperties |
Normal User |
|
| Get inbound forwarding properties |
GetRxEmailProperties |
Normal User |
|
| Add outbound service to an existing user |
AddTxService |
Primary user |
Subject to charge (if applicable) |
| Get outbound service properties |
GetUserTxProperties |
Normal User |
|
| Drop outbound service from an existing user |
RemoveTxService |
Primary user |
Will cease charge (if applicable) |
| Update user's outbound properties |
SetUserTxProperties |
Normal User |
Any user may update his own Tx properties |
| Obtain all time zones |
GetTimeZones |
Anyone |
A utility operation |
| Obtain all time zones in XML structure |
GetTimeZonesXML |
Anyone |
A utility operation |
Method reference
The Admin Web Service WSDL may be accessed at http://ws.interfax.net/admin.asmx?WSDL.
Method: GetAccountPPCardsBalance
Description: Returns the balance left for the Account.
Parameters:
| Name |
Type |
Comments |
| PrimaryUsername |
String |
|
| PrimaryPassword |
String |
|
| Balance |
Decimal |
Money left in prepaid cards (in Account's currency) |
Return value: Integer; Possible values: -1003
(see Appendix A)
Method: OpenUser
Description: Creates a new user under an existing account.
Parameters:
| Name |
Type |
Comments |
| PrimaryUsername |
String |
|
| PrimaryPassword |
String |
|
| NewUser |
User_General |
Structure defined in Appendix B |
| Return Value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: CloseUser
Description: Closes an active user and all related services.
Parameters:
| Name |
Type |
Comments |
| PrimaryUsername |
String |
|
| PrimaryPassword |
String |
|
| Username |
String |
User to be closed |
| Return Value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: SetUserProperties
Description: Update user's general properties.
Parameters:
| Name |
Type |
Comments |
| PrimaryUsername |
String |
|
| PrimaryPassword |
String |
|
| User |
User_General |
Structure defined in Appendix B |
| Return Value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: GetUserProperties
Description: Returns a user's general properties.
Parameters:
| Name |
Type |
Comments |
| PrimaryUsername |
String |
|
| PrimaryPassword |
String |
|
| User |
User_General |
Structure defined in Appendix B; insert any value into array fields |
| Return Value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: GetInboundNodes
Description: Returns available inbound fax nodes (countries) required to open inbound service for a user.
Parameters:
| Name |
Type |
Comments |
| Country |
String |
Two-letter country ISO code (see Appendix C) |
| Language |
String |
Two-letter language code (see Appendix D ) - emails sent from this node will be in this language |
Return value: ArrayOfInboundNode, each item having the following fields:
| ID |
Integer |
Reference number |
| Description |
String |
Description of the node |
| CountryCode |
Integer |
The country code of the node |
| Prefix |
Integer |
The area code prefix of the node |
Method: GetRxEmailProperties
Description: Returns inbound email forwarding properties
Parameters:
| Name |
Type |
Comments |
| Username |
String |
As provided during registration |
| Password |
String |
As provided during registration |
| URxE |
Array |
Array of Rx email addresses (see below) |
URxE Description |
| EmailAddress |
String |
Any value |
| SendSigned |
Boolean |
Any value |
| SendEncrypted |
Boolean |
Any value |
| DigitalID |
String |
Any value |
Return Value:
| Name |
Type |
Comments |
| EmailAddress |
String |
The e-mail address to which inbound faxes will be forwarded |
| SendSigned |
Boolean |
Will the e-mail be sent digitally signed |
| SendEncrypted |
Boolean |
Will the e-mail be sent digitally encrypted |
| DigitalID |
String |
The Digital ID (Certificate) to be used for encrypting the mail message sent to this email address. |
Method: SetRxEmailProperties
Description: Set inbound email forwarding properties
Parameters:
| Name |
Type |
Comments |
| Username |
String |
As provided during registration |
| Password |
String |
As provided during registration |
| EmailAddress |
String |
Email address to change |
| SendSigned |
Boolean |
Will the e-mail be sent signed |
| SendEncrypted |
Boolean |
Will the e-mail be sent encrypted |
| DigitalID |
String |
Will the e-mail be sent with Digital ID |
| Return value |
Integer |
0= OK; less than 0 = Error, see Appendix A |
Method: AddRxEmailProperties
Description: Add an inbound email forwarding email address
Description::
| Name |
Type |
Comments |
| Username |
String |
As provided during registration |
| Password |
String |
As provided during registration |
| EmailAddress |
String |
Email address to change |
| SendSigned |
Boolean |
Will the e-mail be sent signed |
| SendEncrypted |
Boolean |
Will the e-mail be sent encrypted |
| DigitalID |
String |
Will the e-mail be sent with DigitalID |
| Return value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: RemoveRxEmail
Description: Remove an inbound email forwarding address
Parameters:
| Name |
Type |
Comments |
| Username |
String |
As provided during registration |
| Password |
String |
As provided during registration |
| EmailAddress |
String |
The e-mail address to remove |
| Return value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: AddRxService
Description: Add inbound service to user
Parameters:
| Name |
Type |
Comments |
| PrimaryUsername |
String |
The username of the primary user in the account |
| PrimaryPassword |
String |
The password of the primary user in the account |
| Username |
String |
The username of the user to add the service to |
| CountryISOCode |
String |
The ISO code of the country in which to add the number |
| Prefix |
String |
The prefix of the number to be added (this can be retrieved with the GetInboundNodes method) |
| LocalNumber |
String |
The number to be added, if known (if a number is not specified, the system will automatically choose a number for the user) |
| Emails |
String |
The e-mail address to which faxes will be forwarded. May be more than one address, separated by semicolon (;) |
| Return value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: SetRxServiceProperties
Description: Set inbound properties for user
Parameters:
| Name |
Type |
Comments |
| Username |
String |
As provided during registration |
| Password |
String |
As provided during registration |
| U_Rx |
Array |
Array of Rx service properties; structure defined in Appendix B |
| Return Value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: GetRxServiceProperties
Description: Return inbound service properties
Parameters:
| Name |
Type |
Comments |
| Username |
String |
As provided during registration |
| Password |
String |
As provided during registration |
| Return Value |
U_Rx |
See Appendix B; insert any value into array fields |
Method: RemoveRxService
Description: Disable inbound service for given user
Parameters:
| Name |
Type |
Comments |
| PrimaryUsername |
String |
The username of the primary user in the account |
| PrimaryPassword |
String |
The password of the primary user in the account |
| Username |
String |
The username whose service is to be disabled |
| Return value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: AddTxService
Description: Creates a new Tx service under an existing user.
Parameters:
| Name |
Type |
Comments |
| PrimaryUsername |
String |
|
| PrimaryPassword |
String |
|
| User_tx |
User_tx |
Structure defined in Appendix B |
| Return Value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: RemoveTxService
Description: Closes an existing Tx service under an existing
user.
Parameters:
| Name |
Type |
In/Out |
Comments |
| PrimaryUsername |
String |
In |
|
| PrimaryPassword |
String |
In |
|
| Username |
String |
In |
User whose Tx service is to be closed |
| Return Value |
Integer |
|
0= OK; less than 0 = Error (see Appendix A) |
Method: SetUserTxProperties
Description: Update users' outbound properties.
Parameters:
| Name |
Type |
Comments |
| Username |
String |
|
| Password |
String |
|
| User_tx |
User_tx |
Structure defined in Appendix B |
| Return Value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: GetUserTxProperties
Description: Update users' outbound properties.
Parameters:
| Name |
Type |
Comments |
| Username |
String |
|
| Password |
String |
|
| User_tx |
User_tx |
See Appendix B; insert any value into array fields |
| Return Value |
Integer |
0= OK; less than 0 = Error (see Appendix A) |
Method: GetTimeZones
Description: Get List of Time zones and their GMT offset (in
minutes).
Parameters: none
Return value: Array of TimeZoneElement (see Appendix
B)
Method: GetTimeZonesXML
Description: Get List of Time zones and their GMT offset (in
minutes) - in XML format.
Parameters: none
Return value: an XML string in the format:
<TimeZones>
<Name>name 1</Name>
<GMTOffset>GMTOffset 1<GMTOffset>
<Name>name 2</Name>
<GMTOffset>GMTOffset 2<GMTOffset>
..
..
</TimeZones>
Method name: GetOutboundActivity
Description: Get outbound activity list for all users (or for primary user only)
Parameters:
| Name |
Type |
Comments |
| Username |
String |
As provided during registration; Note: This method can only be used by a "Primary" user. |
| Password |
String |
As provided during registration |
| TimeFrom |
DateTime |
Start of date range (yyyy-mm-dd); must be no older than 60 days. |
| TimeUntil |
DateTime |
End of date range (yyyy-mm-dd) |
| OnlyMyUser |
Boolean |
If true - return only the current user's activity. If false - return activity for ALL users under current account. |
Return Value:
| Name |
Type |
Comments |
| Status |
Integer |
Possible values: 0, -1003, -2040, -2041; See Appendix A |
| TimeFrom |
DateTime |
Start of date range (yyyy-mm-dd) |
| TimeUntil |
DateTime |
End of date range (yyyy-mm-dd) |
| Users |
Array |
Array of UserOutboundSummary |
| UserOutboundSummary Description |
| Username |
String |
Username to which transactions apply (see below); lists all users who have outbound service activated in this account. |
| TotalFaxes |
Integer |
Total number of received faxes |
| TotalPages |
Integer |
Total number of received pages |
| TotalUnits |
Decimal |
Total charge units for transactions in range |
| TotalCost |
Decimal |
Total cost for transactions in range |
| MinTransactionID |
Integer |
Lowest TransactionID returned in query |
| MaxTransactionID |
Integer |
Highest TransactionID returned in query |
Method name: GetInboundActivity
Description: Get inbound activity list for all users (or for primary user only)
Parameters:
| Name |
Type |
Comments |
| Username |
String |
As provided during registration; Note: This method can only be used by a "Primary" user. |
| Password |
String |
As provided during registration |
| TimeFrom |
DateTime |
Start of date range (yyyy-mm-dd); must be no older than 60 days. |
| TimeUntil |
DateTime |
End of date range (yyyy-mm-dd) |
| OnlyMyUser |
Boolean |
If true - return only the current user's activity. If false - return activity for ALL users under current account. |
Return Value:
| Name |
Type |
Comments |
| Status |
Integer |
Possible values: 0, -1003, -2040, -2041; See Appendix A |
| TimeFrom |
DateTime |
Start of date range (yyyy-mm-dd) |
| TimeUntil |
DateTime |
End of date range (yyyy-mm-dd) |
| Users |
Array |
Array of UserInboundSummary (see below); lists all users who have inbound service activated in this account. |
| UserInboundSummary Description |
| Username |
String |
Username to which transactions apply |
| PhoneNumber |
String |
Inbound number on which faxes were received |
| TotalFaxes |
Integer |
Total number of received faxes |
| TotalPages |
Integer |
Total number of received pages |
| TotalUnits |
Decimal |
Total charge units |
| TotalCost |
Decimal |
Total cost for transactions in range |
| MinTransactionID |
Integer |
Lowest TransactionID returned in query |
| MaxTransactionID |
Integer |
Highest TransactionID returned in query |
Appendix A - Error codes
| Code |
Description |
| -1003 |
Not authenticated |
| -1020 |
Too many users for this account |
| -2010 |
Username already in use |
| -2011 |
Invalid password (i.e., length not 3-16 characters, characters 0-9, a-z, A-Z) |
| -2012 |
Invalid Time zone |
| -2013 |
Username not in Accounts Namespace |
| -2014 |
Username does not exist |
| -2015 |
Invalid username (longer than 20 characters) |
| -2020 |
Invalid FeedbackType |
| -2021 |
Invalid FeedbackFormat |
| -2022 |
Invalid Allowed senders Address |
| -2023 |
Invalid DefaultPageSize |
| -2024 |
Invalid DefaultPageOrientation |
| -2025 |
Invalid DefaultPageResolution |
| -2026 |
Invalid DefaultRenderingQuality |
| -2027 |
Invalid DefaultRetriesToPerform |
| -2028 |
Invalid CountryISOCode |
| -2030 |
No Tx Service available to user |
| -2031 |
Tx Service already available to user |
| -2032 |
Rx Service already available to user |
| -2033 |
No numbers available |
| -2034 |
E-mail already exists |
| -2035 |
E-mail does not exist |
| -2036 |
No RX service available for user |
| -2037 |
No credit |
| -2040 |
Invalid date range |
| -2041 |
TimeFrom is too old (over 60 days) |
Appendix B - Structures
Structure name: User_General
| Name |
Type |
Description |
| Username |
String |
|
| Password |
String |
|
| CSID |
String |
For both inbound and outbound services |
| TimeZone |
String |
A valid name (see GetTimeZones method) |
Structure name: User_Rx
| Name |
Type |
Description |
| Username |
String |
The username to change the service information for. |
| PhoneNumber |
String |
The phone number assigned to this user |
| AttachmentFormat |
String |
The format of the attachment (PDF / TIFF) |
| DeleteAfterUsage |
String |
Whether to delete the fax image after it has been downloaded or not |
| Emails |
String |
The e-mail that the fax will be sent |
| TimeZone |
String |
The time zone of the user |
| NumberFormat |
String |
The format of the number |
Structure name: User_Tx
| Name |
Type |
Description |
| Username |
String |
|
| CheckPassword |
Boolean |
|
| Conversion |
String |
|
| FeedbackType |
Integer |
0-Never; 1-On success; 2-On failure; 3-Always |
| FeedbackFormat |
Integer |
0-Plain Text (EN); 1-HTML-Local Language; 2-HTML(EN);
3-CSV |
| FeedbackWithTIF |
Boolean |
Should the image be attached to the feedback
message |
| AllowedSenders |
String |
A comma-separated list of email addresses. In
case of an entire domain, a '*' will be provided as username |
| AllowedIPAddresses |
String |
For future use |
| DefaultPageSize |
String |
A4|Letter|Legal|B4 |
| DefaultPageOrientation |
String |
Portrait|Landscape |
| DefaultPageResolution |
String |
Standard|Fine |
| DefaultRenderingQuality |
String |
Standard|Fine |
| DefaultPageHeader |
String |
For future use |
| DefaultRetriesToPerform |
Integer |
For future use (0 through 9) |
| DefaultReplyAddress |
String |
Applicable only for sending via Web service |
| AuthenticateBySignature |
Boolean |
Use S/MIME signature for authentication. |
| AuthenticateByTickets |
Boolean |
Use Office 2003 special authentication; If set
to True, only messages sent via Office 2003 will pass |
| DefaultDeleteAfterUsage |
Boolean |
Delete the fax image as soon as transmission
is completed |
| DialingAreaCode |
String |
Area code from which I am dialing. If set, local
numbers (w/o long distance prefix) will be properly handled |
| DialingCountryISOCode |
String |
Country dialing from (see Appendix C) |
Structure name: TimeZoneElement
| Name |
Type |
Description |
| Name |
String |
|
| GMTOffset |
Integer |
Current offset from GMT (in minutes) |
Appendix C - ISO Country codes
Click for list
Appendix D - Two-letter language code
| Value |
Description |
| DE |
German |
| EN |
English |
| HE |
Hebrew |
| IT |
Italian |
| JP |
Japanese |
|
Sales
