This method returns an exception for a given person/transaction.
Path parameters
tguidstringRequired
Global unique ID of the transaction.
pguidstringRequired
Global unique ID of the person.
Responses
200
OK
application/json
404
Enrollment transaction does not exist, the exception does not exist
application/json
500
Internal Error
application/json
get
/exceptions/{tguid}/{pguid}
listExceptions
get
This method returns a list of exceptions that match the given search criteria.
Query parameters
startDateinteger · int64Optional
Minimum timestamp, in milliseconds.
endDateinteger · int64Optional
Maximum timestamp, in milliseconds.
userstringOptional
ID of the user.
keysstring[]Optional
Array of keys that uniquely identify the person. This field can be an expression.
The following structure can be used for both keys and biographics:
Format
Description
<id>:<value>
Searches for exceptions with incoming or reference keys/biographics with the passed id and value.
<id>:
Searches for exceptions with incoming or reference keys/biographics with the id and any value.
:<value>
Searches for exceptions with incoming or reference keys/biographics with the value and any id.
From the second keys/biographics item onwards, before each id or value, you can include an operator:
[and]: performs an AND operation with the previous item.
[or]: performs an OR operation with the previous item.
These operators may be applied to both keys and biographics.
On every operation on an id or value, the default behavior will be to test for exact matches.
To change this behavior, you can include a modifier at the end of the id or value:
[exact]: tests for exact matches. This is the default behavior, the same as not including any modifier.
[atstart]: searches for content that starts with the passed id/value.
[atend]: searches for content that ends with the passed id/value.
[anywhere]: searches for content that contains the passed id/value.
IMPORTANT: Be careful when using modifiers other than [exact]. They can slow down the search.
Examples:
keys=cpf:001&biographics=name
keys=cpf:001&keys=[or]cpf:002
keys=cpf:00[atstart]
biographicsstring[]Optional
Biographic data of the person. This field can be an expression.
For expressions, use the same structure described in the keys parameter.
labelsstring[]Optional
A list of labels of the person.
pageIndexinteger · int32Optional
pageSizeinteger · int32Optional
locekdUserstringOptional
prioritybooleanOptional
targetstring · enumOptionalPossible values:
Responses
200
OK
application/json
400
Validation Error
application/json
500
Internal Error
application/json
get
/exceptions
unassignException
delete
This method removes the assignment of a user to an exception.
Path parameters
tguidstringRequired
Global unique ID of the transaction.
pguidstringRequired
Global unique ID of the person.
Responses
204
Deleted
application/json
404
Exception does not exist
application/json
500
Internal Error
application/json
delete
/exceptions/{tguid}/{pguid}/users
listByTransaction
get
This method returns the exception list from a given exception.
Path parameters
tguidstringRequired
Global unique ID of the transaction.
Responses
200
OK
application/json
404
Enrollment transaction does not exist
application/json
500
Internal Error
application/json
get
/exceptions/{tguid}
assignException
put
This method assigns an exception to a given user.
Path parameters
tguidstringRequired
Global unique ID of the transaction.
pguidstringRequired
Global unique ID of the person.
userstringRequired
ID of the user.
Responses
201
OK
application/json
404
Exception does not exist
application/json
500
Internal Error
application/json
put
/exceptions/{tguid}/{pguid}/users/{user}
getTreatResult
get
This method returns the status of the treatment given to a specific transaction.
Path parameters
tguidstringRequired
Global unique ID of the transaction.
Responses
200
Ok, enqueued, Error
application/json
400
Validation Error
application/json
404
Exception treatment transaction does not exist
application/json
500
Internal Error
application/json
get
/exceptions/treatment/{tguid}
treatException
post
This method provides the treatment for a given exception.
Body
Responses
201
Enqueued
application/json
202
OK
application/json
400
Validation Error
application/json
403
User not authorized to treat exception.
application/json
404
Exception treatment transaction does not exist, exception does not exist
application/json
500
Internal Error
application/json
post
/exceptions/treatment
getExceptionByEntrantPguid
get
Path parameters
pguidstringRequired
Global unique ID of the person.
Responses
200
OK
application/json
400
Validation Error
application/json
500
Internal Error
application/json
get
/exceptions/byEntrant/{pguid}
getExceptionByReferencePguid
get
Path parameters
pguidstringRequired
Global unique ID of the person.
Responses
200
OK
application/json
400
Validation Error
application/json
500
Internal Error
application/json
get
/exceptions/byReference/{pguid}
Set exception priority
put
Sets or clears the priority flag for a specific exception identified by transaction GUID (tguid) and person GUID (pguid). When the priority path parameter is true, the exception—and its group—is prioritized; when false, the priority is removed. Returns 202 Accepted.
Path parameters
tguidstringRequired
pguidstringRequired
prioritybooleanRequired
Responses
202
ACCEPTED
application/json
put
/exceptions/{tguid}/{pguid}/priority/{priority}
202
ACCEPTED
Unlock biometric
delete
Unlocks a previously locked biometric candidate for a given transaction GUID (tguid), person GUID (pguid) and biometric index. When API security is enabled, the user is derived from the token; otherwise the user must be provided. Returns 204 No Content.
Unlocks a previously locked biometric candidate for a given transaction GUID (tguid), person GUID (pguid) and biometric index, specifying the user that holds the lock. Returns 204 No Content.
Applies a decision to all exceptions within a group. The request body must provide the group GUID (gguid), user (overwritten by the security token when API security is enabled), a list of permissions, comments, timeout, a decision (KEEP or REJECT) and decision parameters: keys (list of {id, value} pairs), biographics (list of {id, value} pairs), labels, keepTransactions and removeTransactions. Responds with 202 Accepted and data containing a status of PENDING or OK. PENDING indicates the treatment requires a follow‑up decision, while OK indicates the group was treated successfully. When status is OK and the decision is KEEP, the response may include newTguid, newPguid and a list of keptTguids.
Body
gguidstringOptional
userstringOptional
commentsstringOptional
timeoutinteger · int32Optional
decisionstring · enumOptionalPossible values:
permissionsstring[]Optional
Responses
202
ACCEPTED
application/json
post
/exceptions/treatment/group
202
ACCEPTED
Get group treatment result
get
Retrieves the treatment result for an exception group identified by its gguid. Returns 202 Accepted with the same data structure as the group treatment response, enabling clients to poll for the final status.
Path parameters
gguidstringRequired
Responses
202
ACCEPTED
application/json
get
/exceptions/treatment/group/{gguid}
202
ACCEPTED
Resolve pending group
post
Completes the treatment of a group left in PENDING status. The request must include the group GUID (gguid), user (overwritten by the security token when API security is enabled), permissions, a pendingTreatment flag (ACCEPT or REJECT), comments and an optional timeout. Responds with 202 Accepted and a data object containing status. A status of OK means the pending treatment was accepted and processed; a status of BIOGRAPHIC or BIOMETRIC_INCONCLUSIVE means the group returns to analysis. When treatment is accepted, newTguid, newPguid and keptTguids may be included.
Treats an uncertain biometric candidate that has been locked by the user. The request must include user (overwritten by the security token when API security is enabled), permissions, enrollTguid, exceptionPguid (the matched person), a decision (HIT, NO_HIT or UNCERTAIN_EXPERT), index and a timeout. Returns 202 Accepted with a data.status reflecting the outcome: ON, ENQUEUED or ERROR when all biometric treatments have been processed and the exception is treated as APPROVED; NOT_FINAL when further biometrics remain; BIOGRAPHIC, BIOMETRIC_MISMATCH or BIOMETRIC_INCONCLUSIVE when the treatments result in a biographic, mismatch or inconclusive target.
Body
enrollTguidstringOptional
exceptionPguidstringOptional
indexinteger · int32Optional
decisionstring · enumOptionalPossible values:
userstringOptional
timeoutinteger · int32Optional
permissionsstring[]Optional
Responses
202
ACCEPTED
application/json
post
/exceptions/treatment/biometric
202
ACCEPTED
Get biometric treatment result
get
Retrieves the treatment result for a biometric candidate identified by transaction GUID (tguid), person GUID (pguid) and biometric index. Returns 202 Accepted with the same data structure as the biometric treatment response, enabling clients to poll for the final status.
Retrieves the treatment result for a biometric candidate identified by aggregated GUID (aguid) and biometric index. This endpoint is used when dealing with aggregated transaction identifiers. Returns 202 Accepted with the same data structure as the biometric treatment response.
Re-executes the processing of transaction exceptions listed in the request, re-applying extraction/identification steps to correct failures.
Body
tguidsstring[]Optional
pageSizeinteger · int32Optional
userstringOptional
commentsstringOptional
justAnalysebooleanOptional
Responses
200
OK
application/json
put
/exceptions/reprocess
200
OK
Get exception reprocessing
get
Provides the progress and result of reprocessing a specific exception identified by the GUID.
Path parameters
guidstringRequired
Responses
200
OK
application/json
get
/exceptions/reprocess/{guid}
200
OK
Reprocess transaction in exception
put
Manually reprocesses a transaction in exception, provided in the body, returning the result of this re-execution.
Body
tguidstringOptional
userstringOptional
commentsstringOptional
justAnalysebooleanOptional
Responses
200
OK
application/json
put
/exceptions/reprocess/one
200
OK
Get next exception group
post
Selects and locks the next available exception group for analysis and treatment. The request includes a user (overwritten by the security token when API security is on), a list of organization permissions, an optional order (ASC or DESC) controlling the sort by priority, pending status and timestamp, and an origin (ENTRANT or BOTH) to filter by organization origin. Responds with 200 OK when a group is found, returning data with group details and remaining for the count of groups pending analysis or pending treatment. Returns 204 No Content when no group is available.
Body
userstringOptional
orderstring · enumOptionalPossible values:
permissionsstring[]Optional
originstring · enumOptionalPossible values:
pendingbooleanOptional
Responses
200
OK
application/json
post
/exceptions/nextGroup
200
OK
Get next biometric
post
Selects and locks the next uncertain biometric candidate requiring a manual decision. The request includes a user (overwritten by the security token when API security is enabled), a list of permissions, an order (ASC or DESC), an optional modality (FINGERPRINT or FACE) and an origin (ENTRANT or BOTH). If no biometric is available, responds with 204 No Content. Otherwise returns 200 OK with remaining for the number of remaining biometrics and data containing the selected biometric candidate: enrollPguid, enrollTguid, transactionTimestamp, match details (matchedPersonPguid, matchedPersonTguid, biometricMatches with score, queryIndex, referenceIndex, minutia and decision), exceptionAnalysis status (ANALYSIS), transactionType, priority and target.
Body
userstringOptional
orderstring · enumOptionalPossible values:
permissionsstring[]Optional
modalitystring · enumOptionalPossible values:
originstring · enumOptionalPossible values:
Responses
200
OK
application/json
204
NO CONTENT
application/json
post
/exceptions/nextBiometric
Get exception log
get
Retrieves detailed logs of transaction exception handling, allowing auditing by period, pguid, tguid and other parameters.
Query parameters
startDateinteger · int64Optional
endDateinteger · int64Optional
userstringOptional
operationstring · enumOptionalPossible values:
typestring · enumOptionalPossible values:
statusstring · enumOptionalPossible values:
decisionstring · enumOptionalPossible values:
indexinteger · int32Optional
pageIndexinteger · int32Optional
pageSizeinteger · int32Optional
Responses
200
OK
application/json
get
/exceptions/log
200
OK
List exception groups
get
Returns a paginated list of exception groups pending analysis or treatment. Use query parameters to filter by status, decision, date range, user, lockedUser, priority flag, target, organization, origin (ENTRANT, REFERENCE, BOTH), and pagination (pageIndex, pageSize). Groups are ordered by priority, pending status, target and creation time. Each group entry includes group identifiers (gguid, tguid), target, status, decision, priority flag, organizations with origin, timestamps, user, comments, and decision parameters such as keys, biographics, labels, kept and removed transactions.
Query parameters
startDateinteger · int64Optional
endDateinteger · int64Optional
userstringOptional
lockedUserstringOptional
prioritybooleanOptional
targetstring · enumOptionalPossible values:
organizationstring[]Optional
permissionstring[]Optional
userOrganizationsbooleanOptional
gguidstring[]Optional
keystring[]Optional
pageIndexinteger · int32Optional
pageSizeinteger · int32Optional
Responses
200
OK
application/json
get
/exceptions/group
200
OK
Get exception group
get
Retrieves details of an exception group by its GUID (gguid). The response includes the group metadata—gguid, tguid, target, status, decision, priority flag, organizations with origin, created and updated timestamps, user and comments—and the associated exceptions within the group. Each exception entry contains the enrollee identifiers, match details (score and index values), analysis status, transaction type, priority and target.
Path parameters
gguidstringRequired
Query parameters
permissionstring[]Optional
Responses
200
OK
application/json
get
/exceptions/group/{gguid}
200
OK
Lock exception group
put
Locks an unlocked exception group so that the current user can treat it. When API security is enabled, the user is derived from the token; otherwise a user must be provided. Returns 204 No Content upon success.
Path parameters
gguidstringRequired
Responses
204
NO CONTENT
application/json
put
/exceptions/group/{gguid}/user
204
NO CONTENT
Unlock exception group
delete
Unlocks a locked exception group for the current user (derived from the token) or for a provided user when API security is disabled. The group must be locked by that user. Returns 204 No Content.
Path parameters
gguidstringRequired
Responses
204
NO CONTENT
application/json
delete
/exceptions/group/{gguid}/user
204
NO CONTENT
Lock exception group for user
put
Locks an unlocked exception group for the specified user. This operation is used when API security is disabled and authentication through tokens is unavailable. Returns 204 No Content.
Path parameters
gguidstringRequired
userstringRequired
Responses
204
NO CONTENT
application/json
put
/exceptions/group/{gguid}/user/{user}
204
NO CONTENT
Unlock exception group for user
delete
Unlocks a previously locked exception group for a specified user. The group must be locked by the same user. Returns 204 No Content.
Path parameters
gguidstringRequired
userstringRequired
Responses
204
NO CONTENT
application/json
delete
/exceptions/group/{gguid}/user/{user}
204
NO CONTENT
Update refused status for group
put
Updates the refused status of an exception group. The status may be one of CREATED, REMOVED, READY_TO_RESEND, SENDING, SENT or ERROR. This endpoint sets the refused_status field for the group and returns 204 No Content.
Path parameters
gguidstringRequired
statusstring · enumRequiredPossible values:
Query parameters
permissionstring[]Optional
Responses
204
NO CONTENT
application/json
put
/exceptions/group/{gguid}/refused/{status}
204
NO CONTENT
Set priority flag for group
put
Sets or clears the priority flag on an exception group. When priority is true, the group and its contained exceptions are prioritized; when false, the priority is removed. Returns 204 No Content.
Path parameters
gguidstringRequired
prioritybooleanRequired
Responses
204
NO CONTENT
application/json
put
/exceptions/group/{gguid}/priority/{priority}
204
NO CONTENT
Get exception group by transaction
get
Retrieves the exception group associated with the specified transaction GUID (tguid). The returned structure is the same as retrieving a group by gguid.
Path parameters
tguidstringRequired
Query parameters
permissionstring[]Optional
Responses
200
OK
application/json
get
/exceptions/group/tguid/{tguid}
200
OK
Count exception groups
post
Counts the number of exception groups remaining for analysis or treatment and the number of group treatments performed by the user on the current day. The request body includes user (overwritten by the security token when API security is enabled), a list of permissions and an optional origin (ENTRANT or BOTH). The response returns remaining and doneByTheDay maps keyed by status.
Body
userstringOptional
permissionsstring[]Optional
originstring · enumOptionalPossible values:
Responses
200
OK
application/json
post
/exceptions/countGroups
200
OK
Count biometrics and decisions
post
Counts the number of remaining uncertain biometrics requiring treatment and the number of decisions made by the user on the current day. The request includes user (overwritten by the security token when API security is enabled), a list of permissions and an optional origin (ENTRANT or BOTH). The response returns remaining and doneByTheDay maps keyed by modality (FINGERPRINT and FACE).
