Knowlege base
Home / Imagicle UC Suite for Cisco UC / Digital Fax / Administration Guide / Product Integration API / Submit Fax

Submit Fax

Article ID: 412
Last updated: 14 Nov, 2024

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"
         ]
}

cURL Example

Following an example of API invocation using the cURL command line sending a textual body and a PDF file to two recepients:

curl --location "http://192.168.235.160/fw/Apps/StoneFax/WebAPI/Faxes/Outbound" --header "Content-Type: multipart/form-data"  --header "Content-Disposition: form-data; name=jsondata" --header "Authorization: Basic YXBpdXNlcjpTM2NyZXQh" -F "jsondata={\"subject\" : \"My fax subject\",  \"coverPageName\" : \"BusinessCover\",  \"recipients\" : [ {\"firstName\" : \"John\", \"lastName\" : \"Doe\", \"faxNumber\" : \"+442012345689\"}, {\"firstName\" : \"Jane\", \"lastName\" : \"Smith\", \"faxNumber\" : \"+4420987654321\" } ], \"notifyByEmail\" : \"true\", \"body\" : \"Hi there, this a sample fax trasmission!\" }" --form "attachment1=@\"C:\Tools\Doc-Tests\SamplePDF_2_pages.pdf\""

Article ID: 412
Last updated: 14 Nov, 2024
Revision: 52
Views: 1699
Print Export to PDF Subscribe Share
This article was:  
Prev   Next
Overview     Get Outbound Fax Details