Instamojo for Developers

Instamojo API v1

You can now access Instamojo programmatically via the API. With version 1.0β you can query a user's offers, create new and edit existing offers. Since the API is based on REST principles, you can easily write and test applications using standard conventions.

We have launched the API in private beta. You need to send an email to api@instamojo.com with subject mentioning "App ID" before you can use the API. Rest of the documentation assumes you have received your appid and that you have registered an account on Instamojo.

An example implementation of the client in Python can be found on our github.

You can use the Python API library or the PHP API Library to get started quickly.

API Endpoint:

All calls to the API are made on top of this URL:

https://www.instamojo.com/api/1

The API is served over HTTPS to ensure privacy of user's data.

Conventions

URLs

All URLs must end with a trailing slash /.

DO
https://www.instamojo.com/api/1/debug/
DON'T
https://www.instamojo.com/api/1/debug

Headers

Authentication data - App-Id and Auth-Token needs to be passed as HTTP X-Header.

# python
import requests
headers = {
           'X-Auth-Token':'444b343537d7906b06e763434fe0c23e',
           'X-App-Id':'8b56476219c163922b66565abe6c4112'
          }
r = requests.get('https://www.instamojo.com/api/1/debug/', headers=headers)

Or in cURL terms:

curl --header "X-App-Id: test" --header "X-Auth-Token: 3ac9b762b44838b24d1629e319f4f2c6" https://www.instamojo.com/api/1/debug/

Response

Responses will be in JSON, in the following generic format:

# JSON
{
  'success':[true or false],
  ...response data...
}

Example response from debug

{"success": true, "message": "Hello hiway! Everything looks peachy here."}

Example error from debug

{"success": false, "message": "API works, but user authentication failed. Got a token?"}

HTTP status will always be returned as 200.

Authentication

Get Auth token

Path

POST /auth/

Required Parameters:

Parameter Description
username Username as registered on Instamojo.com
password Password associated with your username.

Required Headers:

Header Description
X-App-Id Application ID that you received from Instamojo

Response

{
  'success': true,
  'token': '444b343537d7906b06e763434fe0c23e'
}

Delete Auth Token

Path

DELETE /auth/:token/

Required Headers:

Header Description
X-App-Id Application ID that you received from Instamojo

Response

{'message': 'Deleted', 'success': true}

Offer

List All Offers

Path

GET /offer/

Required Headers:

Header Description
X-App-Id Application ID that you received from Instamojo
X-Auth-Token Auth token that you received via /auth/

Response

{"offers": [
  {"shorturl": "http://imojo.in/1b9Auhb", 
  "title": "A View to Die For [photo]", 
  "slug": "a-view-to-die-for-photo", 
  "status": "Pending Moderation"}], 
"success": true}

Create an Offer

Path

POST /offer/

Required Parameters:

Parameter Description
title Title, keep concise since slug is auto-generated from the title [max: 200 char, required]
description Detailed description of the offer, can contain markdown
currency Currency of the offer. Can be INR or USD
base_price Price of the offer as a decimal (up to 2 decimal places)
quantity Keep zero for unlimited quantity, any other positive number will limit sales/claims of the offer and make it unavailable afterwards.
start_date Required for events, date-time when the event begins. Format: YYYY-MM-DD HH:mm
end_date Required for events, date-time when the event begins. Format: YYYY-MM-DD HH:mm
timezone Timezone of the event. Example: Asia/Kolkata
venue Required for events, location where the event will be held.
redirect_url You can set this to a thank-you page on your site. Buyers will be redirected here after successful payment.
note A note to be displayed to buyer after successful payment. This will also be sent via email and in the receipt/ticket that is sent as attachment to the email.
file_upload_json JSON that you receive after uploading the file you want to sell.
cover_image_json JSON that you receive after uploading cover-image.

Required Headers:

Header Description
X-App-Id Application ID that you received from Instamojo
X-Auth-Token Auth token that you received via /auth/

Response

{"offer": 
  {"description": "A unicorn, captured in a gif file, gives you invisible powers.",
   "url": "https://www.instamojo.com/dummy/sparkly-unicorn/", 
   "slug": "sparkly-unicorn", 
   "title": "Sparkly Unicorn", 
   ...
  }, 
"success": true}

Uploading File and Cover Image

Instamojo encourages you to upload the file asynchronously, so if you are creating an app, you can start uploading a file right away and let the user type in details in the meanwhile. This reduces the time between a user pressing 'submit' and the offer getting fully uploaded.

Path

GET /offer/get_file_upload_url/

Required Headers:

Header Description
X-App-Id Application ID that you received from Instamojo
X-Auth-Token Auth token that you received via /auth/

Response

{"upload_url": "https://...", 
 "success": true}

Once you have upload_url, make a POST request to it with the following data:

Path

POST [upload_url]

Required Parameters:

Parameter Description
fileUpload POST data - upload a file.

Example (Python)

import requests
files = {'fileUpload':(filename, open('filename.txt', 'rb'))}
requests.post(upload_url, files=files)

Example (cURL)

curl -X POST -F fileUpload=@filename.txt [upload_url]

Edit an Offer

Path

PATCH /offer/:slug

Required Parameters:

Same as required for creating an offer.

Required Headers:

Header Description
X-App-Id Application ID that you received from Instamojo
X-Auth-Token Auth token that you received via /auth/

Details of an Offer

Path

GET /offer/:slug/

Required Headers:

Header Description
X-App-Id Application ID that you received from Instamojo
X-Auth-Token Auth token that you received via /auth/

Response

{"success": true, "offer": 
  {"shorturl": "http://imojo.in/1b9Auhb", 
   "description": "Photograph from Ladakh, a beautiful view from Thiksey monastery.",
   "url": "https://www.instamojo.com/dummy/a-view-to-die-for-photo/", 
   "title": "A View to Die For [photo]", 
   "slug": "a-view-to-die-for-photo", 
   "currency": "INR", 
   "base_price": "50.00",
   ...

}}

Archive an Offer

Path

DELETE /offer/:slug/

Required Headers:

Header Description
X-App-Id Application ID that you received from Instamojo
X-Auth-Token Auth token that you received via /auth/

Response

{"success": true, "message": "Offer has been archived."}