Submit Fax

Submits a fax job, in order to send one or more documents to one or more recipients.

Resource URL

POST fw/Apps/StoneFax/WebAPI/Faxes/Outbound

Resource Information

Request Content-Type: multipart/form-data
Response Content-Type: application/json
Requires authentication: Yes

URL Parameters

None

Request body

The request body is a multipart/form-data containing a part that describes the submit information and as many parts as the attachments you want to send along the fax.

The submit information part must be as follows:

Content-Type: application/json
Content-Disposition: form-data; name=jsondata
The content of this part must be a JSON with the following model:

Fax

Name	Type	Required	Description	Default	Example
subject	string	optional	The subject of the fax	null	"The fax subject"
coverPageName	string	optional	The name of the cover page to use (not including the COV file extension). If specified, it must match the name of an existing cove page. If the specified coverpage does not exists, the fax will be sent without any coverpage.	null	"BusinessCover"
recipients	Recipient[]	required	The recipients of the fax. It must contain at least one recipient. See below for the Recipient data structure details.	[]
sendAsUsername	string	optional	The username to use as the fax sender. Level 2 users: can only send as the fax group they belong to Level 6 users: like level 2 users Level 10 users: can send as any valid Digital Fax user If not specified, the sender will be the user invoking this method.	null	"userToImpersonate"
notifyByEmail	bool	optional	True if you want to receive email notifications about the transmission status. False otherwise	false	true
notificationEmailAddress	string	optional	Use this parameter to specify a recipient email address for the transmission report email, different from the sending user email address. If not specified, the sending user email address will be used. This parameter is ignored if notifyByEmail=FALSE	null	"mailfornotifications@domain.com"
speedyDirectoryName	string	optional	The name of an existing Speedy directory. Use this parameter to send the fax to every fax contact contained of the Speedy directory (fax multicast). Such contacts will be additional recipients respect to the ones specified by the Recipients[] array.	null	"directory1"
body	string	optional	The fax body (plain text). If null or empty, then the rest of the multipart body must contain at least one valid attachment.	null	"The fax body"

Recipient

Name	Type	Required	Description	Default	Example
firstName	string	optional	Recipient's first name	null	"John"
lastName	string	optional	Recipient's last name	null	"Doe"
faxNumber	string	required	Recipient's fax number	null	"123456"

Response

202 Accepted

Fax has been submitted and is being processed.

Response body

Name	Type	Description
ids	string[]	The submitted job ids (one per recipient)

Error response

400 Bad Request

Response body

Name	Type	Description
reason	BadRequestReason	The reason why the request has been rejected

BadRequestReason

Value	Descritpion
SyntaxError	The JSON part contains a syntax error and cannot be parsed
InvalidRecipients	No recipients provided, or at least one of the recipients has no fax number
InvalidAttachments	The attachments supplied are invalid
InvalidDirectoryName	There is no such Speedy directory having the given name
InvalidUsername	There is no such user having the given username

401 Unauthorized

No authentication provided
Wrong credentials

403 Forbidden

Insufficient privilege level
Outgoing faxes disabled for the user
Outgoing faxes disabled for the impersonated user

Examples

Fax without attachments

This example sends a fax only containing a body (i.e. without attachments) to two recipients, enabling email notifications:

POST fw/Apps/StoneFax/WebAPI/Faxes/Outbound

Request body:


--dcb45cdc-6ac3-46ad-8dea-892a8989588d
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name=jsondata

{
   "subject" : "My fax subject",
   "coverPageName" : "BusinessCover",
   "recipients" : 
   [
      {
         "firstName" : "John",
         "lastName" : "Doe",
         "faxNumber" : "123456"
      },
      {
         "firstName" : "Jane",
         "lastName" : "Doe",
         "faxNumber" : "789012"
      }
   ],
   "notifyByEmail" : "true",
   "body" : "Hello everybody!"
}
--dcb45cdc-6ac3-46ad-8dea-892a8989588d

The response body is:


{
   "ids":[
            "IAS-N1_6a504a1d-12d6-44a7-a249-db6c4389f413_0",
            "IAS-N1_6a504a1d-12d6-44a7-a249-db6c4389f413_1"
         ]
}

Fax with an attachment

This other example sends a fax only with a body and an attachment to one recipient, enabling email notifications:

POST fw/Apps/StoneFax/WebAPI/Faxes/Outbound

Request body:


--8176a96c-1355-400a-8d63-69a230e8c5ea
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name=jsondata

{
   "subject" : "My fax subject with an attachment",
   "coverPageName" : "BusinessCover",
   "recipients" : 
   [
      {
         "firstName" : "John",
         "lastName" : "Doe",
         "faxNumber" : "123456"
      }
   ],
   "notifyByEmail" : "true",
   "body" : "Hello everybody! Please find the attachment."
}
--8176a96c-1355-400a-8d63-69a230e8c5ea
Content-Disposition: form-data; name=""; filename="Attachment.txt"
Content-Type: text/plain

Hi, I'm an attachment!

--8176a96c-1355-400a-8d63-69a230e8c5ea

The response body is:



{
   "ids":[
            "IAS-N1_1322b0b2-696f-4b0e-807d-3707e9a5d1d2_0"
         ]
}

Fax with multiple attachments

If you need to send a fax with two or more attachments, all you have to do is add one form part for each additional attachment you need to send. In this example we send a fax with a body and two attachments:

POST fw/Apps/StoneFax/WebAPI/Faxes/Outbound

Request body:


--8176a96c-1355-400a-8d63-69a230e8c5ea
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name=jsondata

{
   "subject" : "My fax subject with an attachment",
   "coverPageName" : "BusinessCover",
   "recipients" : 
   [
      {
         "firstName" : "John",
         "lastName" : "Doe",
         "faxNumber" : "123456"
      }
   ],
   "notifyByEmail" : "true",
   "body" : "Hello everybody! Please find the attachment."
}
--8176a96c-1355-400a-8d63-69a230e8c5ea
Content-Disposition: form-data; name=""; filename="Attachment1.txt"
Content-Type: text/plain

Hi, I'm an attachment!

--8176a96c-1355-400a-8d63-69a230e8c5ea
Content-Disposition: form-data; name=""; filename="Attachment2.txt"
Content-Type: text/plain

Hi, I'm another attachment!

--8176a96c-1355-400a-8d63-69a230e8c5ea

The response body is:



{
   "ids":[
            "IAS-N1_1322b0b2-696f-4b0e-807d-3707e9a5d1d2_0"
         ]
}