SPID Services

The SPID Services API is desgined for system integrators to access the SPID functionalities from whithin their own applications.

The SPID Services API is provided along with any SPID installation and can be also configured in the SPID Configuration File located at the following paths:

Windows Installation:

C:\Griaule\SPID\conf\GBSSpid2.properties

Linux Installation:

Further information about the SPID Configuration file can be found in the SPID Configuration Manual.

The default port for the SPID Services API is 19980 and can be changed by the port.number parameter in the configuration file. The default endpoint structure is localhost:8080/gbs-spid-services/api/.

The endpoint structure must be followed in any API call, appending the specific information for the desired call at the end of the default structure.

The SPID-Linux is only available for debian-based linux distributions. Contact the Griaule Support Team for further information.

API Calls

Login

This method is used for operator login in the system. It will perform a consult to obtain the operator status from the server.

If the operator is enrolled and has no exceptions linked to his profile, his biometrics will be retrieved for local verification.

When the server cannot be reached, the method will check whether the desired operator is eligible for offline login (the biometrics are already stored at the local database).

URL

/login/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: ID of the operator to be logged in

Response

status: status of the operator login attempt:

  • OPERATOR_FAILED: there was a problem with the operator enrollment at the server;

  • OPERATOR_NOT_FOUND: no operator with the provided ID was found;

  • OPERATOR_IN_PROGRESS: the operator is waiting for the server to process its enrollment after providing its biometrics;

  • OPERATOR_PENDING: the operator was added by the administrator, but did not provided its biometrics yet;

  • OPERATOR_OK: the operator was found and had its biometrics downloaded;

  • OPERATOR_OFFLINE_OK: there has been a problem in the server connection, but the operator was successfully logged in based on the local database information

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: ID of the operator.

Response Example

{
	"status": "OPERATOR_OK",
	"message": "Operator enroll ok",
	"id": "id1"
}

Login Status

This method is used for checking whether there is an active operator logged in the current session.

URL

/login/status

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the operator login:

  • LOGIN_NOT_ACTIVE: there is no active operator logged in the current session;

  • LOGIN_OK: there is an active operator logged in the current session;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: ID of the current operator, if logged in.

Response Example

{
	"status": "LOGIN_OK",
	"message": "Current session login status is LOGIN_OK",
	"id": "id1"
}

Logout

This method is used for disconnecting any active operator from the current session.

URL

/logout

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the operator logout attempt:

  • LOGIN_NOT_ACTIVE: there is no active operator logged in the current session;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

Response Example

{
	"status": "LOGIN_NOT_ACTIVE",
	"message": "Log out successful. There is no active operator"
}

Verify Operator

This method is used for biometrically verifying the active operator of the current session by collecting one of its biometrics and comparing against the biometrics obained at login.

URL

/verify/operator

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the operator verification:

  • LOGIN_NOT_ACTIVE: there is no active operator logged in the current session;

  • OPERATOR_VERIFIED: the biometric verification for the current operator is disabled, so it is successfully verified;

  • OPERATOR_VERIFYING: the verification capture scene was initialized;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: ID of the operator being verified.

Response Example

{
	"status": "OPERATOR_VERIFYING",
	"message": "The operator verify scene has been initialized",
	"id": "id1"
}

Verify Operator Status

This method is used for checking the status of the operator verification.

URL

/verify/status

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the operator verification:

  • LOGIN_NOT_ACTIVE: there is no active operator logged in the current session;

  • OPERATOR_VERIFIED: the biometric verification for the current operator is disabled, so it is successfully verified;

  • OPERATOR_NOT_VERIFIED: the operator was not verified, or there is no verification initialized for this session;

  • OPERATOR_VERIFYING: the verification capture scene was initialized;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: ID of the operator being verified.

Response Example

{
	"status": "OPERATOR_VERIFYING",
	"message": "The operator verify scene has been initialized",
	"id": "id1"
}

Operator Enroll

This method is used for operator enrollment. It invokes the capture scene for the desired operator and submit the captured biometrics to the server.

URL

/capture/operator-enroll/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: ID of the operator to be enrolled

Response

