API RESOURCES
Let your imagination be the limit
API's
  • Introduction
  • Base URL
  • Authentication
  • Date and Time Formats
  • Errors
  • Create Geo-Fences
    • Save Geo-fence - Detailed
    • Save Category
    • Save Brand
    • Save Cost Center
    • Save Geo-fence - Partial
  • Fetch Locations
    • Fetch location - Multiple
    • Fetch Status - Previously Requested
    • Fetch location - Single Opt-in
  • View Configuration
    • List Campaigns
    • List All Brands
    • List All Categories
    • List All Opt-ins
    • List All Geo-fences
    • List All Offers - Single Opt-in
    • Previous Offers - Single Opt-in
Introduction

Fetchon APIs allow you to create and query geo-fence based campaigns as well as query the location of opted-in consumers, and the associated functions.

The APIs are constructed on RESTful HTTP and use a combination of:

  • Result oriented URLs
  • POST and GET Methods
  • In-built HTTP functionality for authentication and parameters
  • Standard HTTP response codes and errors
  • JSON Content-Type and responses
Base URL

All base URLs in the referenced documentation have the following construct:

https://api.fetchon.com/api/v1/customer/

All Fetchon APIs are supported over HTTPs to ensure data security and privacy.

Authentication

All requests to the Fetchon API are authenticated via Auth Tokens that are set via X-Auth-Token value in the Header of the JSON request.

Share a few details here and we will be happy to evaluate and have you sign up for a demo!

Date and Time Formats

Fetchon returns JSON for all API calls.

Date and Time values are passed as strings encoded according to RFC2822.

Errors
Code Description
202 All is well
400 Probably missed a parameter or two
401 Oops! Valid Auth Token not provided
402 Failed Request
404 The requested item not found
500 You caught us napping!
Save Geo-fence - Detailed
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/campaign
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you wish to create a geo-fence
c_id string If you have your own internal CRM-generated ID that you wish to identify the campaign with, mention that entifier using this parameter
title string Human-readable name that you would like to see against the defined campaign
category_id number Assign an appropriate category_id to each of your campaigns. Refer to Save Category API for details
brand_id number Assign an appropriate brand_id to each of your campaigns. Refer to Save Brand API for details
costcenter_id number Assign an appropriate costcenter_id to each of your campaigns. Refer to Save CostCenter API for details
start_date date (ISO-8601) The date on which the campaign will start looking for opted-in consumers, in the defined Geo-fence
end_date date (ISO-8601) The date on which the campaign will stop looking for opted-in consumers, in the defined Geo-fence
active_days string[] An array of days of the week on which a campaign is active
location_str string Latitude and Longitude around which the campaign will be active
radius number Radius of the geo-fence (in meters)
description string The text that needs to be sent to the opted-in consumer when found in the geo-fence
Optional Parameter/s
Parameter Name Type Description
city string City in which the campaign is active
Request:
                                           
{
   "customer_id":6,
   "costcenter_id":6,
   "category_id":17,
   "brand_id":33,
   "city":"Your City",
   "start_date":"2015-10-01T11:10:00-05:00",
   "start_time":"2015-10-01T11:10:00-05:00",
   "end_date":"2015-12-31T21:30:00-05:00",
   "end_time":"2015-12-31T21:30:00-05:00",
   "active_days":[
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY",
      "SATURDAY",
      "SUNDAY"
   ],
   "radius":750,
   "title":"Your Campaign Title",
   "c_id":"Your CRM related ID for the campaign",
   "description":"Text of the campaign that will be sent to the opted-in user, if found in the geo-fence",
   "location_str":"17.434568x78.386882"
}
                                      
Response: Status 202 Accepted
Save Category
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/category
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you wish to create a geo-fence
name string The name that wish to assign to the category
Optional Parameter/s
Parameter Name Type Description
category_type string If you wish to group the category name against any specific category type, use this field to define that category_type
img string The path (URL) from which the image for this category needs to be picked-up from
Request:
                                           
{
   "customer_id":6,
   "name":"Category Name",
   "category_type":"Personal",
   "img":"https://…personal-category.png"
}
                                      
Response: Status 202 Accepted
Save Brand
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/brand
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you wish to create a geo-fence
name string The name that wish to assign to the category
Optional Parameter/s
Parameter Name Type Description
img string The path (URL) from which the image for this brand needs to be picked-up from
Request:
                                           
