Content types and schemes
In this documentation section are covered all content types and schemes that are supported by convertapi.com.
Conversion request content types and schemes
application/json
JSON scheme also can be built in Code Snippets section. File data must be encoded with Base64 encoding, provided as URL or uploaded File ID.
POST https://v2.convertapi.com/convert/doc/to/pdf?Secret=XXX
{ "Parameters": [ { "Name": "File", "FileValue": { "Name": "my_file.doc", "Data": "--Base64 encoded file content--" } } ] }
POST https://v2.convertapi.com/convert/pdf/to/merge?Secret=XXX
{ "Parameters": [ { "Name": "StoreFile", "Value": "true" }, { "Name": "PdfVersion", "Value": "1.7" }, { "Name": "Files", "FileValues": [ { "Name": "file.pdf", "Data": "--Base64 encoded file content--" }, { "Url": "http://example.com/myfile.docx" }, { "Id": "13232131" } ] } ] }
multipart/form-data
Each request parameter must be in separate part. If there is an array type parameter, index must be appended to parameter name e.g. Files[0], Files[1], Files[2] etc.
POST /convert/doc/to/pdf?secret=XXXX HTTP/1.1 Host: v2.convertapi.com Cache-Control: no-cache Content-Type: multipart/form-data; boundary=----7MA4YWxkTrZu0gW ------7MA4YWxkTrZu0gW Content-Disposition: form-data; name="StoreFile" true ------7MA4YWxkTrZu0gW Content-Disposition: form-data; name="File"; filename="my_file.doc" Content-Type: --FILE DATA-- ------7MA4YWxkTrZu0gW Content-Disposition: form-data; name="DocumentTitle" Test title ------7MA4YWxkTrZu0gW--
application/octet-stream
Most bandwidth efficient way to convert file is to pass file content as a request body. Also this content type could be used for stream processing. Request header must contain field: Content-Disposition: attachment; filename="my_file.doc" with the file name and correct file extension. Conversion parameters can be set throw URL query.
Query parameters
Using query parameters it is possible to convert file which is accessible by URL or uploaded File ID.
GET/POST https://v2.convertapi.com/convert/docx/to/pdf?Secret=XXX&File=http://example.com/myfile.docx&StoreFile=true
If there is an array type parameter, index must be appended to parameter name e.g. Files[0], Files[1], Files[2] etc.
Conversion response content types and schemes
Response headers and body contains this information:
- ConversionTime - time in seconds that took to convert file. In this amount of seconds your balance will be decreased after conversion.
- FileName - name of converted file.
- FileSize - converted file size in bytes.
- FileData - converted file content.
- FileUrl - link to converted file if "StoreFile" parameter is set to "true".
application/json
Response scheme can be explored in Test Request response box.
{ "ConversionTime": 2, "Files": [ { "FileName": "my_file.pdf", "FileSize": 523672, "FileData": "--Base64 encoded file content--" } ] }
application/xml
XML scheme is analogous to JSON.
<Conversion xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <ConversionTime>2</ConversionTime> <Files> <File> <FileName>my_file.pdf</FileName> <FileSize>522579</FileSize> <FileData>--Base64 encoded file content--</FileData> <Url i:nil="true" /> </File> </Files> </Conversion>
multipart/mixed
each part contains converted file data or URL to the file.
--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f ConversionTime: 3 Content-Type: application/octet-stream Content-Disposition: attachment; filename="my_file.pdf"; size=8475 --FILE CONTENT-- --43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f--
application/octet-stream
Response body is result file content. File name can be found in content-disposition header field. Can be used with converters that produce only one file result.
HTTP Response Codes
200
Conversion completed successfully.
401
Internal codes provided in response body:
- 4010 - Invalid user credentials - bad secret.
- 4011 - Invalid user credentials - bad token.
- 4012 - Invalid user credentials - bad self generated token.
- 4013 - User credentials not set, secret or token must be passed.
- 4014 - User inactive.
404
Internal codes provided in response body:
- 4040 - Parameter validation error.
- 4041 - No content disposition provided.
500
Internal codes provided in response body:
- 5000 - Conversion timeout.
- 5001 - Conversion failed.
- 5002 - PDF file is damaged.
- 5003 - File is password protected.
- 5004 - No tables to extract in PDF file.
- 5005 - Invalid URL format.
- 5006 - Invalid password.
- 5007 - Unable to download remote file.
- 5008 - Unable to access file from local storage.
- 5009 - File id is invalid.
- 50010 - File link is set incorrectly. Url or File Id must be set.
- 50011 - Can't delete.
502
Internal codes provided in response body:
- 5020 - Worker maximum parallel jobs reached.