Welcome Back

Email
Password
New to Esponce? Create an Account.

Sign Up

We make it easy for you to enhance your mobile strategy.
You can change your plan anytime.

Fortune 500 companies and world most known brands trust Esponce
First Name
Last Name
Email
Password
Confirm Password
By clicking “Create Account”, I agree to the Esponce
Terms of Service and Privacy Policy.
Already an Esponce user? Log In.

Forgot password?

Please provide the Email address that you used when you signed up for your Esponce account.
You will receive an email with instructions on how to reset your password.

Change Password

New Password
Confirm Password

API documentation

Learn how to use Esponce API based on REST web service

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:
200 OK Request has been successfully processed, no error.
400 Bad Request Some parameter is missing or value not specified properly. Check if required parameters are specified.
401 Unauthorized API key is missing or authenticated user does not have permissions to call the method.
403 Forbidden Server is refusing to respond. Check the conditions.
404 Not Found Resource does not exist. Check URL and resource name (id) if in URL.
405 Method Not Allowed Calling method with GET but the method only supports POST verb? Check the Allow header for available verbs.
500 Internal Server Error Internal error occurred on a server. Please notify us so we can fix the problem.
503 Service Unavailable Website or web service is under maintenance. Check the Retry-After header and try again later.
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:
Methods Anonymous Basic Pro Premium
generate 1.000 1.000 5.000 10.000
decode 200 200 1.000 2.000
track/list
track/campaign
track/qrcode
N/A 200 1.000 2.000
track/statistics N/A 200 1.000 2.000
track/export
track/import
N/A N/A 1.000 2.000
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

Samples

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

Utility to create QR Code on the fly