Conversion API Documentation
Contents
Notes
- Base URL for all Requests in this specification is https://www.cometdocs.com/conversionApi/v1/
- All requests are made using HTTP POST method, unless otherwise noted.
- All responses are in JSON format.
- All successful API calls return HTTP status code 200, regardless of response status. To get response status, either parse 'X-Cometdocs-Api-Status' header, or check the 'status' key in JSON response. List of all status codes is provided here.
- All API methods require a token, which is obtained when registering a client.
Conventions
- Types are printed in monospace font
- Arrays are notated by adding square brackets to a type, eg: string[]
- Required parameters are printed in normal font
- Optional parameters are printed in italic
Methods
convert
| convertFromUrl
| getStatus
| getCallbackStatus
| download
| delete
| getConversionTypes
| getRemainingCredits
Converts a file to the specified conversion type. Maximum file size is limited to 128MB.
Use convertFromUrl if you need to convert larger files.
Note that you need to use multipart/form-data as Content-Type and provide the file under the key named 'file'.
Request
Param | Type | Description |
---|---|---|
token | string | Token (obtained when registering a client). |
file | string | File contents. |
conversionType | string | Conversion type. See getConversionTypes for a list of valid types. |
callbackUrl | string | URL that will be called when conversion is done. Details about conversion status will be provided as POST data (eg: jobId=1234&status=succeeded). |
testMode | bool | In test mode, no conversions actually take place and no credits are required. Use in development. |
Response
Param | Type | Description |
---|---|---|
jobId | string | Job ID. |
status | int | Request status. |
message | string | HR message. |
error | string | Detailed error description (in case of an error only). |
Example
URL
https://www.cometdocs.com/conversionApi/v1/convert
POST
---boundaryXYZ
Content-Disposition: form-data; name="file"; filename="sample.pdf" Content-Type: application/pdf
...file contents here...
---boundaryXYZ
Content-Disposition: form-data; name="token"
1234
---boundaryXYZ
Content-Disposition: form-data; name="conversionType"
PDF2DOC
---boundaryXYZ--
Content-Disposition: form-data; name="file"; filename="sample.pdf" Content-Type: application/pdf
...file contents here...
---boundaryXYZ
Content-Disposition: form-data; name="token"
1234
---boundaryXYZ
Content-Disposition: form-data; name="conversionType"
PDF2DOC
---boundaryXYZ--
Converts a file located at the specifed URL to the specified conversion type.
Request
Param | Type | Description |
---|---|---|
token | string | Token (obtained when registering a client). |
url | string | URL of the file. |
conversionType | string | Conversion type. See getConversionTypes for a list of valid types. |
callbackUrl | string | URL that will be called when conversion is done. Details about conversion status will be provided as POST data (eg: jobId=1234&status=succeeded). |
testMode | bool | In test mode, no conversions actually take place and no credits are required. Use in development. |
Response
Param | Type | Description |
---|---|---|
jobId | string | Job ID. |
status | int | Request status. |
message | string | HR message. |
error | string | Detailed error description (in case of an error only). |
Example
URL
https://www.cometdocs.com/conversionApi/v1/convertFromUrl
POST
token=1234&url=http://www.samplepdf.com/sample.pdf&conversionType=PDF2DOC
Returns the status of the specified job.
Request
Param | Type | Description |
---|---|---|
token | string | Token (obtained when registering a client). |
jobId | string | Job ID. |
Response
Param | Type | Description |
---|---|---|
jobStatus | string | Job status. See here for a list of job status codes. |
status | int | Request status. |
message | string | HR message. |
error | string | Detailed error description (in case of an error only). |
Example
URL
https://www.cometdocs.com/conversionApi/v1/getStatus
POST
token=1234&jobId=42
Returns the status of callback for the specified job.
Request
Param | Type | Description |
---|---|---|
token | string | Token (obtained when registering a client). |
jobId | string | Job ID. |
Response
Param | Type | Description |
---|---|---|
callbackAttempt | int | Number of callback attempts. Max is 4. |
callbackStatus | string | Callback status. |
callbackMessage | string | Callback message. |
status | int | Request status. |
message | string | HR message. |
error | string | Detailed error description (in case of an error only). |
Example
URL
https://www.cometdocs.com/conversionApi/v1/getCallbackStatus
POST
token=1234&jobId=42
Download converted file. If job was not successful (or still running), returns an error message. Otherwise sends the file as an attachment.
Request
Param | Type | Description |
---|---|---|
token | string | Token (obtained when registering a client). |
jobId | string | Job ID. |
Response
Param | Type | Description |
---|---|---|
status | int | Request status. |
message | string | HR message. |
error | string | Detailed error description (in case of an error only). |
Example
URL
https://www.cometdocs.com/conversionApi/v1/download
POST
token=1234&jobId=42
Deletes the specified job.
Request
Param | Type | Description |
---|---|---|
token | string | Token (obtained when registering a client). |
jobId | string | Job ID. |
Response
Param | Type | Description |
---|---|---|
status | int | Request status. |
message | string | HR message. |
error | string | Detailed error description (in case of an error only). |
Example
URL
https://www.cometdocs.com/conversionApi/v1/delete
POST
token=1234&jobId=42
Returns a list of valid conversion types. If inputExtension is provided, returns a list of valid conversion types for that extension only.
Request
Param | Type | Description |
---|---|---|
token | string | Token (obtained when registering a client). |
inputExtension | string | Input extension. |
Response
Param | Type | Description |
---|---|---|
conversionTypes | string[] | Valid conversion types. |
status | int | Request status. |
message | string | HR message. |
error | string | Detailed error description (in case of an error only). |
Example
URL
https://www.cometdocs.com/conversionApi/v1/getConversionTypes
POST
token=1234
Returns number of remaining conversion credits.
Request
Param | Type | Description |
---|---|---|
token | string | Token (obtained when registering a client). |
Response
Param | Type | Description |
---|---|---|
remainingCredits | int | Remaining credits. |
status | int | Request status. |
message | string | HR message. |
error | string | Detailed error description (in case of an error only). |
Example
URL
https://www.cometdocs.com/conversionApi/v1/getRemainingCredits
POST
token=1234
Status Codes
All methods return HTTP status code 200, regardless of exit status. To get exit status, you must parse a special header, named 'X-Cometdocs-Api-Status', or parse the value of 'status' key in JSON response. Possible status values are:
Status code | Message | Description |
---|---|---|
0 | OK | No errors |
1 | Internal error | Internal server error. Try again later. |
2 | Unsupported API method | Requested method does not exist. |
3 | Method invocation error | A required parameter is missing, of incorrect type or out of bounds. |
4 | HTTPS required | You must use HTTPS protocol to access API. |
5 | Invalid client token | Invalid client token. |
6 | Bad parameters | Value provided in parameter is invalid. |
7 | Bad job ID | Non-existant job ID (possibly deleted). |
8 | Conversion job failed | Specified conversion can not be downloaded because the job failed. |
9 | Conversion job not yet done | Specified conversion can not be downloaded because the job is not yet done. |
10 | Conversion job not yet started | Specified conversion can not be downloaded because the job has not yet started. |
11 | File download failed | Failed to download file from the specified URL. |
12 | Invalid conversion type | Specified conversion type is not valid. |
13 | Invalid file URL | Specified file URL is not valid. |
14 | Invalid callback URL | Specified callback URL is not valid. |
15 | File too large | File is larger than 128 MB. You need to use convertFromUrl method for such large files. |
16 | Insufficient credits | Conversion job cannot be completed due to insufficient credits. |
17 | Subscription expired | API Subscription expired or cancelled. |
Job Status Codes
Status code | Description |
---|---|
pending_download | About to start downloading input file |
downloading | Downloading input file |
download_failed | Input file download failed |
pending | About to start conversion |
started | Conversion running |
succeeded | Conversion succeeded |
failed | Conversion failed |
insufficient_credits | Client does not have enough conversion credits to perform the specified conversion |
Credits system
For each successful conversion, a pre-determined amount of credits is deducted from client account. This amount depends on the conversion type and file size, as seen in the table below.
Conversion type | Credits |
---|---|
PDF2XLS | 5 |
PDF2PPTX | 3 |
CC-IMG2DOC | 3 |
CC-IMG2XLS | 3 |
CC-IMG2TXT | 3 |
PDF2DXF | 2 |
PDF2DWG | 2 |
PDF2HTML | 2 |
CC-DOC2XLS | 2 |
CC-XLS2DOC | 2 |
All other conversion types | 1 |