Developer Guide

Using the Invitation API

9.0 Using the Invitation API

Not every application fits naturally into an OAuth redirect-based authorization process. For example, SMS-based applications have no natural way to send a redirect. For these situations, Veriplace offers an SMS-based opt-in, in which the end user replies affirmatively to an SMS invitation to grant permission to be located.

The Invitation API allows authorized applications to invite a specific mobile number to opt-in to be located. The calling application may choose to receive an asynchronous callback when this opt-in occurs, or may poll for the result.

This feature must currently be enabled by WaveMarket for specific applications based on a developer request. Please contact WaveMarket developer support if you plan to use the Invitation API. Applications under development that have not yet been published will only be able to invite users who are on their Test Phones list (see Enabling Developer Mode).

9.1 About SMS Opt-In

The SMS Opt-In mechanism consists of Veriplace sending an SMS to the end user asking them to grant permission to be located by a specific application. The user can send an SMS reply to grant permission, and also to register with Veriplace at the same time if not already registered; or the user can refuse, either by declining that particular invitation or by requesting a block on all future SMS invitations.

There is also a user-initiated SMS opt-in mechanism, separate from the Invitation API: your application can be configured with a unique keyword which the user can send to Veriplace's SMS shortcode, in which case the user can grant permission without requiring any action by your application. Contact WaveMarket if you would like to enable this feature.

9.2 Sending an Invitation

Invitations may be requested by submitting an HTTP POST to:

https://veriplace.com/api/1.2/invitations

Requests must be signed using HMAC_SHA1 and the application-specific Access Token.

The request's form-encoded body contains the following parameters:

mobile (required): the mobile number to be invited. Veriplace accepts ten-digit numbers optionally prefixed with "1" or "+1", and ignores all other non-numeric characters.
callback (optional): a URL where your application can receive an HTTP notification from Veriplace. See 9.5 Getting the Final Result
callbackContentType, callbackFormParamName: for asynchronous requests only, these parameters control the format of the callback notification. See 9.5 Getting the Final Result.
sendUserConfirmation (optional): true if Veriplace should send a final SMS to the end-user after the user has accepted or declined the invitation. Any other value (or no value) means that Veriplace will skip this final message, in which case the application is responsible for notifying the user of the result on completion.

9.2.1 Common Failure Cases

Because there are privacy considerations sending unsolicited messages, Veriplace may forbid requests under some circumstances or for some applications. In this case, Veriplace will return an HTTP 403 error.

9.3 Successful Requests

On success, you will receive an HTTP 200 ("OK") code and a result document in one of two forms:

If there is already a Veriplace user with the given mobile number opted-in to your application, the document will contain a Veriplace user ID, and the OAuth access token for locating the user.
Otherwise, the document will contain a one-time nonce (a correlation key) unique to this request, to associate it with its eventual outcome; see 9.5 Getting the Final Result.

The user ID/access token response is represented in XML or JSON as follows:

<?xml version="1.0" encoding="UTF-8"?> 
    <invitationResult xmlns="http://veriplace.com/xml/1.2">
        <mobileNumber>mobileNumber</mobileNumber>
        <user id="userID"/>
        <token value="token" secret="tokenSecret"/>
    </invitationResult>

{ "invitationResult": {
  "mobileNumber": "mobileNumber",
  "user": { "id": "userID" },
  "token": { "value": "token", "secret": "tokenSecret" }
} }

The nonce response is represented in XML or JSON as follows:

<?xml version="1.0" encoding="UTF-8"?> 
    <invitationResult xmlns="http://veriplace.com/xml/1.2">
        <mobileNumber>mobileNumber</mobileNumber>
        <nonce value="value"/>
    </invitationResult>

{ "invitationResult": {
  "mobileNumber": "mobileNumber",
  "nonce": { "value": "value" }
} }

9.4 Unsuccessful Requests

You will receive an HTTP 400 status code if the request was malformed, an HTTP 401 status code if the provided application-specific access token was invalid, and an HTTP 403 error if the invitation could not be sent for some reason.

Note that Veriplace will return a 400 error if you specify a callback that is not a valid externally accessible HTTP URI, e.g. if its domain is localhost.

9.5 Getting the Final Result

If the user responds to the invitation within 24 hours, either agreeing to opt into your application or explicitly declining, then the invitation is complete. To detect this, you can either query the status of the invitation or ask Veriplace to push the result to you.

9.5.1 Querying Results

If you do not specify a callback parameter in the invitation, then it is up to you to query Veriplace for the result at some point in the future. You can do this by making an HTTP GET request to the following protected resource URL, using the same nonce value that was returned when you made the original request:

https://veriplace.com/api/1.2/requests/<nonce>

You can repeat the query as many times as necessary, for up to 24 hours; after that, the request expires and any further queries with that nonce value will receive an HTTP 404 error.

If the user has not yet responded, Veriplace returns HTTP status 204 ("No Content"). If the user has responded, or if the invitation failed, Veriplace returns a result document similar to the one described above in 9.3 Successful Requests. It will always contain the <nonce> and <mobileNumber> elements that identify the invitation, and if successful it will have the <user> and <token> elements. If unsuccessful, it will have an <apiError> element containing an error code as follows:

401, if the user declined the invitation;
403, if the invitation turned out to be disallowed after it was submitted.

The format of the apiError element in XML or JSON is as follows:

<apiError>
    <code>401</code>
    <message>User declined</message>
</apiError>

"apiError": {
  "code" 401,
  "message": "User declined"
}

9.5.2 Receiving Notification by Callback (Push)

If your application can receive HTTP requests, you can tell Veriplace to push a notification to a URL of your choice, which you specify as the callback parameter of the original request. Veriplace will make an HTTP POST request to this URL. This message can use one of several formats, depending on what is most convenient for your application:

The summary format, which is used if you only specified a callback URL, contains a query string in the application/x-www-form-urlencoded content type. Since this callback can be delivered non-securely, it does not contain the user's mobile number or access token; you will have to keep track of the mobile number yourself (associating it with the nonce value) and use the Verify Permission API to get the token. The query string parameters are as follows:

nonce: the unique identifier that was returned when you made the original request
code: the HTTP status code representing the outcome of the request (200 if successful, 401 if declined, 403 if not allowed)
reason: an optional error description, equivalent to the HTTP status message
user: the Veriplace user ID, if the user accepted the invitation

The extended format is used if you also specified a callbackContentType parameter, whose value must be either "text/xml" or "application/json". In this case, the message will be an <invitationResult> object in XML or JSON, containing all the result details if available, as described above. To use this mode, your callback URL must be secure (https:).
The form-encoded extended format is the same as the extended format, but wraps the entire XML or JSON document in a form-encoded parameter -- e.g., <?xml version=... becomes myParamName=%3C%3Fxml+version%3D.... This format is used if you specify callbackFormParamName=myParamName along with callbackContentType. This may be useful if your application receives callbacks through a web gateway that can only accept form-encoded content, but you still want the details included in the extended format.

To confirm receipt of the callback, your application must return an HTTP 200 response within 2000 milliseconds. Otherwise, Veriplace will consider the request a failure and will retry up to 3 times before giving up.

Location Labs

Universal Location Service