status: status of the operator enrollment:

  • LOGIN_OK: there is an already active operator logged in the current session (an operator can not be enrolled if there is another operator logged in);

  • OPERATOR_NOT_PENDING: the operator status in the server is not eligible for enrollment;

  • OPERATOR_CAPTURING: the operator capture scene was initialized;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: ID of the operator being enrolled.

Response Example

{
	"status": "OPERATOR_CAPTURING",
	"message": "Operator capture was initialized",
	"id": "id1"
}

Enroll

This method is used for capturing a client’s biometrics for enrollment.

URL

/capture/enroll/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: ID of the client to be enrolled

Response

status: status of the client enrollment capture:

  • LOGIN_NOT_ACTIVE: there is no operator logged in the current session (there must be a valid operator active to perform a client capture).

  • CLIENT_CAPTURING: the client capture scene was initialized;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: ID of the client being enrolled.

Response Example

{
	"status": "CLIENT_CAPTURING",
	"message": "Client capture initialized",
	"id": "id1"
}

Verify

This method is used to verify the biometrics of a client.

URL

/capture/verify/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: ID of the client to be verified

Response

status: status of the client verification capture:

  • LOGIN_NOT_ACTIVE: there is no operator logged in the current session (there must be a valid operator active to perform a client capture).

  • PERSON_NOT_FOUND: the provided ID does not exist;

  • CLIENT_CAPTURING: the client capture scene was initialized;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: ID of the client being verified.

Response Example

{
	"status": "CLIENT_CAPTURING",
	"message": "Client capture initialized",
	"id": "id1"
}

Remote Enroll

This method is used to perform remote capture and enrollment of the biometrics of a client.

URL

/capture/remoteEnroll/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: ID of the client to be verified

Response

status: status of the client verification capture:

  • LOGIN_NOT_ACTIVE: there is no operator logged in the current session (there must be a valid operator active to perform a client capture).

  • DONE: the capture was correctly started remotely;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: returns the tguid and dynamicLink of the remote enroll transaction. id: ID of the client being captured.

Response Example

{
	"status": "Done",
	"message": "Remote enroll initialized tguid:, dynamicLink",
	"id": "id1"
}

Remote Enroll Result by TGUID

This method is used for querying the status of a given remote enroll.

URL

/capture/remoteEnroll/result/{tguid}

HTTP Method

GET

Content Type

application/json

Parameters

tguid: TGUID of the desired transaction

Response

status: status of the given transaction at the server:

  • LOGIN_NOT_ACTIVE: there is no operator logged in;

  • DONE: the remote enroll was started successfully. Outcome described in the status message;

  • ERROR: an error has occurred, detailed description given in the status message;

message: for valid enroll transactions, the message contains the enroll status. Possible enroll status are:

  • ENROLL_CACHE_OK

  • ENROLL_IN_PROGRESS

  • ENROLL_OK

  • ENROLL_FAILED

  • ERROR

  • ENROLL_EXCEPTION

  • REMOTE_CAPTURE_PENDING

  • REMOTE_CAPTURE_STORED

  • REMOTE_CAPTURE_ACCEPTED

  • REMOTE_CAPTURE_REFUSED

  • REMOTE_CAPTURE_AVAILABLE

  • ENROLL_REJECTED

Response Examples

{
	"status": "Done",
	"message": "Remote enroll with status ENROLL_IN_PROGRESS"
}
{
	"status": "Error",
	"message": "Get enroll result returned null for tguid: TGUID"
}
{
	"status": "Login not active",
	"message": "There is no valid operator logged in"
}
{
	"status": "Enroll Rejected",
	"message": "It wasn't possible to finish operation, because the client enroll belongs to another PSBIO."
}

Remote Verify

This method is used to perform remote capture and verification of the biometrics of a client.

URL

/capture/remoteVerify/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: ID of the client to be verified

Response

status: status of the client verification capture:

  • LOGIN_NOT_ACTIVE: there is no operator logged in the current session (there must be a valid operator active to perform a client capture).

  • PERSON_NOT_FOUND: the provided ID does not exist;

  • DONE: the capture was correctly started remotely;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the tguid and dynamic link of the remote verify, on success. id: ID of the client being verified.

Response Example

{
	"status": "Done",
	"message": "Remote verify initialized tguid:, dynamicLink",
	"id": "id1"
}

Remote Verify Result by ID

This method is used for querying the status of a given remote verify.

