Objects

Add a face object

To add a new face object to a record of individuals, use the following method:

POST /objects/faces/

The added object contains a source photo, thumbnail, and other attributes.

Tip

• To add a new body object to a record of individuals, use /objects/bodies/ instead of /objects/faces/.

• To add a new vehicle object to a vehicle record, use /objects/cars/ instead of /objects/faces/.

The REQUEST BODY is required and contains multipart/form-data with the following parameters:

Name	Type	Description
create_from	string	Can contain one of the following reference expressions that identify a source object from which a new object will be created: detection:<detection_id>: use the id of an object detected in a source image with POST /detect. In the source_photo parameter, specify the same source image that was used with POST /detect. {face|body|car}event:<event_id>: use an event containing an object of a specific type (face, body, or car) to create a new object corresponding to the one from the event. The source_photo parameter must be empty when using this expression. {face|body|car}object:<object_id>: use an existing object of a specific type (face, body, or car) as a template to create a new object. The source_photo parameter must be empty when using this expression. Valid expressions for each method: POST /objects/faces/: faceevent:<event_id>, faceobject:<object_id>, detection:<detection_id>. POST /objects/bodies/: bodyevent:<event_id>, bodyobject:<object_id>, detection:<detection_id>. POST /objects/cars/: carevent:<event_id>, carobject:<object_id>, detection:<detection_id>.
detect_id	string	Auxiliary parameter.
mf_selector	enum	Defines the default behavior to apply when multiple objects are detected in the source image provided via the source_photo parameter, and the create_from parameter does not include the detection:<detection_id> expression. Default: reject. Allowed values: reject: reject the request if the source image contains multiple objects. biggest: select the largest object in the source image.
upload_list	integer	ID of a list of records grouped into a single batch upload. Service parameter used only by the frontend.
source_photo	binary	Source image. Required parameter if the create_from parameter includes the detection:<detection_id> expression. Otherwise, the parameter is optional.
frame_coords_left	integer	X-coordinate (in pixels) of the top-left corner of the object’s bounding box.
frame_coords_top	integer	Y-coordinate (in pixels) of the top-left corner of the object’s bounding box.
frame_coords_right	integer	X-coordinate (in pixels) of the bottom-right corner of the object’s bounding box.
frame_coords_bottom	integer	Y-coordinate (in pixels) of the bottom-right corner of the object’s bounding box.
active	boolean	If true, the added object will be active. Default: true.
card	integer	ID of the record that will store the added object. Required parameter.

CURL example

curl -X POST "http://<findface-ip:port>/objects/faces/" \
  -H "Authorization: Token <token>" \
  -H "Content-Type: multipart/form-data" \
  -F "create_from=detection:d1svumckd5qs72mq52b0" \
  -F "source_photo=@sample_face.jpg" \
  -F "card=1"

Tip

Replace sample_face.jpg with the full path if the file is not in your current working directory. Example: "source_photo=@/home/ubuntu/sample_face.jpg"

For example, to add a new face object, follow these steps:

1. Use the POST /detect method to detect a face in a photo and copy the id of the detected face.

2. Send the POST /objects/faces/ request with the following parameters:

   • create_from: specify the id from step 1 in the following format: detection:<detection_id>.

   • source_photo: provide the same image that was used in the POST /detect request.

   • card: specify the ID of the record to which the new face object will be added.

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

Note

* – means required parameters. 🆁 – read only.

Name	Type	Description
card*	integer	Record ID.
created_date*	date-time 🆁	Timestamp indicating when the object was created.
modified_date*	date-time 🆁	Timestamp indicating when the object was last updated.
source_photo_name*	string 🆁	Filename of the source image used to create the object.
source_photo	uri	URL of the source image file, whose name is specified in the source_photo_name parameter.
thumbnail*	uri 🆁	URL of the object’s thumbnail image.
frame_coords_left	integer	X-coordinate (in pixels) of the top-left corner of the object’s bounding box.
frame_coords_top	integer	Y-coordinate (in pixels) of the top-left corner of the object’s bounding box.
frame_coords_right	integer	X-coordinate (in pixels) of the bottom-right corner of the object’s bounding box.
frame_coords_bottom	integer	Y-coordinate (in pixels) of the bottom-right corner of the object’s bounding box.
active	boolean	true if the object is active. Default: true.
features*	object	Contains additional data as key-value pairs. Keys are arbitrary, and values can be strings, integers, floats, booleans, objects, arrays, or null.
id*	string 🆁	ID of the added object.
meta	object	Metadata.

Response example

{
 "card": 3,
 "created_date": "2025-06-09T16:00:12+00:00",
 "modified_date": "2025-06-09T16:00:12+00:00",
 "source_photo_name": "face1.jpg",
 "source_photo": "http://<findface-ip:port>/uploads/cards/Ad/3/face_face1_YB9Eep.jpg",
 "thumbnail": "http://<findface-ip:port>/uploads/cards/G0/3/face_face1_thumbnail_RNeQrf.jpg",
 "frame_coords_left": 722,
 "frame_coords_top": 31,
 "frame_coords_right": 801,
 "frame_coords_bottom": 132,
 "active": true,
 "features": {},
 "id": "4696237533220385428",
 "meta": {}
}

Useful requests

GET /objects/bodies/
POST /objects/bodies/
GET /objects/bodies/{id}/
DELETE /objects/bodies/{id}/
PATCH /objects/bodies/{id}/
GET /objects/cars/
POST /objects/cars/
GET /objects/cars/{id}/
DELETE /objects/cars/{id}/
PATCH /objects/cars/{id}/
GET /objects/faces/
POST /objects/faces/
GET /objects/faces/{id}/
DELETE /objects/faces/{id}/
PATCH /objects/faces/{id}/