Merge

Merges a specific pages into another file and can be called with a POST Request to the following URL:

[POST]  https://azure.leadtools.com/api/Conversion/Merge

Common Service Request URL Parameters

The following parameters are required unless indicated otherwise, and are used by all Conversion and Recognition API calls:

Parameter Description Accepted Values
fileUrl (Optional) The URL to the file to be processed. For more information, refer to the Cloud Services Overview section. A string or URI containing a valid URL to the file to be uploaded.
firstPage The first page in the file to process. An integer value between 1 and the total number of pages in the file.
lastPage The last page in the file to process. Passing a value of -1 or 0 will indicate to the service that all pages between the First Page parameter, and the last page in the file will be processed. Otherwise, an integer value between 1 and the total number of pages in the file must be passed, and the value must be greater than or equal to the value specified in the FirstPage parameter.
guid (Optional) Unique identifier corresponding to an uploaded file. This value will be returned when a file is uploaded using the UploadFile service call. A valid GUID
filePassword (Optional) The password to unlock a password protected file. A string containing the password for a secure PDF.
callbackUrl (Optional) Passing a callbackURL to the service will allow us to notify you when your file has finished processing. If the callbackUrl is invalid or malicious, it will be ignored. The LEADTOOLS Cloud Services will send the request’s ID in the body of the message sent to the callbackUrl. A string or URI containing a valid URL to message.
ocrLanguage (Optional) The OCR Language to use when OCRing a Raster file. Defaults to en (English) if no languages are specified. 0 - en
1 - bg
2 - hr
3 - cs
4 - da
5 - nl
6 - fr
7 - de
8 - el
9 - hu
10 - it
11 - pl
12 - pt
13 - sr
14 - es
15 - sv
16 - tr
17 - uk
qualityTradeoff (Optional) The compression to quality ratio to use when saving out an Image PDF, TIF, or JPEG. Balanced is the default tradeoff option if none are specified. 0 - Balanced
1 - Quality
2 - Size

Request Specific Parameters

Additional parameters available are listed below.

Parameter Description Accepted Values
format The format to convert the file to. 1 - Png
2 - Jpeg
3 - Tiff
4 - Pdf
5 - Pdfa
6 - PdfImage
7 - PdfImageOverText
8 - PdfaImageOverText
9 - Docx
10 - DocxFramed
11 - Rtf
12 - RtfFramed
13 - Txt
14 - TxtFramed
MergeRequests (body) The JSON body of all the FileIDs and Pages to merge. If only a fileId is passed, then the entire file will be merged. The pages array precedes the firstPage and lastPage parameters. int firstPage
int lastPage
string fileId
int[] pages

Example JSON Body for Merge

[ 
	{ 
		"firstPage" : 1, 
		"lastPage" : -1, 
		"fileId" : "00000000-0000-0000-0000-000000000000" 
	}, 
	{ 
		"pages" : [5,4,3,2,1], 
		"fileId" : "00000000-0000-0000-0000-000000000000" 
	}, 
	{ 
		"firstPage" : 2, 
		"lastPage" : 4, 
		"fileId" : "00000000-0000-0000-0000-000000000000" 
	}, 
	{ 
		"fileId" : "00000000-0000-0000-0000-000000000000" 
	} 
] 

Status Codes

The following status codes will be returned when the method is called:

Status Description
200 The request has been successfully received.
400 The request was not valid for one of the following reasons:

Required request parameters were not included.
GUID value was not provided.
File information provided was malformed.
Attempting to queue a request on a file that has not yet been verified.
401 The AppID/Password combination is not valid or does not correspond with the GUID provided.
402 There are not enough pages left in the Application to process the request.
500 There was an internal error processing your request.

Returns

If performing a single-service merge, a unique-identifier will be returned that can be used to query the progress of the conversion.

Online Demo

This method is available for free in our live Online Demo. You do not need an account and you can test out your own files to see the results.

