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 |