Image/File · eKYC Core

Upload image

POST/v1/images

Uploads an image, as a file or as base64, and returns the image_id that every other eKYC Core API takes as its image reference.

Request

MethodPOST
Path/v1/images
Content-Typemultipart/form-data
Auth requiredYes — HMAC signing

Send the image either as a file in a multipart/form-data body or as base64-encoded text in an application/json body. Which of file and base64 is required follows from that choice.

NameTypeRequiredDescription
filefileRequired if content-type is multipart/form-datathe image file to be uploaded
base64stringRequired if content-type is application/jsonthe base64 of image file to be uploaded
labelstringRequiredlabel of the image as described at Label table
metadatastring_jsonOptionalkey-value, key should be string, value should be string, int, float, bool. Example {\"id\":\"123456789\", \"type\": 1}
tagstringOptionaltag of the image. India only

metadata is a JSON string holding key/value pairs as a dictionary. For a QR code image it can carry the raw decoded string:

JSON
{\"raw\": \"value\"}  // raw decoded string of the QR code.

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/images \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-F 'file=@"images/portrait.jpg"' \
-F 'label="portrait"'

Response

data.image_id is the id of the stored image, and it is what the rest of the eKYC Core APIs take as their image reference.

JavaScript
{
    "data": {
        "image_id": string, // ID of the uploaded image in StoreDB
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

On success the HTTP status code is 200 and data holds:

NameTypeDescription
image_idstringID of the uploaded image (UUID)

A successful upload comes back like this:

JSON
{
    "data": {
        "image_id": "20b457d2-cf11-4c2b-a491-8137ae6b0bc8"
    }
}

Failure codes

In case of error, the data will be empty, and server sends following HTTP status code and error information:

HTTP codeError codeDescription
400invalid_parameter_exceptionInput parameter violates a constraint.
400request_time_too_skewedThe X-TV-Timestamp header is expired, need a newer one.
401access_denied_exceptionYou are not authorized to perform the action.
404image_not_found_exceptionThe image ID is not found in DB.
413image_too_large_exceptionThe input image size exceeds the allowed limit (15MB).
415invalid_image_format_exceptionThe provided image format is not supported (JPG/PNG)
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 lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.