Examples

JavaScript (Node.js)
C#
Python
PHP
Perl
//This sample uses the Request NodeJs library. 
 
var FormatsEnum = { 
    "png":1, "jpeg":2, "tiff":3, "pdf":4, "pdfa":5, 
    "pdfImage": 6, "pdfImageOverText": 7, "pdfaImageOverText": 8, 
    "docx": 9, "docxFramed": 10, "rtf": 11, "rtfFramed": 12, 
    "txt":13, "txtFramed":14 
 }; 
 
 var servicesUrl = "https://azure.leadtools.com/api/"; 
 
 
 //Enum corresponding to the output format for the file. For the purposes of this script, we will be converting to tif. 
 var fileFormat = FormatsEnum.pdf; 
 
 //These ID's will be acquired by calling the Upload API command with the forMerge flag set to true. 
 var fileId1 = ""; 
 var fileId2 = "" 
 
 mergeFile(fileId1, fileId2); 
 
 function mergeFile(firstFileId, secondFileId){ 
	let mergeUrl = `${servicesUrl}Conversion/Merge?format=${outputFormat}`; 
	let options = getRequestOptions(mergeUrl); 
	options['json'] = [ 
		{ 
			'firstPage' : 1, 
			'lastPage' : -1, 
			'fileId' : firstFileId 
		}, 
		{ 
			'pages' : [5,1,2,4,3], 
			'fileId' : secondFileId 
		} 
	] 
 
	request.post(options, (error, response, body) =>{ 
		if (!error && response.statusCode === 200) { 
			console.log("Merge command was successful"); 
		} else { 
			console.log("Merge failed with HTTP code: " + response.statusCode); 
			console.log(body); 
		} 
	}) 
} 
 
 function getRequestOptions(url){ 
     //Function to generate and return HTTP request  options. 
     var requestOptions ={ 
         url: url, 
         auth: { 
             user:"Enter Application ID", 
             password:"Enter Application Password" 
         } 
     }; 
     return requestOptions; 
 } 
using System; 
using System.Collections.Generic; 
using System.Linq; 
using System.Text; 
using System.Threading.Tasks; 
using System.Threading; 
using System.Net; 
using System.Net.Http; 
using System.Net.Http.Headers; 
using Newtonsoft.Json.Linq; 
 
namespace Azure_Code_Snippets.DocumentationSnippets 
{ 
   class CloudServices_Merge_Demo 
   { 
      private enum FormatsEnum 
      { 
         Png = 1, 
         Jpeg = 2, 
         Tiff = 3, 
         Pdf = 4, 
         Pdfa = 5, 
         PdfImage = 6, 
         PdfImageOverText = 7, 
         PdfaImageOverText = 8, 
         Docx = 9, 
         DocxFramed = 10, 
         Rtf = 11, 
         RtfFramed = 12, 
         Txt = 13, 
         TxtFramed = 14, 
      } 
 
      private string hostedServicesUrl = "https://azure.leadtools.com/api/"; 
 
      public async Task<bool> Merge(string firstFileId, string secondFileId) 
      { 
         var mergeList = new List<MergeArgument>(); 
         mergeList.Add(new MergeFirstLast() 
         { 
            fileId = firstFileId, 
            firstPage = 1, 
            lastPage = -1 
         }); 
 
         mergeList.Add(new MergePageArray() 
         { 
            fileId = secondFileId, 
            pages = new int[]{ 5, 1, 2, 4, 2 } 
         }); 
 
         //Final output format for the merged file 
         var outputFormat = FormatsEnum.Pdf; 
         var mergeUrl = string.Format("Conversion/Merge?format={0}", outputFormat); 
         var response = await client.PostAsync(mergeUrl, new StringContent(JsonConvert.SerializeObject(mergeList), Encoding.UTF8, "application/json")); 
         return response.StatusCode == HttpStatusCode.OK; 
 
      } 
 
