API v2.0 - Headers, Codes, Options and Messages

Jump To: Headers | The Request | Detection Options | Messages & Statuses (Error codes)

Headers

All API v2.0 requests require at least the following headers to be set. The software-token header identifies your software (this is a version 2.0 apikey), the content-type header identifies the payload, the authorization header and x-wsse header identify the account holder making the request.

software-token 6268538248dcd2d532ae4b1d8e66ebaf
content-type text/xml or application/json
authorization WSSE profile="UsernameToken"
x-wsse UsernameToken Username="demo@handsetdetection.com", PasswordDigest="4yjxbRDtWzow2wj2C2GQZwx4Vrw=", Nonce="OTJhZTBjMzMxODc2Njg0ZjQ3NDI3YzVhOGVhMzI2YzQ=", Created="2009-08-10T05:58:18Z"


The Request

Request payloads contain a site ID and the HTTP Request Header as sent to your server by the client. Usually this is headers like Host, Accept, Accept-Charset, Accept-Language, User-Agent, x-wap-profile (and any other x-headers).

User-Agent and x-wap-profile are most important parts of the header, other X- headers are also important as content transformation proxies often squirrel real browser information away in them. IP address is required for geoip (ip address, http_remote_addr). Other browser headers also aid in improving the effectiveness of matching.

The site ID is optional and used to log the request against a site. If the site ID missing from the request it will be logged against your default site.

Detection Options

These are capabilities (information groups) you wish get from a device query. Valid options are any of the following : product_info, wml_ui, chtml_ui, xhtml_ui, ajax, markup, cache, display, image_format, bugs, wta, security, bearer, storage, object_download, wap_push, drm, streaming, mms, j2me, sms, sound_format, flash_lite, geoip OR all.

Add multiple options by separating them with a comma in the options field. If you leave options out, or send an empty options field then we’ll send back some of the most common capabilities for your device.

NOTE: Replys for 'all' can be up to 20k in size.

Extra NOTE: In the original dataset boolean reply values would be sent as 1 or 0. Pass option fixbool to get string equivalents 'true' or 'false' instead.

Messages & Statuses (Error codes)

Valid reply messages & statuses are :

API Version Status
(Error Code)		 Message Meaning
1,2 0 OK No Errors
1,2 100 Unknown request type. Use xml or json Try setting content-type in http headers
2 200 Bad username/secret combination
2 201 Unmatched digest Digest does not match (check your username & secret)
1,2 202 Apikey/software-token unknown, Inactive or Suspended
1,2 203 Maximum query limit reached or account suspended You're over quota. Consider upgrading your plan
1,2 204 Can not decipher your XML Ensure your XML is well formed
1,2 205 Can not decode your JSON Ensure your JSON is well formed
1,2 206 No data in payload Use http post, Ensure you have a request body
1,2 207 Vendor missing Supply a vendor in your request body
1 208 Apikey not found Apikey missing from request body
2 209 Software-token not set Set a software-token in the http header
1,2 210 Model missing Supply a model in your request body
1,2 211 Invalid Site ID The Site ID was supplied but it is not found or not owned by the user. Double check your site id
1,2 300 User-Agent or x-wap-profile missing in request Warning Message, Not fatal.
1,2 301 Not Found Device not found in the database. Warning Message, Not fatal.