Send a Fax

To simplify job creation, Docoon REST API provides to you a specific resource per media. For Fax jobs only the resource is called “FaxJobs”.

We will review how to send quickly a Fax with one recipient or many recipients. We will also review the Fax advanced parameters.

When the Fax job request is accepted, you will get a jobNumber, it means a job was accepted and was put in the appropriate queue (depending on your priority defined in your contract), we will send the message to each recipient as soon as possible depending of the current traffic.

When the job is finished, you will be able to check the transmission status of each recipient, check “Get transmission reports” easy worflow for more information.

Send Fax request informations

Name: /FaxJobs
Type: POST

Headers:

Name Value
Authorization Value : Authorization token check : Connect to REST API
Content-Type Value : application/json

 

Parameters list:

Parameter Type Description
JobType String JobType you want to use (‘NO_JTYPE’ for Fax sending).
TrackingID String (Optional) String of your choice, as a reference for the job (shown in the summary and in your billing).
LaunchType Integer (Optional) Choose your type of sending 0 = Send your message , 1 = Do a proof , 2 = Do a preview.
ScheduledStartTime String (Optional) Choose a date to schedule your job.Example : ‘2017-06-08T03:50:25.355Z’
Documents List of FileReference List of FileReference: used to define documents to transmit to each recipient.
Document format accepted for Fax: .pdf, .doc, .xlsx, html, .TIF.
AdhocRecipients List of AdhocRecipients (Optional can be replace by List File)
List of AdhocRecipients: List of the recipients for the sending, see below for the AdhocRecipients Structure.
Lists List of FileReference (Optional can be replace by AdhocRecipients)
List of FileReference: Used for the recipient list.
List format: .xlsx, .xls, .csv, .tab.
your list should at least contained the phone number in the first column (default setting), then it is up to you to fill the other column.
Parameter FaxParameter Avanced parameters for Fax sending (see below).

 

Structure details of AdhocRecipients

This Object is used to list your recipient in the “AdhocRecipients”

Parameter Type Description
Name String Name or Id of your recipient.
Address String Address/Phone number of your recipient.
OptionalFields List of String List of additionnal information of your recipient (Last Name, Birth date, Country, …) .
The first 5 items of the list will be included in the reports.
It is also possible to use these elements to personalize the messages.
If you want to add the first item of this list use ‘BCF3 (then ‘BCF4, 5 etc..).
`BCF1 = Value inserted into the field “Address” and `BCF2 = Value inserted into the field “Name”.

 

Structure details of FileReference

The object File Reference is used for both list and documents, The structure is the same but you have to select the right “Type” depending of your document.

Parameter Type Description
Name String Name of the file with extension (abc.txt).
Content String FileEncoded in BASE64
Hosted Boolean (optional) True: if the file is hosted in your list of document (Docoon hosted document), False: if not.
MimeType String (Optional) If the file’s MIME type is defined, it will be used for sending email. Else, the system will associate a MIME type based on the file extension.
Type Integer Sect your document type :
0 = List
1 = Document
2 = Body (specific email)
3 = AltBody (specific email)
4 = Attachment (specific email)
Send Basic Fax
{
  "JobType": "NO_JTYPE",
  "TrackingId": "Send Basic FAX",
  "Documents": [
    {
      "Name": "document.pdf",
      "Type":1,
      "Content": "Qm9uam91ciwgaWNpIEF1 .../...  uLCBjZWNpIGVzdCB1biB0ZXN0LiA="
    }
  ],
  "AdhocRecipients": [
	{
      "Name": "Dupont",
      "Address": "00334xxxxxx"
    }
  ]
}

Fax advanced parameters description

In addition to the parameters presented above, there are advanced parameters allowing to configure specific parameters to Fax sending (fax resolution, CSID, …).

Parameter Type Description
Media Integer Type of media used
0: Fax (Always this value for Fax sending).
Csid String Csid specifies the called subscriber ID transmitted to the sending fax machine when receiving incoming faxes.
Resolution Integer Type of fax resoltion
0: Standard resolution.
1: Fine resolution.
Use advanced parameters
{
  "JobType": "NO_JTYPE",
  "TrackingId": "Send FAX with advanced parameters",
  "Documents": [
    {
      "Name": "document.pdf",
      "Type":1,
      "Content": "Qm9uam91ciwgaWNpIEF1 .../...  uLCBjZWNpIGVzdCB1biB0ZXN0LiA="
    }
  ],
  "AdhocRecipients": [
	{
      "Name": "Dupont",
      "Address": "00334xxxxxx"
    }
  ],
  "Parameter": {
    "Csid": "My company",
    "Resolution": 1,
    "Media": 0
  }
}

 

Send a Fax using a file list

You can also use a file list for your recipient. You will have to replace the “AdhocRecipients” list by a “Lists” of File Reference (see the structure below). List format accepted : .xlsx, .xls, .csv, .tab.

By Default, the phone number should be in the first column of the first (and only) sheets of your file.
The other columns can be used for personalizations.

Use file list
{
  "JobType": "NO_JTYPE",
  "TrackingId": "Send FAX with file list",
  "Documents": [
    {
      "Name": "document.pdf",
      "Type":1,
      "Content": "Qm9uam91ciwgaWNpIEF1 .../...  uLCBjZWNpIGVzdCB1biB0ZXN0LiA="
    }
  ],
  "Lists": [
    {
      "Name": "test.tab",
      "Hosted": false,
      "Type":0,
      "Content": "77u/MDAzMzc4Tg3OA=="
    }
  ]
}

Sucessful response

Status: 200 : OK

Parameters list:

Parameter Type Description
JobNumber int ID of the job created
Sucessful Sending
{
  "JobNumber": 44608862
}

Error response

Status: 400: Bad request

Parameter Type Description
Message String Specification of the problem.
ModelState list of job List of job (String error).
Error in the Sending
{
  "Message": "The request is invalid.",
  "ModelState": {
    "job": [
      "An error has occurred."
    ]
  }
}

More Usage Examples

Scheduled job

Use the “ScheduledStartTime” value to delay your sending.
In our example you will send a message the 1st of January 2019.

Scheduled job
{
  "JobType": "NO_JTYPE",
  "TrackingId": "Send scheduled fax",
  "ScheduledStartTime": "2019-01-01T00:00:00.688Z", 
  "Documents": [
    {
      "Name": "document.pdf",
      "Type":1,
      "Content": "Qm9uam91ciwgaWNpIEF1 .../...  uLCBjZWNpIGVzdCB1biB0ZXN0LiA="
    }
  ],  
  "AdhocRecipients": [
	{
      "Name": "Dupont",
      "Address": "00334xxxxxx"
    }
  ]
}