      private HttpClient InitClient() 
      { 
         string AppId = "Enter Application ID"; 
         string Password = "Enter Application Password"; 
 
         HttpClient client = new HttpClient(); 
         client.BaseAddress = new Uri(hostedServicesUrl); 
         client.DefaultRequestHeaders.Accept.Clear(); 
         client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json")); 
 
         string authData = string.Format("{0}:{1}", AppId, Password); 
         string authHeaderValue = Convert.ToBase64String(Encoding.UTF8.GetBytes(authData)); 
         client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", authHeaderValue); 
 
         return client; 
      } 
 
      private class MergeArgument 
      { 
         public string fileId { get; set; } 
      } 
 
      private class MergeFirstLast: MergeArgument 
      { 
         public int firstPage { get; set; } 
         public int lastPage { get; set; } 
      } 
 
      private class MergePageArray : MergeArgument 
      { 
         public int[] pages { get; set; } 
      } 
   } 
} 
#Simple script to make a Merge request to the LEADTOOLS CloudServices and parse the resulting JSON. 
 
import requests, sys, time 
 
# Enums in python 
from enum import Enum 
 
class FormatsEnum(Enum): 
    Png = 1 
    Jpeg = 2 
    Tiff = 3 
    Pdf = 4 
    Pdfa = 5 
    PdfImage = 6 
    PdfImageOverText = 7 
    PdfaImageOverText = 8 
    Docx = 9 
    DocxFramed = 10 
    Rtf = 11 
    RtfFramed = 12 
    Txt = 13 
    TxtFramed = 14 
 
servicesUrl = 'https://azure.leadtools.com/api/' 
 
#The application ID. 
appId = "Enter Application ID"; 
 
#The application password. 
password = "Enter Application Password"; 
 
#These ID's will be acquired by calling the Upload API command with the forMerge flag set to true. 
firstFileId = "" 
secondFileId = "" 
 
data = [] 
 
firstFileData = {} 
# pass every page in the file 
firstFileData['firstPage'] = 1 
firstFileData['lastPage'] = -1 
firstFileData['fileId'] = firstFileId 
data.append(firstFileData) 
 
secondFileData = {} 
# Make sure this file's pages are merged in a specific order. 
secondFileData['pages'] = [5,1,2,4,3] 
secondFileData['fileId'] = secondFileId 
data.append(secondFileData) 
 
# The output format of the merged files 
mergeFormat = FormatsEnum.Pdf.value 
 
baseMergeUrl = '{}Conversion/Merge?format={}' 
formattedMergeUrl = baseMergeUrl.format(servicesUrl, mergeFormat) 
request = requests.post(formattedMergeUrl, auth=(appId, password), json=data) 
if request.status_code != 200: 
        print("Error sending merge request") 
        print(request.text) 
        sys.exit() 
