Metadata · Standard API · eKYC Core
Search metadata
Finds the faces whose embedded metadata matches the key/value pairs you search on, and returns each match with its face id, image id and metadata.
Request
Send the metadata key/value pairs to search on. Every face whose embedded metadata matched the search condition comes back with its own metadata attached.
| Name | Type | Required | Description |
|---|---|---|---|
metadata | dictionary | Required | list metadata key/value need search |
collection | string | Optional | search in face collection |
max_results | int | Optional | maximum results. Default is 10 |
If
collectionis not set, the default collection will be used.
{
"metadata": dictionary,
"collection": string,
"max_results": int
}
Sample request
curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/search_metadata \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json' \
-d \
'
{
"metadata": {
"national_id": "123456789"
}
}
'
Response
data.status carries the verdict. Once the request processing has finished the HTTP status code is 200 and data.status is either "success" or "failure" depending on whether the request was processed successfully — so a 200 says the search ran, not that anything matched. The errors array follows the shared response envelope.
{
"data": {
"request_id": string,
"status": string, // "success" or "failure"
"faces": [ // List faces have metadata matched with the search condition
{
"id": string, // id of the face in image
"image_id": string, // id of original image
"metadata": // list of meta data information of this face
{
"field": string, // "application_id": "123", "national_id": 123, ...
... // other fields
}
},
... // other face matched of metadata
],
},
"errors": [
{
"code": string,
"message": string,
"detail": {
"field": string, // optional, which parameter is invalid.
... // any other information that can be useful for client
},
},
... // other errors
]
}
A search on national_id that matched one face:
{
"data": {
"faces": [
{
"id": "d7e3bc6c-6562-4a6d-b6a7-c85cf69c5fae",
"image_id": "b35acc59-eefb-44fb-a6eb-ea02cec42cfc",
"metadata": {
"app_id": "5555",
"national_id": "6666"
}
}
],
"request_id": "59466df0-4815-49af-9652-622861b7a511",
"status": "success"
}
}
Failure codes
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 code | Error code | Description |
|---|---|---|
401 | access_denied_exception | You are not authorized to perform the action. |
400 | invalid_parameter_exception | Input parameter violates a constraint. |
400 | request_time_too_skewed | The X-TV-Timestamp header is expired, need a newer one. |
404 | image_not_found_exception | The image ID is not found in DB. |
404 | request_not_found_exception | The request ID is not found when polling result by id |
408 | request_timeout_exception | Request takes too long to process |
429 | rate_limit_exception | The number of requests exceeded your throughput limit. |
500 | internal_server_error | Some 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.