The Softlinx Cloud Fax REST API is a lightweight alternative to the ReplixFax SOAP API.
It provides a simplified API for sending and retrieving faxes. Requests are made over a secured HTTPS connection.
The list below describes the functionality available with the ReplixFax REST API.
The base URL is "https://api.rpxtest.com/softlinx/replixfax/restapi/v1", The "v1" denotes version 1 of the APIs. The APIs are documented with relative to the base URL, e.g, for send fax the documented URL is /outboundfaxes so the real URL is https://api.rpxtest.com/softlinx/replixfax/restapi/v1/outboundfaxes.
The URL above is for the Softlinx Cloud Fax test environment. A production URL is provided as part of the customer onboarding process.
HTTP submission method
The HTTP method is denoted with GET, POST, PUT, DELETE keywords.
API arguments
The API parameters can be passed in QUERY_STRING or in the body of the request using "www-form-urlencoded" or "form-datea" formats. Both formats are standard form/url submission formats used by browsers. The "application/www-form-urlencoded" body contains mutliple params "key=value&key=value..." whereas "form-data" is mutlpart/form-data contains one parameter per MIME part and is usually used to send attachments.
Arguments are case sensitive and unrecognized arguments are ignored.
Client credentials
The client userid and password is passed to the API using the Basic Authentication header.
REST API responses
Response HTTP code:
200 OK for success, Most responses should return that. For successful send fax return is 201 Created.
401 Authentication failure Unauthorized - bad username or password
403 Forbidden access denied to a resource
400 Bad Request - Client errors in parameters/URLs
404 Not Found missing resource
500 Server Error - Server processing errors
Response body
All responses return JSON data (application/json) except for retrieving fax image where the image/tiff or application/pdf content is returned. ALL JSON responses contain "RequestStatus" object with StatusCode (0 for success), StatusText members. e.g,
The ReplixFax API has methods which allow the sending of a fax request,
querying the status of an outbound fax, marking an outbound fax, resubmitting a failed outbound fax and deleting an outbound fax.
Submits a fax to be sent via the server. When the API call returns, the results will contain a Fax identifier that uniquely identifies the outgoing fax. The fax will most likely not have been sent when the call returns.
You can query that status of this fax, using the Fax ID return to see when the fax is sent.
Information about the recipient of the fax, including fax number.
FaxRecipient
Name
Type
Description
FaxNumber
string
Destination fax number field (required), e.g., 17915551212. Note: a "1" is required for US and Canadian numbers. A "+" should proceed international numbers.
RcptName
string
Recipient name field (used in Cover page template).
Number of times to attempt to send the fax. This includes the initial attempt and any retries. It is recommended that the RetryCount be set between 3 and 5. The cloud service will enforce a minimal and maximum value to ensure optimal performance.
Number of minutes between attempts to send the fax. It is recommended that the Retry Interval be set between 10 and 20 minutes. The cloud service will enforce a minimum and maximum value to ensure optimal performance.
Date/time after which to attempt to send the fax. If missing, attempts to send as soon as possible.
datetime
Description
The valid formats for date/time parameters are a subset of the ISO 8601 specification:
YYYY-MM-DDThh:mmTZ or YYYY-MM-DDThh:mm:ssTZ, where TZ is the time zone and the format of this is either "Z" or (+|-)hh:mm. The “:” between the hour and minutes in the time zone is optional. Examples are:
2010-01-31T13:30:45Z "Z" stands for GMT time zone
2010-01-31T14:30:45+01:00
2010-01-31T13:30:45-0500
*** ReplixFax assumes UTC time, so the "Z" indicator should be used when specifying times. ***
Used to indicate whether a cover page is used. If you set the CoverPageName to a value, then you need to set this to true. If you set this to "true" and do not set a CoverPageName, then the default cover page will be used.
Boolean
Values
Description
true
True
false
False.
CoverPageName
string
Cover page name that is stored in the fax server cover page directory. A Softlinx customer service representative can assist in creating custom cover pages.
CoverMessage
string
Cover page message goes into the "message" field on the cover page. 12 lines maximum. Each line cannot be longer than 128 characters.
CoverField_[ID]
string
Cover page templates can contain custom fields. These fields are not related to fax metadata and are populated via the API. The REST CoverField argument should match a custom field in the template. For example, if there is a field in the PDF template with the name of "field-310", then the REST argument passed should be CoverField_310. A Softlinx customer service representative can assist in creating custom cover pages that include custom fields.
Indicates content of fax header. Will only be used is FaxHeaderEnabled is set to true. The Fax Header can contains static text and keywords that are replaced with real data. The default fax header format is date/time + TSI + pages.
Fax Header Keywords
Keywords are case sensitive.
Values
Description
%t
% character
%t
Time
%d
Date
%P
Page number
%p
Total pages
%i
Sender TSI
%j
Sender name
%k
Sender DID (fax number)
%l
Sender telephone number
%m
Sender email
%n
Send job id
%a
Recipient name
%b
Recipient company name
%c
Recipient title
%e
Recipient fax number
%f
Recipient telephone number
%CN
Cover page field with field id N, N is a number, eg %C333 to insert cover page 333
Fax sending priority (0 to 10). This value is ignored by the cloud service. All faxes have the same priority.
NonNegativeInt
Type
Description
string
An integer greater than or equal to 0.
ProjectCode
string
Application specific string. If set, this will overwrite the account number associated with the user.
ProjectCode2
string
Application specific string, aka reference keyword.
TSI
string
Transmitting station identifier is the string that the receiving fax device displays on the device LCD. The maximum number of characters for this string is 20. Any value more than 20 characters will be truncated when the fax is sent. The TSI string can be part of the fax header.
FaxUserId
string
Specifies the owner of the fax. Normally the fax owner is determined from the HTTP request authentication, but your current credentials may allow (if configured so by the fax administrator) to specify a different owner. E.g, your login credentials are "bob" but your application may decide to assign the ownership to "mary" (so "bob" proxies sends fax for "mary").
Text2tiffFontName
string
Font name when converting text to tiff image. Backend specific, is very unlikely you will ever need to use this.
Resend a fax to a different fax number. This can only be executed against outgoing faxes that
have a status of "sendFailed". When the API call returns, the results will contain a new Fax identifier that uniquely identifies the outgoing fax.
The fax will most likely not have been sent when the call returns. You can query that status of this fax, using the Fax ID return to see when
the fax is sent. Note: the original fax will be deleted.
HTTP:
POST /softlinx/replixfax/restapi/v1/outboundfaxes/
RequestStatus will always be returned. The FaxInfo item will only be present if at least one fax is found that meets the search criteria.
There will be a FaxInfo array item for each fax returned that meets the search criteria.
Date/time that limits the results to faxes that have been updated (or completed when fax has a final status of sent or sendFailed) at specified or later date/time.
datetime
Description
The valid formats for date/time parameters are a subset of the ISO 8601 specification:
YYYY-MM-DDThh:mmTZ or YYYY-MM-DDThh:mm:ssTZ, where TZ is the time zone and the format of this is either "Z" or (+|-)hh:mm. The “:” between the hour and minutes in the time zone is optional. Examples are:
2010-01-31T13:30:45Z "Z" stands for GMT time zone
2010-01-31T14:30:45+01:00
2010-01-31T13:30:45-0500
*** ReplixFax assumes UTC time, so the "Z" indicator should be used when specifying times. ***
Date/time that limits the results to faxes that have been updated (or completed when fax has a final status of sent or sendFailed) at specified or earlier date/time.
datetime
Description
The valid formats for date/time parameters are a subset of the ISO 8601 specification:
YYYY-MM-DDThh:mmTZ or YYYY-MM-DDThh:mm:ssTZ, where TZ is the time zone and the format of this is either "Z" or (+|-)hh:mm. The “:” between the hour and minutes in the time zone is optional. Examples are:
2010-01-31T13:30:45Z "Z" stands for GMT time zone
2010-01-31T14:30:45+01:00
2010-01-31T13:30:45-0500
*** ReplixFax assumes UTC time, so the "Z" indicator should be used when specifying times. ***
FaxUserId
string
Limit faxes returned to those owned by specific fax user id. If the username set in the credentials does not have the proxy user privilege, this parameter will be ignored.
If a query was issued with the ResultLimit set and the results HasMoreResults is "true", then there are more results that match the criteria. To get to the next set of faxes, reissue the query, but set GetNextResults to the value returned in the ResultsReference attribute. If GetNextResults is set, then any changes to the original search criteria on subsequent queries is ignored, except for ResultLimit. In other words, if GetNextResults is set, you cannot alter the query when getting the next set of faxes, except for the number of faxes to return.
Fax group identifier. If a fax request is made with multiple recipients, then a unique fax request is generated for each recipient. The group identifier for all of these faxes will be the same. It will be the fax id of the first fax in the group.
TSI (Transmitting Station Identifier) is a string that a sending fax machine sends to the receiving fax machine. The receiving fax machine usually displays this value on the fax machines LCD display.
CSI (Called Station Identifier) is a string that a receiving fax machine sends to the sending fax machine. The sending fax machine usually displays this string on the fax machines LCD display.
TSI and CSI are transmitted during initial stage of the fax protocol negotiation
TSI (Transmitting Station Identifier) is a string that a sending fax machine sends to the receiving fax machine. The receiving fax machine usually displays this value on the fax machines LCD display.
CSI (Called Station Identifier) is a string that a receiving fax machine sends to the sending fax machine. The sending fax machine usually displays this string on the fax machines LCD display.
TSI and CSI are transmitted during initial stage of the fax protocol negotiation
If "ResultLimit" input argument provided and the number of records exceeds the limit, only limited number of records is returned and this result indicates that there were records from the query.
Boolean
Values
Description
true
True
false
False.
ResultsReference
string
A key that is set if there are more faxes that meet the search criteria but are not returned in the results. Use this key in the GetNextResults attribute in the subsequent query to retrieve the next set of faxes.
Date/time that limit the results to faxes that have been received at specified or later date/time.
datetime
Description
The valid formats for date/time parameters are a subset of the ISO 8601 specification:
YYYY-MM-DDThh:mmTZ or YYYY-MM-DDThh:mm:ssTZ, where TZ is the time zone and the format of this is either "Z" or (+|-)hh:mm. The “:” between the hour and minutes in the time zone is optional. Examples are:
2010-01-31T13:30:45Z "Z" stands for GMT time zone
2010-01-31T14:30:45+01:00
2010-01-31T13:30:45-0500
*** ReplixFax assumes UTC time, so the "Z" indicator should be used when specifying times. ***
Date/time that limit the results to faxes that have been received at specified or earlier date/time.
datetime
Description
The valid formats for date/time parameters are a subset of the ISO 8601 specification:
YYYY-MM-DDThh:mmTZ or YYYY-MM-DDThh:mm:ssTZ, where TZ is the time zone and the format of this is either "Z" or (+|-)hh:mm. The “:” between the hour and minutes in the time zone is optional. Examples are:
2010-01-31T13:30:45Z "Z" stands for GMT time zone
2010-01-31T14:30:45+01:00
2010-01-31T13:30:45-0500
*** ReplixFax assumes UTC time, so the "Z" indicator should be used when specifying times. ***
FaxUserId
string
Limit faxes retrieved to those owned by specific fax user id. Unless your current login is configured as a proxy user, you should leave this field empty as the fax server will only return faxes owned by your current login. To see faxes from all users set to "*".
If a query was issued with the ResultLimit set and the results HasMoreResults is "true", then there are more results that match the criteria. To get to the next set of faxes, reissue the query, but set GetNextResults to the value returned in the ResultsReference attribute. If GetNextResults is set, then any changes to the original search criteria on subsequent queries is ignored, except for ResultLimit. In other words, if GetNextResults is set, you cannot alter the query when getting the next set of faxes, except for the number of faxes to return.
A key that is set if there are more faxes that meet the search criteria but are not returned in the results. Use this key in the GetNextResults attribute in the subsequent query to retrieve the next set of faxes.