<?php 
    //Simple script to make a Conversion request to the LEADTOOLS CloudServices and parse the resulting JSON. 
 
    $servicesBaseUrl = "https://azure.leadtools.com/api/"; 
 
    abstract class FormatsEnum 
    { 
        const Png = 1; 
        const Jpeg = 2; 
        const Tiff = 3; 
        const Pdf = 4; 
        const Pdfa = 5; 
        const PdfImage = 6; 
        const PdfImageOverText = 7; 
        const PdfaImageOverText = 8; 
        const Docx = 9; 
        const DocxFramed = 10; 
        const Rtf = 11; 
        const RtfFramed = 12; 
        const Txt = 13; 
        const TxtFramed = 14; 
    } 
 
     //These ID's will be acquired by calling the Upload API command with the forMerge flag set to true. 
    $firstFileId = ""; 
    $secondFileId = ""; 
 
    $data = []; 
 
    $firstFileData = array( 
        "firstPage" => 1, 
        "lastPage" => -1, 
        "fileId" => $firstFileId 
    ); 
    $secondFileData = array( 
        "pages" => [5,1,2,3,4], 
        "fileId" => $secondFileId 
    ); 
    array_push($data, $firstFileData, $secondFileData); 
 
    $fileFormat = FormatsEnum::Pdf; 
    $mergeUrl = "%sConversion/Merge?format=%s"; 
    $mergeUrl = sprintf($mergeUrl, $servicesBaseUrl, $fileFormat); 
    $mergeOptions = GeneratePostOptionsMerge($mergeUrl, $data); 
 
    $r = curl_init(); 
    curl_setopt_array($r, $mergeOptions); //Set the request URL 
 
    if (!$id = curl_exec($r)) { 
        echo "There was an error sending the merge request \n\r"; 
        echo $id; 
        exit; 
    } 
    curl_close($r); //Close the request 
 
 
    function GeneratePostOptionsMerge($url, $jsonData) 
    { 
        $options = GeneratePostOptionsUpload($url); 
        //remove 0 content-length header 
        unset($options[CURLOPT_HTTPHEADER]); 
 
        $encodedData = json_encode($jsonData); 
        $options[CURLOPT_POSTFIELDS] = $encodedData; 
        $options[CURLOPT_HTTPHEADER] = array( 
            'Content-Type: application/json', 
            'Content-Length: ' . strlen($encodedData) 
        ); 
        return $options; 
    } 
 
    function GeneratePostOptions($url) 
    { 
        $appId = "Enter Application ID"; 
        $password = "Enter Application Password"; 
        $headers = array( 
            "Content-Length : 0" 
        ); 
        $postOptions = array( 
            CURLOPT_POST => 1, 
            CURLOPT_URL => $url, 
            CURLOPT_FRESH_CONNECT => 1, 
            CURLOPT_RETURNTRANSFER => 1, 
            CURLOPT_USERPWD => "$appId:$password", 
            CURLOPT_FORBID_REUSE => 1, 
            CURLOPT_HTTPHEADER => $headers 
        ); 
        return $postOptions; 
    } 
?> 
#Simple script to make and process the results of a merge request to the LEADTOOLS CloudServices. 
 
use base 'HTTP::Message'; 
use LWP::UserAgent (); 
 
require HTTP::Request; 
require HTTP::Headers; 
 
my $servicesUrl = "https://azure.leadtools.com/api/"; 
 
my $appId = 'Enter Application ID'; 
my $password = 'Enter Application Password'; 
my $headers = HTTP::Headers->new( 
    Content_Length => 0 
); 
$headers->authorization_basic($appId, $password); 
 
#These ID's will be acquired by calling the Upload API command with the forMerge flag set to true. 
my $firstFileId = ""; 
my $secondFileId = ""; 
 
#The User Agent to be used when making requests 
my $ua = LWP::UserAgent->new; 
 
my @data = (); 
push( @data, { 
        firstPage => 1, 
        lastPage => -1, 
        fileId => $firstFileId 
}); 
 
push( @data, { 
    'pages' => [5,1,2,4,3], 
    'fileId' => $secondFileId 
}); 
 
#Enum corresponding to the output format for the file. For the purposes of this script, we will be converting to PDF. 
my $outputFormat = 4; 
my $mergeUrl = $servicesUrl . 'Conversion/Merge?format=' . $outputFormat; 
my $encodedData = to_json \@data; 
 
my $headers =HTTP::Headers->new( 
    Content_Type => 'application/json' 
); 
$headers->authorization_basic($appId, $password); 
 
my $request = HTTP::Request->new(POST => $mergeUrl, $headers); 
$request->content($encodedData); 
my $response = $ua->request($request); 
if(!$response->is_success){ 
        print STDERR $response->status_line, "\n"; 
        exit; 
    } 
 
print("Merge request successful \n\r"); 

See Also

Resources

Legal

Help Version 22.0.2022.12.14
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.