API v3 Messages, Return Codes, Options

API v3 Overview

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

API v3 authentication uses an account username & secret which is used for API access only and wholly different to the email and password you use to login to Handset Detection. API v3 accepts JSON only.


API v3 requests use a modified one way HTTP Auth Digest, the content-type header identifies the payload which is always json.

content-type application/json

Authorization Digest username=”Mufasa”, realm=”APIv3″, nonce=”dcd98b7102dd2f0e8b11d0f600bfb0c093″, uri=”/site/detect/21.json”, qop=auth, nc=00000001, cnonce=”0a4f113b”, response=”6629fae49393a05397450978507c4ef1″, opaque=”5ccc069c403ebaf9f0171e9517f40e41″

The Request

Request payloads contain HTTP Request Headers as sent to your server by the client. Usually this is headers like HostAcceptAccept-CharsetAccept-LanguageUser-Agentx-wap-profile (and any other x-headers).

User-Agent and x-wap-profile are the 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.

Detection Options

The v3 Schema is completely different to the v2 Schema. To assist in migrating to the new schema we have provided the legacy keyword which allows you to query for v2 options through the v3 API. Include the legacy capability with your request as well : so your options would be legacy, product_info. Legacy options are any of the v2 capability groups : 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.

Messages & Statuses (Error codes)

Valid reply messages & statuses are :

API Version Status
(Error Code)
Message Meaning
1,2,3 OK No Errors
1,2,3 100 Unknown request type. Use json Try setting content-type in http headers
2,3 200 Bad username/secret combination  
2,3 201 Unmatched digest Digest does not match (check your username & secret)
1,2,3 203 Maximum query limit reached or account suspended You’re over quota. Consider upgrading your plan
1,2,3 205 Can not decode your JSON Ensure your JSON is well formed
1,2,3 206 No data in payload Use http post, Ensure you have a request body
1,2,3 207 Vendor missing Supply a vendor in your request body
1 208 Apikey not found Apikey missing from request body
1,2,3 210 Model missing Supply a model in your request body
1,2,3 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,3 300 User-Agent or x-wap-profile missing in request Warning Message, Not fatal.
1,2,3 301 Not Found Device not found in the database. Warning Message, Not fatal.

Get Started Today

Our free Express / Cloud plan has 20,000 detections per month. No credit card required. Upgrade when you're ready. We also have a free Community Edition for Ultimate Detection, our high performance local detection library, which you can build into community open source projects.

Get Started. Its Free