URL

/capture/remoteVerify/result/{tguid}

HTTP Method

GET

Content Type

application/json

Parameters

tguid: TGUID of the desired transaction

Response

status: status of the given transaction at the server:

  • LOGIN_NOT_ACTIVE: there is no operator logged in;

  • DONE: the remote verify was started successfully. Outcome described in the status message;

  • ERROR: an error has occurred, detailed description given in the status message;

message: the message containing more information about any ERROR, or the description of the verify status in the absence of errors. The verify status can be:

  • SEARCH_MATCH

  • SEARCH_NOT_MATCH

  • SEARCH_IN_PROGRESS

  • SEARCH_FAILED

  • REMOTE_CAPTURE_PENDING

  • REMOTE_CAPTURE_STORED

  • REMOTE_CAPTURE_ACCEPTED

  • REMOTE_CAPTURE_REFUSED

  • REMOTE_CAPTURE_AVAILABLE

Response Example

{
	"status": "Done",
	"message": "Remote verify with status SEARCH_MATCH"
}

Remote Approval by TGUID

This method is used to open the remote approval window. Used for remote enroll and remote verify

URL

/gbs-spid-services/api/capture/remoteApproval/{tguid}

HTTP Method

GET

Content Type

application/json

Parameters

tguid: TGUID returned by the remote capture

Response

status: status of the call, can be one of the following values:

  • LOGIN_NOT_ACTIVE: there is no operator logged in, must be a valid operator active to make the client capture.

  • DONE: the remote approval was started correctly.

  • ERROR: an error has occurred, detailed description given in the status message;

message: eturns message for remote approval

Response Examples

{
	"status": "Done",
	"message": "Remote approval initialized"
}
{
	"status": "Error",
	"message": "..."
}
{
	"status": "Login not active",
	"message": "There is no valid operator logged in"
}

Operator Capture

This method is utilized for capturing the biometrics of the operator and authenticating him. It will initialize a capture scene that can also receive comments from the operator and includes the agreement for use of his biometrics.

URL

capture/operator-capture

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the operator authentication:

  • LOGIN_NOT_ACTIVE: there is no active operator logged in the current session;

  • CLIENT_CAPTURE_NOT_DONE: the client capture hasn’t been finalized yet, so the operator can not authenticate itself;

  • OPERATOR_CAPTURE_DONE: the biometric authentication for the current operator is disabled at the server, so it is successfully authenticated;

  • OPERATOR_CAPTURING: the operator capture scene was initialized;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: ID of the client being captured.

Response Example

{
	"status": "CLIENT_CAPTURE_NOT_DONE",
	"message": "The client capture hasn't been completed",
	"id": "id1"
}

Stop Capture

This method is used to stop and close all capture scenes initialized.

URL

/capture/stop

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the capture scene stop attempt:

  • OK: all the capture scenes were successfully closed;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

Response Example

{
	"status": "OK",
	"message": "All active scenes were closed"
}

Capture Status

This method is used for checking the status of the current capture session.

URL

/capture/status

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the current capture session:

  • NONE: there is no capture session initialized;

  • CLIENT_CAPTURING: the client capture scene was initialized and is waiting for the operator to finish the client’s capture;

  • CLIENT_CAPTURE_DONE: the client capture has been completed;

  • FINGERPRINT_LOW_QUALITY: The client capture has been completed, but the fingerprint was not able to be captured because of the low quality.

  • OPERATOR_CAPTURE_DONE: the operator has captured it’s biometrics and has been authenticated;

  • OPERATOR_CAPTURING: the operator capture scene was initialized and is waiting for the operator to authenticate.

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

Response Example

{
	"status": "CLIENT_CAPTURING",
	"message": "The client capture has been initialized"
}

Capture Send

This parameter is used for enqueuing an operation to be sent to the server.

URL

/capture/send

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the enqueuing attempt:

  • CAPTURE_ENQUEUED: the capture was enqueued to be sent to the server;

  • CLIENT_CAPTURING: the client capture scene is waiting to be finished;

  • OPERATOR_CAPTURING: the operator capture scene is waiting to be finished;

  • VERIFIED: In case of send verify, return this status if verify is sent correctly to SPID Server

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: local ID of the operation.

Response Example

