Image/File · Standard API · eKYC Core

Convert PDF to images

POST/v1/convert_pdf_sync

Converts the requested pages of an uploaded PDF into images and returns one image id per page.

Request

MethodPOST
Path/v1/convert_pdf_sync
Content-Typemultipart/form-data
Auth requiredYes — HMAC signing
NameTypeRequiredDescription
filefileRequiredthe PDF file to be uploaded
pagesarray of json objectRequiredlist of pages to convert to images with their labels and metadata
metadatadictionaryOptionalkey-value, key should be string, value should be string

Where each object in pages has following json format:

JSON
{
    "index": int, // index of the page, starts from 1
    "label": string, // label of the page image
    "metadata": {...}, // optional, any key-value metadata to store with the page image
}

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/convert_pdf_sync \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-F 'file=@"portrait.pdf"' \
-F 'pages="[{\"index\":1, \"label\": \"portrait\"}]"'

Response

data.status carries the verdict, and data.images lists one entry per converted page — the image's id, its page number in the PDF and its label.

JavaScript
{
    "data": {
        "status": string, "success" or "failure"
        "images": [ // list of converted images
            {
                "id": string, // ID of the image
                "page" int, // page number (1-indexed) in the PDF file
                "label": string, // label of the image
            },
        ],
        "request_id": string // return request id to the client and can use request-id to check logs.
    }
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

In case the request processing has been finished, the HTTP status code will be 200, and the data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.

Converting the first page of a PDF comes back like this:

JSON
{
    "data": {
        "images": [
            {
                "id": "081083a6-55e1-4eae-9c54-523edbae4390",
                "label": "portrait",
                "page": 1
            }
        ],
        "request_id": "0866d821-9548-4445-936c-3a593345fe11",
        "status": "success"
    }
}

Failure codes

If the data.status is "failure", the "errors" field will tell you why it failed.

Error codeDescription
page_does_not_existThe page number doesn't exist in the PDF file

In case of any other errors, the data field will be empty, and the server sends one of following HTTP status code with error code:

HTTP codeError codeDescription
401access_denied_exceptionYou are not authorized to perform the action.
413file_too_large_exceptionThe input file size exceeds the allowed limit (15MB).
415invalid_file_format_exceptionThe provided file format is not supported (PDF).
400invalid_parameter_exceptionInput parameter violates a constraint.
400request_time_too_skewedThe X-TV-Timestamp header is expired, need a newer one.
404image_not_found_exceptionThe image ID is not found in DB.
408request_timeout_exceptionRequest takes too long to process
429rate_limit_exceptionThe number of requests exceeded your throughput limit.
500internal_server_errorSome unexpected error occurs while processing the request

The codes above are the ones documented for this endpoint. Response errors on the Overview lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.