Record

List records

To retrieve a list of records of individuals, use the following method:

GET /cards/humans/

Tip

To retrieve a list of vehicle records, use /cards/cars/ instead of /cards/humans/.

The REQUEST contains the QUERY-STRING PARAMETERS. The list of all available parameters can be found at http://<findface-ip:port>/api-docs.

You can use this method to search for faces and bodies in the system.

CURL example

curl -X GET "http://<findface-ip:port>/cards/humans/?looks_like=detection:cf4ffvmv54rotim9jt60" \
 -H "Authorization: Token <token>"

If the response is successful (OK: 200), it returns a JSON object that contains the following parameters:

Name	Type	Description
`next_page`	string┃null	Next page.
`prev_page`	string┃null	Previous page.
`results`	[{…}]	Array containing the following parameters. Example.

Note

* – means required parameters. 🆁 – read only.

Name		Type	Description
`id*`		integer 🆁	Record ID.
`active`		boolean	`true` if the record is active.
`created_date*`		date-time 🆁	Timestamp indicating when the record was created.
`modified_date*`		date-time 🆁	Timestamp indicating when the record was last updated.
`name*`		string	Record name. Constraints: Min 1┃Max 256 chars.
`comment`		string	Extended description. Constraints: Min 0┃Max 2048 chars.
`watch_lists*`		array of integers	Array of related watch list IDs.
`looks_like*`		object	Present in the response only if the `looks_like` parameter is specified in the `GET /cards/humans/` request. Contains information about the most similar object in the record.
	`confidence*`	number	Value of the `looks_like_confidence` parameter. Constraints: Min 0┃Max 1.
	`collection*`	string┃null	Name of the object collection where the matched object was found (e.g., `face_objects` for the face collection).
	`matched_object*`	string┃null	ID of the matched object in the record.
`meta`		object	Metadata.
`looks_like_confidence*`		number 🆁	Present in the response if the `looks_like` parameter is specified in the `GET /cards/humans/` request. Indicates the similarity score between two feature vectors in the database: the feature vector of the object being searched for via the `looks_like` parameter and the feature vector of the matched object in the record. The value of the `looks_like_confidence` parameter is used when filtering results by the similarity score if the `threshold` parameter is specified.
`face_objects*`		integer 🆁	Total number of face objects in the record.
`body_objects*`		integer 🆁	Total number of body objects in the record.
`face_cluster*`		integer 🆁	ID of the face cluster that matched the record.
`body_cluster*`		integer 🆁	ID of the body cluster that matched the record.

Response example

{
 "next_page": null,
 "prev_page": null,
 "results": [
   {
     "id": 1,
     "active": true,
     "created_date": "2025-01-17T07:43:56.363330Z",
     "modified_date": "2025-01-17T11:56:42.496871Z",
     "name": "Angelina Jolie",
     "comment": "actor",
     "watch_lists": [
       2
     ],
     "looks_like": {
       "confidence": 0.8078,
       "collection": "face_objects",
       "matched_object": "4493493039043981648"
     },
     "meta": {},
     "looks_like_confidence": 0.8078,
     "face_objects": 1,
     "body_objects": 0,
     "face_cluster": 11,
     "body_cluster": null
   }
 ]
}

Create a new record

To create a new record for individuals, use the following method:

POST /cards/humans/

Tip

To create a vehicle record, use /cards/cars/ instead of /cards/humans/.

The REQUEST BODY is required and contains an application/json object with the following parameters:

Name	Type	Description
`active`	boolean	If `true`, the created record will be active.
`name*`	string	Record name. Constraints: Min 1┃Max 256 chars.
`comment`	string	Extended description. Constraints: Min 0┃Max 2048 chars.
`watch_lists*`	array of integers	Array of related watch list IDs.
`meta`	object	Metadata represented as an object with string keys and arbitrary values.

Request example

Tip

This example is provided for reference only. Substitute your own values in the corresponding fields. You only need to fill in the required fields; all other fields will use their default values.

{
 "active": false,
 "name": "A",
 "comment": "AAAAAA",
 "watch_lists": [
   0
 ],
 "meta": {}
}

For example, you can send these parameters:

{
 "active": true,
 "name": "new card",
 "comment": "sample",
 "watch_lists": [
   1
 ]
}

CURL example

curl -X POST "http://<findface-ip:port>/cards/humans/" \
 -H "Authorization: Token <token>" \
 -H "Content-Type: application/json" \
 -d '{"active":true,"name":"new card","comment":"sample","watch_lists":[1]}'

If the response is successful (Created: 201), it returns a JSON object that contains parameters. Example.

Response example

{
 "id": 24,
 "active": false,
 "created_date": "2025-07-21T15:26:52.435522Z",
 "modified_date": "2025-07-21T15:26:52.435560Z",
 "name": "new card",
 "comment": "sample",
 "watch_lists": [
   1
 ],
 "meta": {},
 "face_objects": 0,
 "body_objects": 0,
 "face_cluster": null,
 "body_cluster": null
}

Useful requests

GET /cards/cars/
POST /cards/cars/
GET /cards/cars/{id}/
DELETE /cards/cars/{id}/
PATCH /cards/cars/{id}/
GET /cards/cars/count/
GET /cards/humans/
POST /cards/humans/
GET /cards/humans/{id}/
DELETE /cards/humans/{id}/
PATCH /cards/humans/{id}/
GET /cards/humans/count/