{
	"status": "CAPTURE_ENQUEUED",
	"message": "The message has been enqueued to be sent",
	"id": "97"
}

Capture Result by ID

This method is used for querying the result of a given capture.

URL

/capture/result/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: local ID or TGUID of the desired transaction

Response

status: status of the given transaction at the server:

  • NOT_SENT: a problem has happened while trying to send the capture to the server;

  • ENROLL_OK: the enrollment transaction was successfully finalized at the server;

  • ENROLL_CACHE_OK: the enrollment transaction was successfully processed locally and is awaiting responses from remote servers;

  • ENROLL_CONTINGENCY_OK: the enrollment transaction was successfully processed locally while one or more remote servers couldn’t be reached and is awaiting responses;

  • ENROLL_SENT: the server received the enrollment transaction and is processing it; This is a temporary status.

  • ENROLL_FAILED: the enrollment transaction failed at the server;

  • ENROLL_ANOMALY: the enrollment transaction has caused an exception (a match occured with a previously enrolled set of biometrics);

  • ENROLL_TIMEOUT: the server connection timed out while sending the enrollment transaction;

  • UPDATE_OK: the update transaction was successfully finalized at the server;

  • UPDATE_CACHE_OK: the update transaction was successfully processed locally and is awaiting responses from remote servers;

  • UPDATE_CONTINGENCY_OK: the update transaction was successfully processed locally while one or more remote servers couldn’t be reached and is awaiting responses;

  • UPDATE_SENT: the server received the update transaction and is processing it; This is a temporary status.

  • UPDATE_FAILED: the update transaction failed at the server;

  • UPDATE_ANOMALY: the update transaction has caused an exception (no match occured with the previously enrolled set of biometrics);

  • UPDATE_TIMEOUT: the server connection timed out while sending the update transaction;

  • CORRUPTED: the transaction data couldn’t be read from the local database;

  • SEARCH_ENQUEUED: the “verify” transaction in the server is in progress. This is a temporary status;

  • SEARCH_MATCH: the “verify” transaction returned a match with the previously enrolled biometrics;

  • SEARCH_NOT_MATCH: the “verify” transaction returned a no match with the previously enrolled biometrics;

  • SEARCH_FAILED: the “verify” transaction failed at the server;

  • OPERATOR_NOT_AUTHENTICATED: the server couldn’t successfully authenticate the operator;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

If the return is an error, the following fields will be added:

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

If the return is not an error, the following fields will be added:

id: local ID or TGUID of the operation. doc: person ID of the client. docOperator: operator ID. timestamp: time the transaction was registered at the local database (epoch time in miliseconds). lastUpdate: timestamp of the transaction’s last update at the server. tguid: transaction ID at the server.

Response Example

{
	"id": 97,
	"doc": "id1",
	"docOperator": "id2",
	"timestamp": 1490114943468,
	"lastUpdate": 1490114943969,
	"status": "UPDATE_SENT",
	"tguid": "37BBE44B-924B-406F-824C-73FDC535416F"
}

Capture Result by Date

This method is used for consulting the result of a set of transactions within a given time interval and ordered by ID.

URL

/capture/result/list/{startDate}/{endDate}/{offset}

HTTP Method

GET

Content Type

application/json

Parameters

startDate: initial date to be consulted (epoch time in miliseconds) endDate: final date to be consulted (epoch time in miliseconds) offset: the list is limited to 100 results per request and this parameter defines the offset from the list head to be considered

Response

For each transaction in the returned list, the following information will be provided:

status: status of the given transaction at the server:

  • NOT_SENT: a problem has happened while trying to send the capture to the server;

  • ENROLL_OK: the enrollment transaction was successfully finalized at the server;

  • ENROLL_CACHE_OK: the enrollment transaction was successfully processed locally and is awaiting responses from remote servers;

  • ENROLL_CONTINGENCY_OK: the enrollment transaction was successfully processed locally while one or more remote servers couldn’t be reached and is awaiting responses;

  • ENROLL_SENT: the server received the enrollment transaction and is processing it;

  • ENROLL_FAILED: the enrollment transaction failed at the server;

  • ENROLL_ANOMALY: the enrollment transaction has caused an exception (a match occured with a previously enrolled set of biometrics);

  • ENROLL_TIMEOUT: the server connection timed out while sending the enrollment transaction;

  • UPDATE_OK: the update transaction was successfully finalized at the server;

  • UPDATE_CACHE_OK: the update transaction was successfully processed locally and is awaiting responses from remote servers;

  • UPDATE_CONTINGENCY_OK: the update transaction was successfully processed locally while one or more remote servers couldn’t be reached and is awaiting responses;

  • UPDATE_SENT: the server received the update transaction and is processing it;

  • UPDATE_FAILED: the update transaction failed at the server;

  • UPDATE_ANOMALY: the update transaction has caused an exception (no match occured with the previously enrolled set of biometrics);

  • UPDATE_TIMEOUT: the server connection timed out while sending the update transaction;

  • CORRUPTED: the transaction data couldn’t be read from the local database;

  • SEARCH_MATCH: the “verify” transaction returned a match with the previously enrolled biometrics;

  • SEARCH_NOT_MATCH: the “verify” transaction returned a no match with the previously enrolled biometrics;

  • SEARCH_FAILED: the “verify” transaction failed at the server;

  • OPERATOR_NOT_AUTHENTICATED: the server couldn’t successfully authenticate the operator;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

If the return is an error, the following fields will be added:

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

If the return is not an error, the following fields will be added:

id: local ID or TGUID of the operation. doc: person ID of the client. docOperator: operator ID. timestamp: time the transaction was registered at the local database (epoch time in miliseconds). lastUpdate: timestamp of the transaction’s last update at the server. tguid: transaction ID at the server.

Response Example

[
	{
		"Id": 1,
		"doc": "id1",
		"docOperator": "id2",
		"timestamp": 1489752222590,
		"lastUpdate": 1489752228016,
		"status": "ENROLL_OK",
		"tguid": "2272DB15-AC76-4324-98C5-11EA1386F0CE"
	},
	{
		"Id": 2,
		"doc": "id1",
		"docOperator": "id2",
		"timestamp": 1489752274455,
		"lastUpdate": 1489752279908,
		"status": "UPDATE_OK",
		"tguid": "1E823F30-1E67-4254-B347-106D0DE74946"
	},
	{
		"Id": 33,
		"doc": "id1",
		"docOperator": "id2",
		"timestamp": 1489866115100,
		"lastUpdate": 1489866121427,
		"status": "UPDATE_SENT",
		"tguid": "549AEC06-7621-4972-BEDF-BAD24A20EEAC"
	}
]

Capture Result List

This method is used for querying the result of a set of transactions ordered by ID.

URL

/capture/result/list/{offset}

HTTP Method

GET

Content Type

application/json

Parameters

offset: the list is limited to 100 results per request and this parameter defines the offset from the list head to be considered

Response

For each transaction in the returned list, the following information will be provided:

status: status of the given transaction at the server:

  • NOT_SENT: a problem has happened while trying to send the capture to the server;

  • ENROLL_OK: the enrollment transaction was successfully finalized at the server;

  • ENROLL_CACHE_OK: the enrollment transaction was successfully processed locally and is awaiting responses from remote servers;

  • ENROLL_CONTINGENCY_OK: the enrollment transaction was successfully processed locally while one or more remote servers couldn’t be reached and is awaiting responses;

  • ENROLL_SENT: the server received the enrollment transaction and is processing it;

  • ENROLL_FAILED: the enrollment transaction failed at the server;

  • ENROLL_ANOMALY: the enrollment transaction has caused an exception (a match occured with a previously enrolled set of biometrics);

  • ENROLL_TIMEOUT: the server connection timed out while sending the enrollment transaction;

  • UPDATE_OK: the update transaction was successfully finalized at the server;

  • UPDATE_CACHE_OK: the update transaction was successfully processed locally and is awaiting responses from remote servers;

  • UPDATE_CONTINGENCY_OK: the update transaction was successfully processed locally while one or more remote servers couldn’t be reached and is awaiting responses;

  • UPDATE_SENT: the server received the update transaction and is processing it;

  • UPDATE_FAILED: the update transaction failed at the server;

  • UPDATE_ANOMALY: the update transaction has caused an exception (no match occured with the previously enrolled set of biometrics);

  • UPDATE_TIMEOUT: the server connection timed out while sending the update transaction;

  • CORRUPTED: the transaction data couldn’t be read from the local database;

  • SEARCH_MATCH: the “verify” transaction returned a match with the previously enrolled biometrics;

  • SEARCH_NOT_MATCH: the “verify” transaction returned a no match with the previously enrolled biometrics;

  • SEARCH_FAILED: the “verify” transaction failed at the server;

  • OPERATOR_NOT_AUTHENTICATED: the server couldn’t successfully authenticate the operator;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