{
   "customer_id":6,
   "name":"Brand Name",
   "category_id":5,
   "img":"https://…brand.png"
}
                                      
Response: Status 202 Accepted
Save Cost Center
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/cost-center
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you wish to create a geo-fence
name string The name that wish to assign to the cost center
Request:
                                           
{
   "customer_id":6,
   "name":"Cost Center Name"
}
                                      
Response: Status 202 Accepted
Save Geo-fence - Partial
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/geofence
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you wish to create a geo-fence
location_str string Latitude and Longitude around which the campaign will be active
radius number Radius of the geo-fence (in meters)
Request:
                                           
{
   "customer_id":6,
   "location_str":"12.22x72.33",
   "radius":700
}
                                      
Response: Status 202 Accepted
                                           
{
   "id":1,
   "location":"12.22x72.33",
   "radius":700
}
                              
Fetch location - Multiple
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/fetch_location
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you wish to create a geo-fence
numbers string[] Mobile Numbers for which you want to know if or not they are in any of the defined geo-fences
callback_url string The URL to which the response(s) will be posted
streaming_response boolean If set to true, Fetchon will POST the geo-fence IDs in which any of the requested mobile numbers are available. If set to false, Fetchon will send the available geo-fence IDs for the mobile numbers as of that instant
Request:
                                           
{
   "customer_id":6,
   "numbers":[
      "+919632289xxx",
      "+919880569xxx",
      "+919786"
   ],
   "callback_url":"http://callbackurl/…",
   "streaming_response":"false"
}
                                      
Response: Status 202 Accepted
                                           
{
   "request_numbers":[
      "+919632289xxx",
      "+919880569xxx",
      "+919786"
   ],
   "invalid_numbers":[
      "+919786"
   ],
   "request_id":"9488ab13-6e05-4202-890d-17108eff4axx",
   "valid_numbers":[
      "+919632289xxx",
      "+919880569xxx"
   ]
}
                                
Fetch Status - Previously Requested
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/fetch_location
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you fetch location status for
request_id string The request_id for which you want to query the status. This request_id is generated via the POST request made to https://api.fetchon.com/api/v1/customer/:customer_id/fetch_location
Request:
                                           
{
   "customer_id":6,
   "request_id":"9488ab13-6e05-4202-890d-17108eff4axx"
}
                                      
Response: Status 202 Accepted
                                           
{
   "callback_url":" http://callbackurl/…",
   "success_count":0,
   "request_status":"SUCCESS",
   "request_count":2,
   "request_mobile_numbers":[
      "+919632289xxx",
      "+919880569xxx",
      "+919876"
   ],
   "request_at":"2015-12-28T19:11:58.847279+00:00",
   "failure_count":0,
   "request_id":"9488ab13-6e05-4202-890d-17108eff4axx"
}
                                
Fetch location - Single Opt-in
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/fetch
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
mobilenumber string The mobile number for which location is needed
isp string The request_id for which you want to query the status. This request_id is generated via the POST request made to https://api.fetchon.com/api/v1/customer/:customer_id/fetch_location
Request:
                                           
{
   "mobilenumber":"+919632289xxx",
   "isp":"AIRTEL"
}
                                      
Response: Status 202 Accepted
                                           
{
   "location":{
      "at":"2015-12-29T17:34:23.812+05:30",
      "lon":"77.5775",
      "lat":"12.9325"
   },
   "status":1
}
                                
List Campaigns
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/campaign
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you list campaigns for
Request:
                                           
{
   "customer_id":6
}
                                      
Response: Status 202 Accepted
                                           
