| Table of Contents |
|---|
RegisterVerificationWithDocument
This method is used to register a verification attempt using an image of a document as a source of personal details. This method is intended to be used the first time a verification attempt is made with an identity document for an individual in a verification session.
The caller passes an image of the front, and optionally the back, of an identity document (the requirements depend on the type of identity document). The images are scanned for personal details, and if they are successfully read, then a verification step is attempted. If the verification step passes, then the verification attempt is registered in greenID. Otherwise, if the card is readable, but the details did not pass the verification step, then the details read from the card are returned to the caller. If the card was not readable, then the image is saved, and a reference is returned to the caller.
For an example of the expected sequence of calls, please refer to the examples for registering with a document (above).
Input Parameters:
Name | Type | Required | Restrictions |
|---|---|---|---|
accountId | String | Yes | GreenID issues each customer with an accountId, which is a unique identifier by which greenID knows the caller. This accountId must be supplied with every call to any method in this API. |
password | String | Yes | Each customer is issued a password that must be supplied with every call to any web method in this API. |
verificationId | String | May be null | Each verification attempt for a person must have a verificationId, which is a unique identifier that greenID and the caller use to refer to a verification attempt for an individual person. If the caller supplies the verificationId, then greenID stores and uses that identifier; otherwise, greenID will generate a unique verificationId. The verificationId is returned to the caller. |
ruleId | String | Yes | Callers have one or more rules configured for their greenID account. This string must identify one of those rules. Contact greenID for the names of the rules configured for your account. If only one rule is configured, then the string “default” will automatically select that rule. |
String | May be null | Must be a valid email address. | |
imageCode | String | May be null | A reference to an image that has previously been OCRed, and the results exists in greenID. This parameter must be present if thebase64DocumentFront is not supplied. |
documentType | String | Yes | The type of document being validated. Please refer to the list of supported Identity Card Types.
|
base64DocumentFront | String | May be null | If present, it must be a base64 encoded string representing the image of the front of the identity document. This field must be supplied if theimageCode parameter is not supplied. |
base64DocumentBack | String | May be null | If present, t must be a base64 encoded string representing the image of the back of the identity document. This field must be supplied for certain identity document types. |
deviceIDData | String | May be null | This field is only needed for customers using the ReD Shield device verification service. Customers not using this service can leave this field blank. If you are using the ReD Shield device verification service, then please contact Edentiti for technical details regarding this field. |
generateVerificationToken | boolean | Yes | This parameter indicates whether a verification token is required. If "true", the registerVerification method will produce a verification token just asgetVerificationToken would. For information about verification tokens, please refer to the getVerificationToken method. If a verification token is not required, this parameter should be set to “false”. |
| extraData | List<NameValuePair> | No | This parameter is used to send additional request information to greenID. |
Return Value:
This method returns a RegistrationResultV2 object. Different members of the object will be populated depending on the outcome of the OCR and verification steps.
If the outcome of the web service call is UNREADABLE_DOCUMENT, then the following members will be populated:
- documentType - this will have the same value that was passed in the documentType input parameter.
- imageCode - this will have a reference that can be used to refer to the images that were provided as input in subsequent calls. If the inputimageCode parameter was set, then the same value will be returned.
- userData - this member will be present, but it won't contain any personal information, as the identity card could not be read. It will contain the sameimageCode and documentType as mentioned above.
If the outcome of the web service call is UNMATCHED_DOCUMENT, then the following members will be populated:
- documentType - this will have the same value that was passed in the documentType input parameter.
- imageCode - this will have a reference that can be used to refer to the images that were provided as input in subsequent calls. If the input imageCode parameter was set, then the same value will be returned.
- userData - this member will contain the personal details that were extracted from the identity card. For full details, please refer to the UserDataV2 type.
- extraData - this member will contain any extraData values that were supplied as input, as well as document specific information that was extracted from the identity card. For a list of extraData items, please refer to the list of supported Identity Card Types.
If the outcome of the web service call is SUCCESSFUL_REGISTRATION, then the following members will be populated.
- documentType - this will have the same value that was passed in the documentType input parameter.
- imageCode - this will have a reference that can be used to refer to the images that were provided as input in subsequent calls. If the input imageCode parameter was set, then the same value will be returned.
- currentStatus - this will contain all of the information about the registration that was made. For full details, please refer to the CurrentStatusV2 type.
- extraData - this member will contain any extraData values that were supplied as input, as well as document specific information that was extracted from the identity card. For a list of extraData items, please refer to the list of supported Identity Card Types.
Exceptions:
- InvalidCustomerIdException – the accountId input parameter was missing or not recognised.
- InvalidRuleIdException – the ruleId input parameter was missing or not recognised.
- InvalidCertificateException – if certificates are used to connect, then this exception may be thrown if an invalid certificate is used.
- InvalidPasswordException – the password input parameter was missing or incorrect.
- InvalidFieldException – one of the required fields was missing, or the format of a field was not valid. For example, this may be thrown if an email address is not valid.
- InvalidSourceIPAddressException - if IP address restriction is enabled and the IP address of the requesting client is not an allowed IP address, then this exception will be thrown.
- VerificationFaultException - there was an error while attempting to contact the data source.
- SystemException - there was an internal error in greenID while processing the request.
RegisterVerificationWithDocumentAndDetails
This method is used to register a verification attempt once a call to registerVerificationWithDocument has returned either UNREADABLE_DOCUMENT orUNMATCHED_DOCUMENT.
The caller passes a reference to the image(s) previously passed, the imageCode, as well as the personal details which have been collected or corrected manually by the person attempting verification. The personal details provided are used for the verification step rather than the details extracted from the identity card (if they exist). Just like the registerVerificationWithDocument method, if the verification step passes, then a verification attempt is registered in greenID. The caller can optionally force a verification attempt to be registered using the forceRegistration input parameter, even if the verification step fails.
For an example of the expected sequence of calls, please refer to the examples for registering with a document (above).
Input Parameters:
Name | Type | Required | Restrictions |
|---|---|---|---|
accountId | String | Yes | GreenID issues each customer with an accountId, which is a unique identifier by which greenID knows the caller. This accountId must be supplied with every call to any method in this API. |
password | String | Yes | Each customer is issued a password that must be supplied with every call to any web method in this API. |
verificationId | String | May be null | Each verification attempt for a person must have a verificationId, which is a unique identifier that greenID and the caller use to refer to a verification attempt for an individual person. If the caller supplies the verificationId, then greenID stores and uses that identifier; otherwise, greenID will generate a unique verificationId. The verificationId is returned to the caller. |
ruleId | String | Yes | Callers have one or more rules configured for their greenID account. This string must identify one of those rules. Contact greenID for the names of the rules configured for your account. If only one rule is configured, then the string “default” will automatically select that rule. |
| name | The person's name. | ||
String | May be null | Must be a valid email address. | |
| currentResidentialAddress | AusAddress | Yes | The person's current residential address. |
| previousResidentialAddress | AusAddress | May be null | The person's previous residential address. |
| dob | DateOfBirth | Yes | The person's date of birth. |
| homePhone | String | May be null | If present, must be 10 digits only. |
| workPhone | String | May be null | If present, must be 10 digits only. |
| mobilePhone | String | May be null | If present, must be 10 digits only. |
imageCode | String | May be null | A reference to an image that has previously been OCRed, and the results exists in greenID. This parameter must be present if the base64DocumentFront is not supplied. |
base64DocumentFront | String | May be null | If present, it must be a base64 encoded string representing the image of the front of the identity document. This field must be supplied if the imageCode parameter is not supplied. |
base64DocumentBack | String | May be null | If present, t must be a base64 encoded string representing the image of the back of the identity document. This field must be supplied for certain identity document types. |
| documentType | String | Yes | The type of document being validated. Please refer to the list of supported Identity Card Types. |
deviceIDData | String | May be null | This field is only needed for customers using the ReD Shield device verification service. Customers not using this service can leave this field blank. If you are using the ReD Shield device verification service, then please contact Edentiti for technical details regarding this field. |
generateVerificationToken | boolean | Yes | This parameter indicates whether a verification token is required. If "true", this method will produce a verification token just as getVerificationTokenwould. For information about verification tokens, please refer to the getVerificationToken method. If a verification token is not required, this parameter should be set to “false”. |
| forceRegistration | boolean | Yes | If the document is readable, but verification step fails, then this flag will govern whether a verification attempt should be registered in greenID. Using this flag, a caller can allow a person multiple attempts to try and pass the verification step, but once the attempts are exhausted, the caller can set this flag to "true" to force a verification attempt to be registered, and then move on to other interactive data sources. If this flag is false and the verification step fails, then no verification attempt is registered. If the verification step succeeds, then a verification attempt is registered regardless of the value of this flag. If the document is not readable, then this flag cannot force a registration to be made. |
| extraData | List<NameValuePair> | No | This parameter is used to send additional request information to greenID. |
Return Value:
This method will return a RegistrationResultV2 object. Different members of the object will be populated depending on the outcome of the OCR and verification steps.
If the outcome of the web service call is UNREADABLE_DOCUMENT, then the following members will be populated. Note that the value of the forceRegistration flag will not force a registration to occur if the document is unreadable.
- documentType - this will have the same value that was passed in the documentType input parameter.
- imageCode - this will have a reference that can be used to refer to the images that were provided as input in subsequent calls. If the input imageCode parameter was set, then the same value will be returned.
- userData - this member will be present, but it won't contain any personal information, as the identity card could not be read. It will contain the same imageCode and documentType as mentioned above.
- documentType - this will have the same value that was passed in the documentType input parameter.
- imageCode - this will have a reference that can be used to refer to the images that were provided as input in subsequent calls. If the input imageCode parameter was set, then the same value will be returned.
- userData - this member will contain the personal details that were extracted from the identity card. For full details, please refer to the UserDataV2 type.
- extraData - this member will contain any extraData values that were supplied as input, as well as document specific information that was extracted from the identity card. For a list of extraData items, please refer to the list of supported Identity Card Types.
- documentType - this will have the same value that was passed in the documentType input parameter.
- imageCode - this will have a reference that can be used to refer to the images that were provided as input in subsequent calls. If the input imageCode parameter was set, then the same value will be returned.
- currentStatus - this will contain all of the information about the registration that was made. For full details, please refer to the CurrentStatusV2 type.
- extraData - this member will contain any extraData values that were supplied as input, as well as document specific information that was extracted from the identity card. For a list of extraData items, please refer to the list of supported Identity Card Types.
Exceptions:
- InvalidCustomerIdException – the accountId input parameter was missing or not recognised.
- InvalidRuleIdException – the ruleId input parameter was missing or not recognised.
- InvalidCertificateException – if certificates are used to connect, then this exception may be thrown if an invalid certificate is used.
- InvalidPasswordException – the password input parameter was missing or incorrect.
- InvalidFieldException – one of the required fields was missing, or the format of a field was not valid. For example, this may be thrown if an email address is not valid.
- InvalidSourceIPAddressException - if IP address restriction is enabled and the IP address of the requesting client is not an allowed IP address, then this exception will be thrown.
- VerificationFaultException - there was an error while attempting to contact the data source.
- SystemException - there was an internal error in greenID while processing the request.
RegisterVerification
This method must be called before any of the other web methods in this API for a verification of an individual person. This method will register the person’s details, a.k.a. the “master record”, with greenID. This method establishes a verificationId that must be used to identify this particular verification attempt in subsequent method calls.
...