If the return is an error, the following fields will be added:

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

If the return is not an error, the following fields will be added:

id: local ID or TGUID of the operation. doc: person ID of the client. docOperator: operator ID. timestamp: time the transaction was registered at the local database (epoch time in miliseconds). lastUpdate: timestamp of the transaction’s last update at the server. tguid: transaction ID at the server.

Response Example

[
	{
		"Id": 1,
		"doc": "id1",
		"docOperator": "id2",
		"timestamp": 1489752222590,
		"lastUpdate": 1489752228016,
		"status": "ENROLL_OK",
		"tguid": "2272DB15-AC76-4324-98C5-11EA1386F0CE"
	},
	{
		"Id": 2,
		"doc": "id1",
		"docOperator": "id2",
		"timestamp": 1489752274455,
		"lastUpdate": 1489752279908,
		"status": "UPDATE_OK",
		"tguid": "1E823F30-1E67-4254-B347-106D0DE74946"
	},
	{
		"Id": 33,
		"doc": "id1",
		"docOperator": "id2",
		"timestamp": 1489866115100,
		"lastUpdate": 1489866121427,
		"status": "UPDATE_SENT",
		"tguid": "549AEC06-7621-4972-BEDF-BAD24A20EEAC"
	}
]

Capture Update

This method is used for updating the status of a specific transaction.

URL

/capture/result/list/update/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: local ID of the desired transaction

Response

status: status of the given transaction at the server:

  • NOT_SENT: a problem has happened while trying to send the capture to the server;

  • ENROLL_OK: the enrollment transaction was successfully finalized at the server;

  • ENROLL_CACHE_OK: the enrollment transaction was successfully processed locally and is awaiting responses from remote servers;

  • ENROLL_CONTINGENCY_OK: the enrollment transaction was successfully processed locally while one or more remote servers couldn’t be reached and is awaiting responses;

  • ENROLL_SENT: the server received the enrollment transaction and is processing it;

  • ENROLL_FAILED: the enrollment transaction failed at the server;

  • ENROLL_ANOMALY: the enrollment transaction has caused an exception (a match occured with a previously enrolled set of biometrics);

  • ENROLL_TIMEOUT: the server connection timed out while sending the enrollment transaction;

  • UPDATE_OK: the update transaction was successfully finalized at the server;

  • UPDATE_CACHE_OK: the update transaction was successfully processed locally and is awaiting responses from remote servers;

  • UPDATE_CONTINGENCY_OK: the update transaction was successfully processed locally while one or more remote servers couldn’t be reached and is awaiting responses;

  • UPDATE_SENT: the server received the update transaction and is processing it;

  • UPDATE_FAILED: the update transaction failed at the server;

  • UPDATE_ANOMALY: the update transaction has caused an exception (no match occured with the previously enrolled set of biometrics);

  • UPDATE_TIMEOUT: the server connection timed out while sending the update transaction;

  • CORRUPTED: the transaction data couldn’t be read from the local database;

  • SEARCH_MATCH: the “verify” transaction returned a match with the previously enrolled biometrics;

  • SEARCH_NOT_MATCH: the “verify” transaction returned a no match with the previously enrolled biometrics;

  • SEARCH_FAILED: the “verify” transaction failed at the server;

  • OPERATOR_NOT_AUTHENTICATED: the server couldn’t successfully authenticate the operator;

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

If the return is an error, the following fields will be added:

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

If the return is not an error, the following fields will be added:

id: local ID or TGUID of the operation. doc: person ID of the client. docOperator: operator ID. timestamp: time the transaction was registered at the local database (epoch time in miliseconds). lastUpdate: timestamp of the transaction’s last update at the server. tguid: transaction ID at the server.

Response Example

