Upload Image

Uploads an image to FaceAuthen and returns an image_id. This is the mandatory first step for every other service — all downstream APIs take an image_id rather than raw image bytes.

Endpoint

POST /v1/images
Content-Type: multipart/form-data

Parameters:

Param	Type	Required	Default	Description
file	file	Yes	—	The image file to be uploaded. JPG or PNG, max 15MB.
label	string	Yes	—	The image label. Must be one of the values in Usage Recommendations.
metadata	string_json	No	{}	JSON string of key/value pairs. Keys are strings; values are string, int, float or bool. Example: {"id":"<ID>","type":1}

Returns: UploadImageResponse

Use portrait for a selfie captured by the camera and portrait_nfc for a portrait read from the NFC chip.

Sample Request

curl -X POST \
  '<BASE_URL>/v1/images' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -F 'file=@"images/portrait.jpg"' \
  -F 'label="portrait"'

Device Signature (SDK Requests)

When the Mobile SDK uploads with the transaction token (Authorization: Bearer …), it also sends Device-Id, X-Device-Key-Id and X-Device-Signature on a tenant with the device signature check enabled, signed over the raw multipart body exactly as sent. The credential named by X-Device-Key-Id must be ACTIVE and registered for the same Device-Id; otherwise the request is rejected with access_denied_exception. See Request Signing.

Response

{
  "data": {
    "image_id": "20b457d2-cf11-4c2b-a491-8137ae6b0bc8"
  },
  "errors": [],
  "success": true,
  "code": 0,
  "message": "Success"
}

Field	Type	Description
data.image_id	string	UUID of the uploaded image in StoreDB. Pass this to every other API.
errors	array	Detail of each failure. Empty on success.
success	bool	Whether the call succeeded.
code	int	Numeric status code — 0 on success.
message	string	Status message.

On success the HTTP status is 200. An HTTP 200 alone is not enough — check success and data.status before treating the upload as complete.

Errors

When success is false, one of these numeric codes is returned:

Code	Message
2001010	Access ID not found.
2001014	Register rate limit exceeded.
2001015	Register brute force limit exceeded.
401100	You are not authorized to perform the action.
4001000	Input parameter violates a constraint.
4001001	The X-TV-Timestamp header is expired, need a newer one.
4041001	User not found.
4091000	The cus_user_id has been registered.
4291000	The number of requests exceeded your throughput limit.
5001000	Some unexpected error occurs while processing the request.

The errors array carries one or more detailed error codes:

Code	Description
invalid_parameter_exception	Input parameter violates a constraint.
request_time_too_skewed	The X-TV-Timestamp header is expired, need a newer one.
access_denied_exception	You are not authorized to perform the action.
image_not_found_exception	The image ID is not found in DB.
image_too_large_exception	The input image size exceeds the allowed limit (15MB).
invalid_image_format_exception	The provided image format is not supported (JPG/PNG).
rate_limit_exception	The number of requests exceeded your throughput limit.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Usage Recommendations — the full label vocabulary
• Register Faces — enrol using the image IDs returned here
• Verify Face Authen — authenticate using the image IDs returned here