Create a person record

Description

The method creates a new person record in the user’s list (default or specified). It supports multiple parameters for flexible integration and photo upload. Access requires a JWT token in the header or in the request body.

Request format

HTTP method: POST
URL: /person/create
Content-Type: multipart/form-data
Authorization: required

Request parameters

Parameter	Type	Where passed	Required	Description
token	string	Header, form-data	✅*	Permanent user token. If a temporary token is not specified in the «token» header, this parameter is required in the request body
list_id	string	form-data	❌	Identifier of the list where the person is added. By default, the primary list is used
group_id	string	form-data	❌	Identifier of the data source group
source_id	string	form-data	❌	Identifier of the data source
yaw	string/number	form-data	❌	Left/right face rotation angle
pitch	string/number	form-data	❌	Up/down face rotation angle
feature_check	array<string/object>	form-data	❌	List of detectable facial features
new_person_threshold	any	form-data	❌	Threshold for new face detection
new_person_square_min	any	form-data	❌	Minimum face side size in pixels
new_person_yaw_max	any	form-data	❌	Maximum yaw angle for a new face
new_person_pitch_max	any	form-data	❌	Maximum pitch angle for a new face
new_person_threshold_score	string/number	form-data	❌	Matching threshold by score
fields	array	form-data	❌	Business fields for the record
multi	boolean	form-data	❌	Process all faces in the image
replace_on_found	boolean	form-data	❌	ID of the record to replace
thumb	boolean	form-data	❌	Return thumbnail
normalized	boolean	form-data	❌	Return normalized image
bbox	boolean	form-data	❌	Return face bounding box coordinates
bbox_pro	boolean	form-data	❌	Return 4-point bounding box
drop_image	boolean	form-data	❌	Do not save image in history
embedding_only	boolean	form-data	❌	Return only embedding
embedding	string	form-data	❌	Vector representation of the face

One of the token transfer methods is required.

Example request (cURL)

curl -X POST "https://api.enface.ai/person/create" 
  -H "Authorization: Bearer jwt.temporary.token" 
  -F "list_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" 
  -F "group_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" 
  -F "source_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" 
  -F "fields=John" 
  -F "fields=Doe" 
  -F "multi=true" 
  -F "thumb=true" 
  -F "image=@/path/to/photo.jpg"

Response examples

Success (200 OK)

{
  "faces_total": 0,
  "message": "image format is unknown",
  "spent": 97,
  "status": "ok"
}

Operation completed, but no records added (201)

{
  "faces_total": 0,
  "matches": [],
  "message": "image format is unknown",
  "persons": [],
  "persons_new": 0,
  "persons_total": 0,
  "spent": 400,
  "status": "ok"
}

Error (400 Invalid schema)

{
  "message": "invalid schema",
  "status": "error"
}

Error (401 Unauthorized request)

{
  "message": "access denied",
  "status": "failed"
}