{
	"id": 97,
	"doc": "11068101806",
	"docOperator": "41799362833",
	"timestamp": 1490114943468,
	"lastUpdate": 1490114943969,
	"status": "UPDATE_ANOMALY",
	"tguid": "37BBE44B-924B-406F-824C-73FDC535416F"
}

Capture Resend All

This method is used for resending any transaction with a status that indicates problems, such as ENROLL_TIMEOUT, UPDATE_TIMEOUT, NOT_SENT and, if enabled in the configuration file, ERROR and OPERATOR_NOT_AUTHENTICATED.

URL

/capture/resendAll

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the resending attempt:

  • OK: the resending process has started

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors. id: the local ID of the operation.

Response Example

{
	"status": "OK",
	"message": "The captures that had problem are being resent"
}

Capture Report

This method is used to retrieve the transaction report, which will be returned as a PDF file encoded as base64.

URL

/capture/report/{id}

HTTP Method

GET

Content Type

application/json

Parameters

id: local ID of desired transaction

Response

If the report is successful retrieved:

report: the base64 representation of the report document (PDF):

If there is an error while retrieving the report:

status: of the attempt to retrieve de report:

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

Response Example

{
	"report": "JVBERi0xLjQKJeLjz9MKMiAwIG9iago8PC9Db2xvclNwYWNlL0RldmljZVJHQi9TdWJ0eXBlL0ltYWdlL0hlaWdodCA1NS9GaWx0ZXIvRmxhdGVEZWNvZGUvVHlwZS9YT2JqZWN0L1dpZHRoIDQ5L0xlbmd0aCAzMS9CaXRzUGVyQ29tcG9uZW50IDg+PnN0cmVhbQp4nO3BMQEAAADCoP6pZwo/oAAAAAAAAACAiwGefnc9CmVuZHN0cmVhbQplbmRvYmoKNCAwIG9iago8PC9Db2xvclNwYWNlL0RldmljZVJHQi9TdWJ0eXBlL0ltYWdlL0hlaWdodCA1NS9GaWx0ZXIvRmxhdGVEZWNvZGUvVHlwZS9YT2JqZWN0L1dpZHRoIDQ5L0xlbmd0aCAzMS9CaXRzUGVyQ29tcG9uZW50IDg+PnN0cmVhbQp4nO3BMQEAAADCoP6pZwo/oAAAAAAAACAiwGefnc9CmVuZHN0cmVhbQplbmRvYmoKNSAwIG9iago8PC9Db2xvclNwYWNlL0RldmljZVJHQi9TdWJ0eXBlL0ltYWdlL0hlaWdodCAyNTAvRmlsdGVyL0ZsYXRlRGVjb2RlL1R5cGUvWE9iamVjdC9XaWR0aCAxODcvTGVuZ3RoIDc1OTA1L0JpdHNQZXJDb21wb25lbnQgOD4+c3RyZWFtCnic5L3nV1vJtu49xv1y7+m2yRlEkgAhiZwzJhkbbJyNbcCAyVFCCeWAckJCEiLb7pxzzsE5x7Y77H3uOe8/8s5aJRayhGnc3TuccTWeXqOQhEyzfjzzmVW1JIPJaCCkNxqwjAE3vV6vVqtlxE2hUBgMBqfTOb/gwXLNu92eeRjA0V9up788LlKueScWHjvdc+Q9MP5jmnM5AuR0OOfscw44euWY3Y7sc17Z7FY/zTpsXs1a/WSzWbCsVrNXMJ61mK2mJ2Q2m0wm+NXKZOKJyZHRsYHxyRF/TQzDQ5Ps0SnuBIjHZ/MFHJBwmjst4onEfKxpsRBLLB..."
}

Stop

This method is used for stopping the running SPID instance.

URL

/stop

HTTP Method

GET

Content Type

application/json

Parameters

none

Response

status: status of the stopping attempt:

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

Redirect to Verify

This endpoint redirects a transaction to verify in SPID Server.

URL

/redirect_to_verify/{tguid}

HTTP Method

GET

Content Type

application/json

Parameters

tguid: Unique ID of the desired transaction.

Response

status: status of the redirection attempt:

  • ERROR: there was an error while processing this operation (further information will be provided in the message field).

message: the message containing more information about any ERROR, or the description of the status in the absence of errors.

Development Guide

The recommended integration flow is shown below: