Introduction

Esponce API offers you a way to integrate QR Code features into your application. API can be used in your application to automate generating QR Codes or decode content from scanned QR Code images or to handle trackable QR Codes and campaigns.

Ask a question?

If you have any questions please contact us

Quick start

To get familiar with API try the following examples:

1. To generate a QR Code make an HTTP GET request to http://www.esponce.com/api/v3/generate?content=hello&format=png where "hello" will be encoded in a QR Code. This method can be tested directly in a web browser.
2. To decode the content behind a QR Code image make an HTTP POST request to http://www.esponce.com/api/v3/decode and upload raw image bytes in the request. Server will return a message from the image, like { content: "some message" }
3. To get a list of campaigns and trackable QR Codes make a GET request to http://www.esponce.com/api/v3/track/list?auth=demo where the parameter auth should be your API key.

Libraries

Check out the libraries and samples to speed up integration.

API methods

All service method calls start with the base URL http://www.esponce.com/api/v3/ then follows a method name. Each method expects certain input parameters and returns a specific result. Details for each method are described further in the documentation.

General

generate	generate a QR Code image, using HTTP GET
decode	get content from QR Code image

QR Code Tracking

The following methods require API key to identify user:

track/list	get a list of campaigns and trackable QR Codes
track/campaign	manage campaign: select, insert, update, delete
track/qrcode	manage trackable QR Code: select, insert, update, delete
track/statistics	get statistics about a particular QR Code
track/export	export campaigns and trackable QR Codes
track/import	import campaigns and trackable QR Codes

Example

• URL to generate a QR Code: http://www.esponce.com/api/v3/generate
• URL to get a tracking list: http://www.esponce.com/api/v3/track/list

Troubleshooting

Note that URL ends without slash character (/), e.g. generate/ generate

API structure

API follows the REST guidelines: uses GET, POST, PUT and DELETE verbs, uses friendly names in URL, responds with appropriate HTTP status code, supports JSON and XML formats, etc.

Parameters

GET and DELETE methods expects parameters only in URL. POST and PUT methods accepts combined parameters in both HTTP body and/or URL query depending on the context. Request parameters in URL must be present as key-value pairs where values are URL encoded.

Some parameters are required while others are optional. If required parameter is missing HTTP responds with status code 400 Bad Request. If an optional parameter is not set it automatically gets the default value.

Variable types

bool	true/false value
int	32-bit integer
double	decimal number
string	UTF-8 string in JSON/XML or URL encoded string in URL query
date	date formatted as "yyyy-MM-dd", e.g. "2012-01-05" for 5th January 2012
timestamp	date and time formatted as "yyyy-MM-ddTHH:mm:ssZ" (ISO 8601)
color	ARGB color, e.g. "#7FFFF500" for semi-transparent yellow
array	array of int, string, object or other types
object	custom type, additionally described in the documentation

Error handling

Errors are reported as HTTP status code: HTTP response may also contain extra HTTP headers:

• X-Api-Error with a detailed error message for developer
• X-Api-Error-Code with numeric error identifier
• X-Api-Error-Hint with hint how to solve the problem

X-Api-Error-Code values

1000	General error
1001	Deprecated method or parameter
2001	User not authenticated
2002	User does not exist
2003	User is not activated
2005	Access denied, user should check credentials (username and password)
3001	Rate limit exceeded
3002	Need to upgrade package plan
4002	Check parameter value
4003	Record does not exist
4004	Record does not belong to authenticated user
4005	Record contains no data

Secure connection

To use a secure HTTPS connection just replace http with https in base URL, i.e. https://www.esponce.com/api/v3

Authentication

Some methods require authentication to identify the caller. You will need an API key for authentication (get it at your profile page).

API key is passed as auth parameter in URL query, e.g. http://www.esponce.com/api/v3/track/list?auth=9b02ec5da819ff14450c56583211eff3

Warning: try not to use API key in public as malicious users can copy your API key and abuse it (e.g. unwanted delete or content change)

Data formats

In general methods can handle user-preferred JSON (application/json) or XML (application/xml) while import/export methods support CSV, XLS, XML, ZIP formats.

Data format is defined in Accept header, e.g. request with Accept: application/json returns data formatted as JSON while Accept: application/xml returns XML data. Default content type is JSON in case Accpet header is missing.

Limitations

API methods have limited rate of HTTP requests per IP per day. Values below are specified in number of requests per day: Some other restrictions are bound to package plan, e.g. how many tracking QR Codes are available to the user. The restrictions are similar to those on our web interface.

Additional notes

• character encoding: UTF-8
• all dates and times are considered by UTC time zone

Libraries and Samples

Libraries

• C# .NET 3.5 library and samples hosted on CodePlex
• Java and Python library, Google Project Hosting
• PHP library and samples hosted on GitHub

Samples

• Esponce Blog contains some code to copy-paste for C#, Java, JavaScript, Python and PHP