[
   {
      "title":"Alpha Numeric Value",
      "start_date":"yyyy-mm-dd",
      "end_date":"yyyy-mm-dd",
      "c_id":"Alpha Numeric Value",
      "id":"campaign ID as returned by Fetchon while creating the campaign",
      "customer_id":"Assigned numeric customer_id",
      "category_id":"Assigned numeric category_id",
      "costcenter_id":"Assigned numeric costcenter_id",
      "city":"alpha-numeric value",
      "brand_id":"numeric brand_id",
      "description":"Text of the defined content",
      "radius":"numeric value (in meters)",
      "location_str":"decimalxdecimal",
      "start_time":"hh:mm:ss",
      "active_days":[
         "MONDAY",
         "TUESDAY",
         "WEDNESDAY",
         "THURSDAY",
         "FRIDAY",
         "SATURDAY",
         "SUNDAY"
      ],
      "end_time":"hh:mm:ss"
   },
   {
      "title":"Alpha Numeric Value",
      "start_date":"yyyy-mm-dd",
      "end_date":"yyyy-mm-dd",
      "c_id":"Alpha Numeric Value",
      "id":"campaign ID as returned by Fetchon while creating the campaign",
      "customer_id":"Assigned numeric customer_id",
      "category_id":"Assigned numeric category_id",
      "costcenter_id":"Assigned numeric costcenter_id",
      "city":"alpha-numeric value",
      "brand_id":"numeric brand_id",
      "description":"Text of the defined content",
      "radius":"numeric value (in meters)",
      "location_str":"decimalxdecimal",
      "start_time":"hh:mm:ss",
      "active_days":[
         "MONDAY",
         "WEDNESDAY",
         "FRIDAY",
         "SUNDAY"
      ],
      "end_time":"hh:mm:ss"
   }
]
                                
List All Brands
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/brand
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you list brands for
Optional Parameter/s
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you list brands for
Request:
                                           
{
   "customer_id":6,
   "category_id":14
}
                                      
Response: Status 202 Accepted
                                           
[
   {
      "title":"Alpha Numeric Value",
      "start_date":"yyyy-mm-dd",
      "end_date":"yyyy-mm-dd",
      "c_id":"Alpha Numeric Value",
      "id":"campaign ID as returned by Fetchon while creating the campaign",
      "customer_id":"numeric customer_id assigned by Fetchon for your account",
      "category_id":"numeric category_id assigned while creating the campaign",
      "costcenter_id":"numeric costcenter_id assigned while creating the campaign",
      "city":"alpha-numeric value",
      "brand_id":"numeric brand_id assigned while creating the campaign",
      "description":"Text of the content that was defined while creating the campaign",
      "radius":"numeric value (in meters)",
      "location_str":"decimalxdecimal",
      "start_time":"hh:mm:ss",
      "active_days":[
         "MONDAY",
         "TUESDAY",
         "WEDNESDAY",
         "THURSDAY",
         "FRIDAY"
      ],
      "end_time":"hh:mm:ss"
   },
   {
      "title":"Alpha Numeric Value",
      "start_date":"yyyy-mm-dd",
      "end_date":"yyyy-mm-dd",
      "c_id":"Alpha Numeric Value",
      "id":"campaign ID as returned by Fetchon while creating the campaign",
      "customer_id":"numeric customer_id assigned by Fetchon for your account",
      "category_id":"numeric category_id assigned while creating the campaign",
      "costcenter_id":"numeric costcenter_id assigned while creating the campaign",
      "city":"alpha-numeric value",
      "brand_id":"numeric brand_id assigned while creating the campaign",
      "description":"Text of the content that was defined while creating the campaign",
      "radius":"numeric value (in meters)",
      "location_str":"decimalxdecimal",
      "start_time":"hh:mm:ss",
      "active_days":[
         "MONDAY",
         "WEDNESDAY",
         "FRIDAY"
      ],
      "end_time":"hh:mm:ss"
   }
]
                                
List All Categories
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/category
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you list categories for
Request:
                                           
{
   "customer_id":6
}
                                      
Response: Status 202 Accepted
                                           
[
   {
      "category_type":"alpha-numeric value while creating the category",
      "customer_id":"numeric customer_id assigned by Fetchon for your account",
      "img":"Location from which to fetch the category image",
      "name":"Name of the category",
      "id":"numeric id assigned by Fetchon for the category"
   },
   {
      "category_type":"alpha-numeric value while creating the category",
      "customer_id":"numeric customer_id assigned by Fetchon for your account",
      "img":"Location from which to fetch the category image",
      "name":"Name of the category",
      "id":"numeric id assigned by Fetchon for the category"
   }
]
                                
List All Opt-ins
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/consumers
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you list categories for
Request:
                                           
{
   "customer_id":6
}
                                      
Response: Status 202 Accepted
                                           
[
   {
      "id":"unique numeric id assigned to the consumer by Fetchon",
      "mobile":"mobile number of the consumer in international format",
      "email":"e-mail address, if captured at the time of registration",
      "valid_email":"boolean true or false",
      "valid_mobile":"boolean true or false",
      "isp":"alpha-numeric mobile operator name or source of location information"
   },
   {
      "id":"unique numeric id assigned to the consumer by Fetchon",
      "mobile":"mobile number of the consumer in international format",
      "email":"e-mail address, if captured at the time of registration",
      "valid_email":"boolean true or false",
      "valid_mobile":"boolean true or false",
      "isp":"alpha-numeric mobile operator name or source of location information"
   }
]
                                
List All Geo-fences
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/consumers
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account
Request:
                                           
{
   "customer_id":2
}
                                      
Response: Status 202 Accepted
                                           
[
   {
      "radius":500,
      "customer_id":2,
      "id":1,
      "location_str":"12.933788x77.583685"
   },
   {
      "radius":750,
      "customer_id":2,
      "id":2,
      "location_str":"12.929158x77.576543"
   },
   {
      "radius":1000,
      "customer_id":2,
      "id":3,
      "location_str":"19.114977x72.847607"
   }
]
                                
List All Offers - Single Opt-in
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/get-coupons
Note Replace {:customer_id} with the customer_id assigned to your account.
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you list categories for
mobile string Mobile Number in international format
location_lat number Latitude of geo-fence
location_lon number Longitude of geo-fence
Request:
                                           
{
   "customer_id":6,
   "mobile":"+919632289xxx",
   "location_lat":"77.5775",
   "location_lon":"12.9325"
}
                                      
Response: Status 202 Accepted
                                           
[
   {
      "title":"Alpha Numeric Value",
      "start_date":"yyyy-mm-dd",
      "end_date":"yyyy-mm-dd",
      "c_id":"Alpha Numeric Value",
      "id":"campaign ID as returned by Fetchon while creating the campaign",
      "customer_id":"numeric customer_id assigned by Fetchon for your           account",
      "category_id":"numeric category_id assigned while creating the            campaign",
      "costcenter_id":"numeric costcenter_id assigned while creating the            campaign",
      "city":"alpha-numeric value",
      "brand_id":"numeric brand_id assigned while creating the campaign",
      "description":"Text of the content that was defined while creating the           campaign",
      "radius":"numeric value (in meters)",
      "location_str":"decimalxdecimal",
      "start_time":"hh:mm:ss",
      "active_days":[
         "MONDAY",
         "TUESDAY",
         "WEDNESDAY",
         "THURSDAY",
         "FRIDAY"
      ],
      "end_time":"hh:mm:ss"
   },
   {
      "title":"Alpha Numeric Value",
      "start_date":"yyyy-mm-dd",
      "end_date":"yyyy-mm-dd",
      "c_id":"Alpha Numeric Value",
      "id":"campaign ID as returned by Fetchon while creating the campaign",
      "customer_id":"numeric customer_id assigned by Fetchon for your            account",
      "category_id":"numeric category_id assigned while creating the            campaign",
      "costcenter_id":"numeric costcenter_id assigned while creating the            campaign",
      "city":"alpha-numeric value",
      "brand_id":"numeric brand_id assigned while creating the campaign",
      "description":"Text of the content that was defined while creating the            campaign",
      "radius":"numeric value (in meters)",
      "location_str":"decimalxdecimal",
      "start_time":"hh:mm:ss",
      "active_days":[
         "MONDAY",
         "TUESDAY",
         "WEDNESDAY",
         "THURSDAY",
         "FRIDAY",
         "SATURDAY",
         "SUNDAY"
      ],
      "end_time":"hh:mm:ss"
   }
]
                                
Previous Offers - Single Opt-in
Method POST
URI https://api.fetchon.com/api/v1/customer/:customer_id/pushed_offers/{consumer_id}
Note Replace {:customer_id} with the customer_id assigned to your account. Replace {consumer_id} with the unique consumer_id of the opted-in consumer
Mandatory Parameters
Parameter Name Type Description
customer_id number Assigned by Fetchon for your account for which you list categories for
consumer_id number Unique consumer ID assigned per opted in consumer
Request:
                                           
{
   "customer_id":6,
   "consumer_id":78
}
                                      
Response: Status 202 Accepted
                                           
{
   "pushed_offer_ids":[
      10,
      12,
      16,
      18
   ]
}