# Searches

## getSearchResult

> This method returns the result of a search operation, given its TGUID. \<br>\<br> Use the \`searchFields\` query parameter to control the fields included in the response.

```json
{"openapi":"3.0.1","info":{"title":"GBDS API","version":"5.1.16"},"servers":[{"url":"http://<ip>:8085/gbds/v2"}],"paths":{"/people/searches/{tguid}":{"get":{"description":"This method returns the result of a search operation, given its TGUID. <br><br> Use the `searchFields` query parameter to control the fields included in the response.","tags":["searches"],"operationId":"getSearchResult","summary":"getSearchResult","parameters":[{"name":"tguid","description":"Global unique ID of the transaction.","in":"path","required":true,"schema":{"type":"string"}},{"name":"searchFields","in":"query","description":"<br> Specify the level of detail to include in the search response. The options are:\n- **NO_FIELDS**: Standard response. Only `tguid`, `status`, `score`, `bonafideScore` are possibly returned. (See specific rules for score and bonafideScore in the response model)\n- **BASIC_FIELDS**: Adds the fields: `progress`, `searchType`, `apiID`, `gbdsVersion`, `extractionElapsed`, `searchElapsed`, `postSearchElapsed`, `ulsearch`, and `latentSearch` to the standard response.\n- **CANDIDATES**: Adds the candidate list to the standard response.\n- **BIOMETRICS**: Adds the biometrics list to the standard response.\n- **ALL_FIELDS**: Includes all of the above in the response.\n","required":false,"schema":{"type":"string","enum":["NO_FIELDS","BASIC_FIELDS","CANDIDATES","BIOMETRICS","ALL_FIELDS"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSearchesResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}}}}}},"components":{"schemas":{"GetSearchesResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Search"}}},"Search":{"type":"object","properties":{"status":{"description":"Status of the search.","type":"string","enum":["ENQUEUED","PREPARED","PROCESSING","MATCH","NOT_MATCH","FAILED","PENDING","PERSON_NOT_FOUND"]},"tguid":{"description":"Search transaction TGUID.","type":"string"},"candidates":{"description":"List of match candidates.","type":"array","items":{"$ref":"#/components/schemas/MatchBob"}},"progress":{"type":"number","format":"float"},"request":{"$ref":"#/components/schemas/SearchSpec"},"failReason":{"description":"Fail message on why search didn't complete.","type":"string"},"searchType":{"description":"Type of finger that was searched.","type":"string","enum":["SAME_FINGERS","ALL_FINGERS","CROSSED_WINDOW_TWEEZERS"]},"biometrics":{"description":"List of biometrics","type":"array","items":{"$ref":"#/components/schemas/Biometric"}},"apiID":{"description":"API ID","type":"string"},"gbdsVersion":{"description":"GBDS Version","type":"string"},"extractionElapsed":{"description":"Time to complete the extraction.","type":"integer","format":"int64"},"searchElapsed":{"description":"Time to complete the search.","type":"integer","format":"int64"},"postSearchElapsed":{"description":"Time to complete the post match.","type":"integer","format":"int64"},"ulsearch":{"description":"Unsolved latent search.","type":"boolean"},"latentSearch":{"description":"Latent search.","type":"boolean"},"score":{"description":"Score of the biometric comparison. Only returned if a single biometric was provided in the payload of the request that created the search.","type":"integer","format":"int32"},"bonafideScore":{"description":"Bonafide score of the liveness verification. Only returned if the `liveness` flag was set to `true` in the payload of the request that created the search. Ranges from 0 to 100 (0=attack, 100=genuine).","type":"integer","format":"int32"},"metadata":{"$ref":"#/components/schemas/SearchMetadata"}}},"MatchBob":{"type":"object","properties":{"matchedPersonPguid":{"description":"PGUID of the person the candidate matched against.","type":"string"},"matchedPersonTguid":{"description":"TGUID of the person the candidate matched against.\n\nReturned at this level only when Best of Biometrics (**BoB**) is **DISABLED**. Otherwise, omitted here and **one TGUID per biometric** is returned at the `biometricMatches` level (child).\n","type":"string"},"biometricMatches":{"description":"Information about the match.","type":"array","items":{"$ref":"#/components/schemas/BiometricMatchBob"}}}},"BiometricMatchBob":{"type":"object","properties":{"matchedPersonTguid":{"description":"TGUID of the person the candidate matched against.\n\nReturned at this level only when Best of Biometrics (**BoB**) is **ENABLED**. Otherwise, omitted here and only **one TGUID per candidate** is returned at the `candidates` level (parent).\n","type":"string","format":"uuid"},"score":{"description":"Score of the match.","type":"integer","format":"int32"},"queryIndex":{"description":"Index of the biometric data that was sent and caused a match.","type":"integer","format":"int32"},"referenceIndex":{"description":"Index of the biometric data, from the already enrolled person, which matched.","type":"integer","format":"int32"},"minutia":{"description":"Array of minutia matches. Returned only for latent searches.","type":"array","items":{"$ref":"#/components/schemas/Minutiae"}}}},"Minutiae":{"type":"object","properties":{"query":{"description":"Index of Minutiae, from the provided biometric data, which was involved in the match.","type":"integer","format":"int32"},"reference":{"description":"Index of Minutiae, from biometric data already in the database, which was involved in the match.","type":"integer","format":"int32"}}},"SearchSpec":{"type":"object","properties":{"searchType":{"description":"Type of finger to be searched.","type":"string","enum":["SAME_FINGERS","ALL_FINGERS","CROSSED_WINDOW_TWEEZERS"]},"biometric":{"description":"If only one biometric is provided, a match score will be returned. If more than one biometric is provided, a list of candidates can be retrieved using getSearchResult.","type":"array","items":{"$ref":"#/components/schemas/Biometric"}},"keys":{"type":"array","items":{"$ref":"#/components/schemas/Key"}},"pguids":{"description":"This field is a list of PGUIDs. If the list is empty or null, the search will be against the entire database. If it has only one PGUID, the search will be 1:1. It is possible to make 1:1 searches with more than one PGUID.","type":"array","items":{"type":"string"}},"labelFilters":{"description":"Used for 1:N operations. The filters will be compared with the labels field registered by the enroll method.","uniqueItems":true,"type":"array","items":{"type":"string"}},"isLatentSearch":{"description":"Flag indicating if the search is a Latent Search.","type":"boolean"},"isULSearch":{"description":"Flag indicating if the search is an UL Search.","type":"boolean"},"numberOfCandidates":{"description":"Number of candidates to be returned.","type":"integer","format":"int32"},"classificationThreshold":{"description":"Threshold for either classifying biometric data or marking it as UNKNOWN.","type":"integer","format":"int32"},"classifications":{"description":"Vector containing the classifications to be considered. Defaults to UNKNOWN.","uniqueItems":true,"type":"array","items":{"type":"string","enum":["PLAIN_ARCH","LEFT_LOOP","RIGHT_LOOP","WHORL","SCAR","UNKNOWN","AMPUTATION","OTHER"]}},"singularities":{"description":"Singularities to be considered. Defaults to NONE.","type":"string","enum":["NONE","NO_DELTA_ALL_CORES","ONE_DELTA_NO_CORES","ONE_DELTA_ALL_CORES"]},"latentSearchOptions":{"$ref":"#/components/schemas/LatentSearchOptions"},"searchOptions":{"$ref":"#/components/schemas/SearchOptions"},"user":{"type":"string"},"uguids":{"description":"Globally unique ID of the UL. Can be a list of uguids.","type":"array","items":{"type":"string"}},"liveness":{"description":"Flag to request liveness verification on query face image. If activated, a bonafide score will be returned.","type":"boolean"}}},"Biometric":{"type":"object","oneOf":[{"$ref":"#/components/schemas/CONSOLIDATED_TEMPLATE"},{"$ref":"#/components/schemas/TEMPLATE"},{"$ref":"#/components/schemas/ORIGINAL"}],"discriminator":{"propertyName":"source"}},"CONSOLIDATED_TEMPLATE":{"title":"CONSOLIDATED_TEMPLATE","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["CONSOLIDATED_TEMPLATE"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"BiometricProperties":{"type":"object","properties":{"width":{"description":"Width, in pixels, of the image. If 0, GBDS will try to extract this information from the image header.","type":"integer","format":"int32"},"height":{"description":"Height, in pixels, of the image. If 0, GBDS will try to extract this information from the image header.","type":"integer","format":"int32"},"resolution":{"description":"Image or template resolution.","type":"integer","format":"int32"},"ratio":{"description":"Proportion of the image.","type":"number","format":"double"},"matcherId":{"description":"ID of the Biometric Matcher to be used in verification and identification operations.","type":"integer","format":"int32"},"extractorId":{"description":"ID of the extractor to be used on the image.","type":"integer","format":"int32"}}},"TEMPLATE":{"title":"TEMPLATE","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["TEMPLATE"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"ORIGINAL":{"title":"ORIGINAL","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["ORIGINAL"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","VOICE","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["RAW","WSQ","JPEG","JPEG2000","PNG","TIFF","GIF","BMP","PCM","WAV","PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"Key":{"type":"object","properties":{"id":{"description":"Name of entity identifier.","type":"string"},"value":{"description":"Value of entity identifier.","type":"string"}}},"LatentSearchOptions":{"type":"object","properties":{"scoreThreshold":{"description":"Search score threshold.","type":"integer","format":"int32"},"rotationAngleThreshold":{"description":"Rotation angle threshold for searching.","type":"integer","format":"int32"}}},"SearchOptions":{"type":"object","properties":{"biometricType":{"description":"biometricType must contain its data and be one of the following values - FINGERPRINT, PALMPRINT, FACE, IRIS, NEWBORN_PALMPRINT, i.e., you must substitute the \"biometricType\" field name by one of the ENUM names.","type":"object","properties":{"scoreThreshold":{"description":"Search score threshold.","type":"integer","format":"int32"},"rotationAngleThreshold":{"description":"Rotation angle threshold for searching.","type":"integer","format":"int32"},"matcher":{"description":"Define which ginger preset will be used.","type":"string","enum":["DEFAULT","MOBILE"]}}}}},"SearchMetadata":{"description":"Additional information.","type":"object","additionalProperties":{"description":"A flexible key-value pair where the key is a string."}},"ValidationError":{"type":"object","properties":{"type":{"description":"Type of the Error","type":"string","enum":["VALIDATION_ERROR"]},"code":{"description":"Internal error code.","type":"string","enum":["MISSING_PGUID","MISSING_PERSON","MISSING_BIOMETRIC","INVALID_PARAMETER_COMBINATION","MISSING_REQUIRED_QUERY_PARAMETER","MISSING_REQUIRED_ENTITY_ATTRIBUTE","UNKNOWN_ENTITY_ATTRIBUTE","QUERY_PARAMETER_OUT_OF_RANGE","PARAMETER_OUT_OF_RANGE","PGUID_IS_EMPTY","FORBIDDEN_ATTRIBUTE_SET","INVALID_TOKEN_GRANT_SPEC","INVALID_ENUM_VALUE","MALFORMED_JSON","INVALID_JSON_ATTRIBUTE_VALUE","INVALID_URL_ATTRIBUTE_VALUE","UNKNOWN_REQUEST_READ_ERROR","PAGE_NOT_FOUND","UNSUPPORTED_HTTP_METHOD"]},"message":{"description":"Message detailing the nature of the Error","type":"string"},"meta":{"description":"Contains extra information about the API call.","type":"object"}}},"InternalError":{"type":"object","properties":{"type":{"description":"Type of the Error","type":"string","enum":["INTERNAL_ERROR"]},"code":{"description":"Internal error code.","type":"string","enum":["DRIVER_OFFLINE","CREDENTIAL_SERVER_CONNECTION_ERROR","CLIENT_NOT_INITIALIZE","TRUSTED_ENROLL_WITH_PENDING_STATUS","SUBJECT_NOT_SET","UNKNOWN"]},"message":{"description":"Message detailing the nature of the Error","type":"string"},"meta":{"description":"Contains extra information about the API call.","type":"object"}}}}}}
```

## search

> This method performs a biometric search a returns the people that match the search criteria.

```json
{"openapi":"3.0.1","info":{"title":"GBDS API","version":"5.1.16"},"servers":[{"url":"http://<ip>:8085/gbds/v2"}],"paths":{"/people/searches":{"post":{"description":"This method performs a biometric search a returns the people that match the search criteria.","tags":["searches"],"operationId":"search","summary":"search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSearchRequest"}}},"required":true},"responses":{"201":{"description":"Created, match, not match","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSearchResponse"}}}},"202":{"description":"Enqueued, processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSearchResponse"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"404":{"description":"Person does not exist (if a PGUID is provided)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessingError"}}}},"422":{"description":"Processing Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessingError"}}}},"500":{"description":"Internal Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}}},"parameters":[]}}},"components":{"schemas":{"CreateSearchRequest":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SearchSpec"},"meta":{"$ref":"#/components/schemas/SearchMeta"}}},"SearchSpec":{"type":"object","properties":{"searchType":{"description":"Type of finger to be searched.","type":"string","enum":["SAME_FINGERS","ALL_FINGERS","CROSSED_WINDOW_TWEEZERS"]},"biometric":{"description":"If only one biometric is provided, a match score will be returned. If more than one biometric is provided, a list of candidates can be retrieved using getSearchResult.","type":"array","items":{"$ref":"#/components/schemas/Biometric"}},"keys":{"type":"array","items":{"$ref":"#/components/schemas/Key"}},"pguids":{"description":"This field is a list of PGUIDs. If the list is empty or null, the search will be against the entire database. If it has only one PGUID, the search will be 1:1. It is possible to make 1:1 searches with more than one PGUID.","type":"array","items":{"type":"string"}},"labelFilters":{"description":"Used for 1:N operations. The filters will be compared with the labels field registered by the enroll method.","uniqueItems":true,"type":"array","items":{"type":"string"}},"isLatentSearch":{"description":"Flag indicating if the search is a Latent Search.","type":"boolean"},"isULSearch":{"description":"Flag indicating if the search is an UL Search.","type":"boolean"},"numberOfCandidates":{"description":"Number of candidates to be returned.","type":"integer","format":"int32"},"classificationThreshold":{"description":"Threshold for either classifying biometric data or marking it as UNKNOWN.","type":"integer","format":"int32"},"classifications":{"description":"Vector containing the classifications to be considered. Defaults to UNKNOWN.","uniqueItems":true,"type":"array","items":{"type":"string","enum":["PLAIN_ARCH","LEFT_LOOP","RIGHT_LOOP","WHORL","SCAR","UNKNOWN","AMPUTATION","OTHER"]}},"singularities":{"description":"Singularities to be considered. Defaults to NONE.","type":"string","enum":["NONE","NO_DELTA_ALL_CORES","ONE_DELTA_NO_CORES","ONE_DELTA_ALL_CORES"]},"latentSearchOptions":{"$ref":"#/components/schemas/LatentSearchOptions"},"searchOptions":{"$ref":"#/components/schemas/SearchOptions"},"user":{"type":"string"},"uguids":{"description":"Globally unique ID of the UL. Can be a list of uguids.","type":"array","items":{"type":"string"}},"liveness":{"description":"Flag to request liveness verification on query face image. If activated, a bonafide score will be returned.","type":"boolean"}}},"Biometric":{"type":"object","oneOf":[{"$ref":"#/components/schemas/CONSOLIDATED_TEMPLATE"},{"$ref":"#/components/schemas/TEMPLATE"},{"$ref":"#/components/schemas/ORIGINAL"}],"discriminator":{"propertyName":"source"}},"CONSOLIDATED_TEMPLATE":{"title":"CONSOLIDATED_TEMPLATE","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["CONSOLIDATED_TEMPLATE"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"BiometricProperties":{"type":"object","properties":{"width":{"description":"Width, in pixels, of the image. If 0, GBDS will try to extract this information from the image header.","type":"integer","format":"int32"},"height":{"description":"Height, in pixels, of the image. If 0, GBDS will try to extract this information from the image header.","type":"integer","format":"int32"},"resolution":{"description":"Image or template resolution.","type":"integer","format":"int32"},"ratio":{"description":"Proportion of the image.","type":"number","format":"double"},"matcherId":{"description":"ID of the Biometric Matcher to be used in verification and identification operations.","type":"integer","format":"int32"},"extractorId":{"description":"ID of the extractor to be used on the image.","type":"integer","format":"int32"}}},"TEMPLATE":{"title":"TEMPLATE","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["TEMPLATE"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"ORIGINAL":{"title":"ORIGINAL","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["ORIGINAL"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","VOICE","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["RAW","WSQ","JPEG","JPEG2000","PNG","TIFF","GIF","BMP","PCM","WAV","PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"Key":{"type":"object","properties":{"id":{"description":"Name of entity identifier.","type":"string"},"value":{"description":"Value of entity identifier.","type":"string"}}},"LatentSearchOptions":{"type":"object","properties":{"scoreThreshold":{"description":"Search score threshold.","type":"integer","format":"int32"},"rotationAngleThreshold":{"description":"Rotation angle threshold for searching.","type":"integer","format":"int32"}}},"SearchOptions":{"type":"object","properties":{"biometricType":{"description":"biometricType must contain its data and be one of the following values - FINGERPRINT, PALMPRINT, FACE, IRIS, NEWBORN_PALMPRINT, i.e., you must substitute the \"biometricType\" field name by one of the ENUM names.","type":"object","properties":{"scoreThreshold":{"description":"Search score threshold.","type":"integer","format":"int32"},"rotationAngleThreshold":{"description":"Rotation angle threshold for searching.","type":"integer","format":"int32"},"matcher":{"description":"Define which ginger preset will be used.","type":"string","enum":["DEFAULT","MOBILE"]}}}}},"SearchMeta":{"description":"Contains extra information about the API call.","type":"object","properties":{"timeout":{"description":"Time, in milliseconds, waiting for the completion of the operation. If this value is -1, then the method is fully synchronous. If the timeout value is 0, then the method is fully asynchronous. If>0, the call expires after this time (in milliseconds).","type":"integer","format":"int32"},"priority":{"description":"Priority of the operation.","type":"string","enum":["GOD_PRIORITY","HIGHEST_PRIORITY","HIGHER_PRIORITY","HIGH_PRIORITY","DEFAULT_PRIORITY","LOW_PRIORITY","LOWER_PRIORITY","LOWEST_PRIORITY"]},"metadata":{"$ref":"#/components/schemas/SearchMetadata"},"verifyResult":{"type":"boolean","description":"Flag to request the result of the Verification call (Verify - when keys and/or PGUIDs are provided). Default: `false`.\n\nIf `false`, the Verify will return:\n- `tguid`\n- `status`\n- `score` (if only one biometric was provided in the request payload and the `searchType` is `SAME_FINGERS`; if more than one biometric was provided, the score will not be returned)\n- `bonafideScore` (for faces, if the data->`liveness` flag is set to `true` in the request payload)\n\nIf `true`, the Verify will return all above plus:\n- `candidates` (if more than one biometric is provided, candidates will be returned and the score will not be returned)\n- `progress`\n- `searchType`\n- `metadata`\n- `apiID`\n- `gbdsVersion`\n- `extractionElapsed`\n- `searchElapsed`\n- `postSearchElapsed`\n- `ulsearch`\n- `latentSearch`\n\nPS: `biometrics` are never returned in the response.\n"}}},"SearchMetadata":{"description":"Additional information.","type":"object","additionalProperties":{"description":"A flexible key-value pair where the key is a string."}},"CreateSearchResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"description":"Status of the search.","type":"string","enum":["ENQUEUED","PROCESSING","MATCH","NOT_MATCH","FAILED"]},"tguid":{"description":"Search transaction TGUID.","type":"string"},"score":{"description":"Biometric comparison score. <br><br> Only returned if a **single** biometric was provided in the request payload and the `searchType` is `SAME_FINGERS`.","type":"integer","format":"int32"},"bonafideScore":{"description":"Bonafide score of the liveness verification. <br><br> Only returned for **faces** and if the `liveness` flag was set to `true` in the request payload. Ranges from 0 to 100. (0=attack, 100=genuine).","type":"integer","format":"int32"},"candidates":{"description":"List of match candidates. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"array","items":{"$ref":"#/components/schemas/MatchBob"}},"progress":{"description":"Progress. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"number","format":"float"},"searchType":{"description":"Type of finger that was searched. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"string","enum":["SAME_FINGERS","ALL_FINGERS","CROSSED_WINDOW_TWEEZERS"]},"metadata":{"allOf":[{"description":"Additional Information. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*"},{"$ref":"#/components/schemas/SearchMetadata"}]},"apiID":{"description":"API ID. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"string"},"gbdsVersion":{"description":"GBDS Version. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"string"},"extractionElapsed":{"description":"Time to complete the extraction. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"integer","format":"int64"},"searchElapsed":{"description":"Time to complete the search. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"integer","format":"int64"},"postSearchElapsed":{"description":"Time to complete the post match. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"integer","format":"int64"},"ulsearch":{"description":"Unsolved latent search. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"boolean"},"latentSearch":{"description":"Latent search. <br><br> *(Only returned if meta->`verifyResult` is `true` in the request payload)*","type":"boolean"}}}}},"MatchBob":{"type":"object","properties":{"matchedPersonPguid":{"description":"PGUID of the person the candidate matched against.","type":"string"},"matchedPersonTguid":{"description":"TGUID of the person the candidate matched against.\n\nReturned at this level only when Best of Biometrics (**BoB**) is **DISABLED**. Otherwise, omitted here and **one TGUID per biometric** is returned at the `biometricMatches` level (child).\n","type":"string"},"biometricMatches":{"description":"Information about the match.","type":"array","items":{"$ref":"#/components/schemas/BiometricMatchBob"}}}},"BiometricMatchBob":{"type":"object","properties":{"matchedPersonTguid":{"description":"TGUID of the person the candidate matched against.\n\nReturned at this level only when Best of Biometrics (**BoB**) is **ENABLED**. Otherwise, omitted here and only **one TGUID per candidate** is returned at the `candidates` level (parent).\n","type":"string","format":"uuid"},"score":{"description":"Score of the match.","type":"integer","format":"int32"},"queryIndex":{"description":"Index of the biometric data that was sent and caused a match.","type":"integer","format":"int32"},"referenceIndex":{"description":"Index of the biometric data, from the already enrolled person, which matched.","type":"integer","format":"int32"},"minutia":{"description":"Array of minutia matches. Returned only for latent searches.","type":"array","items":{"$ref":"#/components/schemas/Minutiae"}}}},"Minutiae":{"type":"object","properties":{"query":{"description":"Index of Minutiae, from the provided biometric data, which was involved in the match.","type":"integer","format":"int32"},"reference":{"description":"Index of Minutiae, from biometric data already in the database, which was involved in the match.","type":"integer","format":"int32"}}},"ValidationError":{"type":"object","properties":{"type":{"description":"Type of the Error","type":"string","enum":["VALIDATION_ERROR"]},"code":{"description":"Internal error code.","type":"string","enum":["MISSING_PGUID","MISSING_PERSON","MISSING_BIOMETRIC","INVALID_PARAMETER_COMBINATION","MISSING_REQUIRED_QUERY_PARAMETER","MISSING_REQUIRED_ENTITY_ATTRIBUTE","UNKNOWN_ENTITY_ATTRIBUTE","QUERY_PARAMETER_OUT_OF_RANGE","PARAMETER_OUT_OF_RANGE","PGUID_IS_EMPTY","FORBIDDEN_ATTRIBUTE_SET","INVALID_TOKEN_GRANT_SPEC","INVALID_ENUM_VALUE","MALFORMED_JSON","INVALID_JSON_ATTRIBUTE_VALUE","INVALID_URL_ATTRIBUTE_VALUE","UNKNOWN_REQUEST_READ_ERROR","PAGE_NOT_FOUND","UNSUPPORTED_HTTP_METHOD"]},"message":{"description":"Message detailing the nature of the Error","type":"string"},"meta":{"description":"Contains extra information about the API call.","type":"object"}}},"ProcessingError":{"type":"object","properties":{"type":{"description":"Type of the Error","type":"string","enum":["PROCESSING_ERROR"]},"code":{"description":"Internal error code.","type":"string","enum":["ENTITY_DOES_NOT_EXIST","ENTITY_ALREADY_EXISTS","POOR_BIOMETRIC_QUALITY","DUPLICATED_BIOMETRIC","BIOMETRIC_OUT_OF_SEQUENCE","BIOMETRIC_ERROR","INSUFFICIENT_TEMPLATE_COUNT","UNEXTRACTABLE_BIOMETRIC","PERSON_DOES_NOT_EXIST","PERSON_NOT_ACTIVE","PERSON_DOES_NOT_HAVE_BIOMETRIC","PENDING_EXCEPTIONS","ENROLL_TRANSACTION_DOES_NOT_EXIST","ENROLL_PERSON_NOT_FOUND","INVALID_TRANSACTION_STATE","EXCEPTION_DOES_NOT_EXIST","TREAT_EXCEPTION_TRANSACTION_DOES_NOT_EXIST","USER_NOT_AUTHORIZED_TO_TREAT_EXCEPTION","UL_IS_ALREADY_SOLVED","INVALID_PARAMETER_COMBINATION","CAN_NOT_DISABLE_ONLY_ENROLL_TRANSACTION","PERSON_DOES_NOT_OWN_TRANSACTION","TRANSACTION_IS_ALREADY_DISABLED","CAN_NOT_DISABLE_TRANSACTION_OF_UNSUPPORTED_TYPE","INVALID_EBTS_TYPE9_CONTENT","EXTERNAL_ID_DOES_NOT_EXIST","EXCEPTION_IS_ALREADY_TREATED","INVALID_TREATMENT_FOR_EXCEPTION","ENROLL_IS_ALREADY_ASSIGNED","ENROLL_IS_ALREADY_UNASSIGNED","ENROLL_IS_NOT_PENDING","ENROLL_IS_NOT_ASSIGNED","ENROLL_HAS_DIFFERENT_ASSIGNED_USER","NO_PGUID_FOUND_FOR_KEY","NO_SEARCHABLE_BIOMETRIC"]},"message":{"description":"Message detailing the nature of the Error","type":"string"},"meta":{"description":"Contains extra information about the API call.","type":"object"}}},"InternalError":{"type":"object","properties":{"type":{"description":"Type of the Error","type":"string","enum":["INTERNAL_ERROR"]},"code":{"description":"Internal error code.","type":"string","enum":["DRIVER_OFFLINE","CREDENTIAL_SERVER_CONNECTION_ERROR","CLIENT_NOT_INITIALIZE","TRUSTED_ENROLL_WITH_PENDING_STATUS","SUBJECT_NOT_SET","UNKNOWN"]},"message":{"description":"Message detailing the nature of the Error","type":"string"},"meta":{"description":"Contains extra information about the API call.","type":"object"}}}}}}
```

## rematch

> Triggers a new matching process (rematch) on transactions or persons whose data were updated, recalculating candidates and results.

```json
{"openapi":"3.0.1","info":{"title":"GBDS API","version":"5.1.16"},"servers":[{"url":"http://<ip>:8085/gbds/v2"}],"paths":{"/people/searches/rematch":{"put":{"tags":["searches"],"operationId":"rematch","summary":"rematch","parameters":[{"name":"tguid","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSearchesResponse"}}}}},"description":"Triggers a new matching process (rematch) on transactions or persons whose data were updated, recalculating candidates and results."}}},"components":{"schemas":{"ListSearchesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Search"}},"httpResponse":{"$ref":"#/components/schemas/HttpResponse"}}},"Search":{"type":"object","properties":{"status":{"description":"Status of the search.","type":"string","enum":["ENQUEUED","PREPARED","PROCESSING","MATCH","NOT_MATCH","FAILED","PENDING","PERSON_NOT_FOUND"]},"tguid":{"description":"Search transaction TGUID.","type":"string"},"candidates":{"description":"List of match candidates.","type":"array","items":{"$ref":"#/components/schemas/MatchBob"}},"progress":{"type":"number","format":"float"},"request":{"$ref":"#/components/schemas/SearchSpec"},"failReason":{"description":"Fail message on why search didn't complete.","type":"string"},"searchType":{"description":"Type of finger that was searched.","type":"string","enum":["SAME_FINGERS","ALL_FINGERS","CROSSED_WINDOW_TWEEZERS"]},"biometrics":{"description":"List of biometrics","type":"array","items":{"$ref":"#/components/schemas/Biometric"}},"apiID":{"description":"API ID","type":"string"},"gbdsVersion":{"description":"GBDS Version","type":"string"},"extractionElapsed":{"description":"Time to complete the extraction.","type":"integer","format":"int64"},"searchElapsed":{"description":"Time to complete the search.","type":"integer","format":"int64"},"postSearchElapsed":{"description":"Time to complete the post match.","type":"integer","format":"int64"},"ulsearch":{"description":"Unsolved latent search.","type":"boolean"},"latentSearch":{"description":"Latent search.","type":"boolean"},"score":{"description":"Score of the biometric comparison. Only returned if a single biometric was provided in the payload of the request that created the search.","type":"integer","format":"int32"},"bonafideScore":{"description":"Bonafide score of the liveness verification. Only returned if the `liveness` flag was set to `true` in the payload of the request that created the search. Ranges from 0 to 100 (0=attack, 100=genuine).","type":"integer","format":"int32"},"metadata":{"$ref":"#/components/schemas/SearchMetadata"}}},"MatchBob":{"type":"object","properties":{"matchedPersonPguid":{"description":"PGUID of the person the candidate matched against.","type":"string"},"matchedPersonTguid":{"description":"TGUID of the person the candidate matched against.\n\nReturned at this level only when Best of Biometrics (**BoB**) is **DISABLED**. Otherwise, omitted here and **one TGUID per biometric** is returned at the `biometricMatches` level (child).\n","type":"string"},"biometricMatches":{"description":"Information about the match.","type":"array","items":{"$ref":"#/components/schemas/BiometricMatchBob"}}}},"BiometricMatchBob":{"type":"object","properties":{"matchedPersonTguid":{"description":"TGUID of the person the candidate matched against.\n\nReturned at this level only when Best of Biometrics (**BoB**) is **ENABLED**. Otherwise, omitted here and only **one TGUID per candidate** is returned at the `candidates` level (parent).\n","type":"string","format":"uuid"},"score":{"description":"Score of the match.","type":"integer","format":"int32"},"queryIndex":{"description":"Index of the biometric data that was sent and caused a match.","type":"integer","format":"int32"},"referenceIndex":{"description":"Index of the biometric data, from the already enrolled person, which matched.","type":"integer","format":"int32"},"minutia":{"description":"Array of minutia matches. Returned only for latent searches.","type":"array","items":{"$ref":"#/components/schemas/Minutiae"}}}},"Minutiae":{"type":"object","properties":{"query":{"description":"Index of Minutiae, from the provided biometric data, which was involved in the match.","type":"integer","format":"int32"},"reference":{"description":"Index of Minutiae, from biometric data already in the database, which was involved in the match.","type":"integer","format":"int32"}}},"SearchSpec":{"type":"object","properties":{"searchType":{"description":"Type of finger to be searched.","type":"string","enum":["SAME_FINGERS","ALL_FINGERS","CROSSED_WINDOW_TWEEZERS"]},"biometric":{"description":"If only one biometric is provided, a match score will be returned. If more than one biometric is provided, a list of candidates can be retrieved using getSearchResult.","type":"array","items":{"$ref":"#/components/schemas/Biometric"}},"keys":{"type":"array","items":{"$ref":"#/components/schemas/Key"}},"pguids":{"description":"This field is a list of PGUIDs. If the list is empty or null, the search will be against the entire database. If it has only one PGUID, the search will be 1:1. It is possible to make 1:1 searches with more than one PGUID.","type":"array","items":{"type":"string"}},"labelFilters":{"description":"Used for 1:N operations. The filters will be compared with the labels field registered by the enroll method.","uniqueItems":true,"type":"array","items":{"type":"string"}},"isLatentSearch":{"description":"Flag indicating if the search is a Latent Search.","type":"boolean"},"isULSearch":{"description":"Flag indicating if the search is an UL Search.","type":"boolean"},"numberOfCandidates":{"description":"Number of candidates to be returned.","type":"integer","format":"int32"},"classificationThreshold":{"description":"Threshold for either classifying biometric data or marking it as UNKNOWN.","type":"integer","format":"int32"},"classifications":{"description":"Vector containing the classifications to be considered. Defaults to UNKNOWN.","uniqueItems":true,"type":"array","items":{"type":"string","enum":["PLAIN_ARCH","LEFT_LOOP","RIGHT_LOOP","WHORL","SCAR","UNKNOWN","AMPUTATION","OTHER"]}},"singularities":{"description":"Singularities to be considered. Defaults to NONE.","type":"string","enum":["NONE","NO_DELTA_ALL_CORES","ONE_DELTA_NO_CORES","ONE_DELTA_ALL_CORES"]},"latentSearchOptions":{"$ref":"#/components/schemas/LatentSearchOptions"},"searchOptions":{"$ref":"#/components/schemas/SearchOptions"},"user":{"type":"string"},"uguids":{"description":"Globally unique ID of the UL. Can be a list of uguids.","type":"array","items":{"type":"string"}},"liveness":{"description":"Flag to request liveness verification on query face image. If activated, a bonafide score will be returned.","type":"boolean"}}},"Biometric":{"type":"object","oneOf":[{"$ref":"#/components/schemas/CONSOLIDATED_TEMPLATE"},{"$ref":"#/components/schemas/TEMPLATE"},{"$ref":"#/components/schemas/ORIGINAL"}],"discriminator":{"propertyName":"source"}},"CONSOLIDATED_TEMPLATE":{"title":"CONSOLIDATED_TEMPLATE","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["CONSOLIDATED_TEMPLATE"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"BiometricProperties":{"type":"object","properties":{"width":{"description":"Width, in pixels, of the image. If 0, GBDS will try to extract this information from the image header.","type":"integer","format":"int32"},"height":{"description":"Height, in pixels, of the image. If 0, GBDS will try to extract this information from the image header.","type":"integer","format":"int32"},"resolution":{"description":"Image or template resolution.","type":"integer","format":"int32"},"ratio":{"description":"Proportion of the image.","type":"number","format":"double"},"matcherId":{"description":"ID of the Biometric Matcher to be used in verification and identification operations.","type":"integer","format":"int32"},"extractorId":{"description":"ID of the extractor to be used on the image.","type":"integer","format":"int32"}}},"TEMPLATE":{"title":"TEMPLATE","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["TEMPLATE"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"ORIGINAL":{"title":"ORIGINAL","type":"object","properties":{"source":{"description":"How the biometric data was obtained.","type":"string","enum":["ORIGINAL"]},"type":{"description":"Type of the biometric data.","type":"string","enum":["FINGERPRINT","PALMPRINT","FOOTPRINT","FACE","IRIS","VOICE","SIGNATURE","SEQUENCE_CONTROL","NEWBORN_PALMPRINT","OTHER"]},"format":{"description":"Format of the biometric data.","type":"string","enum":["RAW","WSQ","JPEG","JPEG2000","PNG","TIFF","GIF","BMP","PCM","WAV","PRIVATE","ISO","ANSI","UNKNOWN","EBTS_TYPE9"]},"properties":{"$ref":"#/components/schemas/BiometricProperties"},"index":{"description":"Identifies which biometric, of the specified type, is being sent.","type":"integer","format":"int32"},"content":{"description":"Base64 encoded biometric data.","type":"string"},"quality":{"description":"Given the quality of the extracted biometric template. The quality is unbounded and starts at 0.","type":"integer","format":"int32"}}},"Key":{"type":"object","properties":{"id":{"description":"Name of entity identifier.","type":"string"},"value":{"description":"Value of entity identifier.","type":"string"}}},"LatentSearchOptions":{"type":"object","properties":{"scoreThreshold":{"description":"Search score threshold.","type":"integer","format":"int32"},"rotationAngleThreshold":{"description":"Rotation angle threshold for searching.","type":"integer","format":"int32"}}},"SearchOptions":{"type":"object","properties":{"biometricType":{"description":"biometricType must contain its data and be one of the following values - FINGERPRINT, PALMPRINT, FACE, IRIS, NEWBORN_PALMPRINT, i.e., you must substitute the \"biometricType\" field name by one of the ENUM names.","type":"object","properties":{"scoreThreshold":{"description":"Search score threshold.","type":"integer","format":"int32"},"rotationAngleThreshold":{"description":"Rotation angle threshold for searching.","type":"integer","format":"int32"},"matcher":{"description":"Define which ginger preset will be used.","type":"string","enum":["DEFAULT","MOBILE"]}}}}},"SearchMetadata":{"description":"Additional information.","type":"object","additionalProperties":{"description":"A flexible key-value pair where the key is a string."}},"HttpResponse":{"type":"object","properties":{"httpCode":{"type":"integer","format":"int32"},"body":{"type":"string"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.griaule.com/apis/gbds-5/searches.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.