Versions Compared

Version Old Version 3 New Version 4
Changes made by

Sharmeen Hussain

Sharmeen Hussain

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This method checks that the input account is enabled for Hosted, performs validation using the input details and then will prepare a link to the hosted site for the account and send this link to the input mobile phone number via SMS.

Info

If you are using this method, please also refer to getHostedSMSInvitationStatus as this method can facilitate with tracking invitation progress.

Inputs Parameters

Field 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 the API.

smsVerificationId

String

No (may be null)

smsVerificationId is supplied by the customer and will become the verificationId when the user registers. If smsVerificationId is not supplied by the customer, greenID will generate a verificationId for the registration. (confirm if required or optional)

ruleId

String

No (may be null)

Callers have a specific rule configured for their greenID Hosted account.  This string must identify a rule. Contact greenID for the name of the rule configured for your Hosted account.  If only one rule is configured, then the string “default” will automatically select that rule.

name

String

Yes

mobilePhone

String

Yes

See Mobile Phone Validation

extraData

List <NameValuePair>

No

This parameter allows the customer to send extra data that will need to be agreed upon before implementation. It will be a simple key /value format. If there is no previous agreement for certain keys to be sent in this field then it will be ignored.

Return Values

The API call returns a GreenIDHostedServiceResult containing the following data:

Field Name

Type

Notes

smsInvitationId

String

An identifier specifically related to the SMS invitation generated. This identified can be used to query the status of the SMS SMS and registration via a web service call.

smsVerificationId

String

Returns the smsVerificationId defined by the customer in the input. If smsVerificationId is not provided, this will be empty / null.

smsInvitationStatus

String

Values = waiting, expired or complete.

waiting = user has not yet registered

complete = user is now registered in greenID

expired = link has expired and user is not registered

smsId

String

A unique identifier of the SMS message sent.

smsStatus

String

Indicates whether the SMS has been successfully submitted to the SMS provider, or if an error occurred meaning the SMS will not be sent.

Values can be:  'submitted' or 'error'

responseErrorFlag

Boolean

True = an error occurred
False = no error occurred

responseErrorMessage

String

A message providing information regarding the error that occurred.

errorReasonCode

String

Indicates the type of error that occurred.

Exceptions

  • InvalidCustomerIdException (or InvalidAccountIdException) – the accountId 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 web service IP restriction is enabled, then this exception will be thrown if the caller's IP address is not white-listed.

  • HostedAccountException  - the Hosted account is not appropriately configured. For example, account is not enabled for Hosted or account is not enabled for SMS.

  • SystemException - an unexpected error occurred.

getHostedSMSInvitationStatus (Pending)

This method checks that the input account is enabled for Hosted, performs validation using the input details and then will provide a status of the SMS invitation associated with the SMS Invitation ID.

Info

This method shouldonlybe used if you are using sendHostedSMSInviteForOnboarding  - it is not compatible with other Hosted web services.

Inputs Parameters

Field Name

Type

Required

Description

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 the API.

smsInvitationId

String

Yes

Returns the smsVerificationId defined by the customer in the input. If smsVerificationId is not provided, this will be empty / null.

extraData

List <NameValuePair>

No

This parameter allows the customer to send extra data that will need to be agreed upon before implementation. It will be a simple key /value format. If there is no previous agreement for certain keys to be sent in this field then it will be ignored.

Return Values

The API call returns a GreenIDHostedServiceResult containing the following data:

Field Name

Type

Description

smsInvitationId

String

An identifier specifically related to the SMS invitation generated. This identified can be used to query the status of the SMS and registration via a web service call.

smsInvitationStatus

String

Values = waiting, expired or complete.

verificationId

String

The verificationId will be returned if the smsInvitationStatus is 'complete'. If it is waiting or expired, this field will be empty.

overallVerificationStatus

String

The overall status of the verification.

For this method, this will only be populated with a value once a user has registered and the SMS Invitation Status is 'Complete'. Please use geVerificationResult for subsequent verification updated.

smsId

String

A unique identifier of the SMS message sent.

smsStatus

String

Indicates whether the SMS has been successfully submitted to the SMS provider, or if an error occurred meaning the SMS will not be sent.

Values could be: Submitted, Delivered, Undelivered, Sent and Failed

responseErrorFlag

Boolean

True = an error occurred
False = no error occurred

responseErrorMessage

String

A message providing information regarding the error that occurred.

errorReasonCode

String

Indicates the type of error that occurred.

Exceptions

  • InvalidCustomerIdException (or InvalidAccountIdException) – the accountId 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.

  • InvalidSourceIPAd. cxcdressException - if web service IP restriction is enabled, then this exception will be thrown if the caller's IP address is not white-listed.

  • HostedAccountException  - the Hosted account is not appropriately configured. For example, account is not enabled for Hosted or account is not enabled for SMS.

  • SystemException - an unexpected error occurred.

Useful Links:

Include Page
greenID include
greenID include

On This Page

Table of Contents
minLevel1
maxLevel7
excludeOn This Page
Include Page
greenID Hosted Web A-Z
greenID Hosted Web A-Z