Developer Guide
Using the Verify Locatability API
11.0 Using the Verify Locatability API
The Verify Locatability API tests whether a particular mobile number is potentially able to be located by your application. Even if the end user has not granted permission to be located, or if a Veriplace account has not yet been created for that number, the Veriplace platform has rules to determine whether those things can happen. You can use that information to tell end users whether your application is compatible with their mobile carrier.
For a launched application (see 2.4 Certifying and Launching Your Application), whether a mobile number is locatable depends on its carrier. Applications may be certified for all carriers, or only for specific ones. Veriplace can look up the carrier for any valid North American mobile number and check it against the list of allowed carriers for the application. The API will not tell you what the carrier is, only that is is supported.
For an application that's still in development and hasn't been certified for any carrier, the only numbers that are locatable are the ones you have designated as test phones on the Veriplace Developer Portal site. Also, if and when an end user creates a Veriplace account with that number, the user must choose to enable developer mode or the number will not be addressable by an unpublished application even if it is on the test phone list; see the tutorial on Enabling Developer Mode.
Note that these rules apply to the number rather than to the mobile phone itself. Some phones do not have a location feature, or have a service plan that doesn't allow them to be located; if the number has not yet been registered with Veriplace, it's not possible to determine what type of phone the user has until the phone has contacted Veriplace by SMS or mobile web.
Also, locatability is not the same as permission; you will not be able to locate a phone unless the end user has previously granted permission (via web or SMS). See Using the Verify Permission API and Using the Invitation API.
11.1 Querying a Mobile Number
To make this request, submit an HTTP GET to the following URL:
https://veriplace.com/api/1.2/verify/carrier?mobile=NUMBER
The value of the mobile query string parameter should be a ten-digit North American mobile number. You may also prefix the number with "1" or "+1", and Veriplace will ignore all other non-numeric characters, so the following numbers are all equivalent: 5105551212, 15105551212, 1-510-555-1212, +15105551212.
The request must be signed using HMAC-SHA1 and the application-specific Access Token (the one configured for your application as a whole, rather than for a particular user).
11.1.1 Successful Requests
If the mobile number is valid and potentially locatable by your application, you will receive an HTTP 200 ("OK") code. The response has no other content.
11.1.2 Unsuccessful Requests
The following HTTP status codes indicate error conditions:
- 400: the mobile number was not in a valid format
- 401: the application-specific Access Token was not valid
- 403: the mobile number was valid, but the number is not locatable by your application
- 404: Veriplace was not able to determine the carrier for the mobile number (the number may not be in use)