logo
Documentation Powered by ReDoc

Instaon Partner API (1.0)

Download OpenAPI specification:Download

Instaon API Team: api@shown.io URL: https://instaon.io/partners License: Proprietary by Instaon Terms of Service

The official API to manage Instaon campaigns and assets. Please contact us via our Instaon Partner Program for more information and getting whitelisted.

Introduction

Th API allows you to register a Instaon user and build optimized marketing campaigns. Once a user has been authenticated over the api, you can add business information and start creating campaigns. Marketing campaigns are published to platforms (Google, Facebook, Microsoft, ..) with different goals (Get calls, get website traffic etc..). To publish a given campaign, all required features have to be added to a campaign.

Authentication

httpBearer

Most requests returning user data require a valid bearer token. Users are authenticated with a bearer token in the header of every request.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

authentication

API calls to register a user in order to obtain a bearer token. Bearer token must be added to every request in order to be able to access personnal data.

Login (Password Grant / Client Credentials Grant Flow)

header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
client_id
required
integer <int32>
client_secret
required
string
grant_type
required
string
password
required
string
scope
required
string
username
required
string

Responses

Login (Implicit Grant with Redirect)

query Parameters
client_id
required
integer <int32>
Example: client_id=75
redirect_uri
required
string
Example: redirect_uri=https://dev.instaon.io/app
response_type
required
string
Example: response_type=token

code or token

scope
required
string
state
required
integer <int32>
Example: state=25435353

{{$randomAlphaNumeric}}

Responses

Login (Deprecated in March 2020)

Request Body schema:
application/x-www-form-urlencoded
application/x-www-form-urlencoded
application/json
email
required
string
password
required
string

Request samples

Content type
application/x-www-form-urlencoded
application/x-www-form-urlencoded
application/json
No sample

Register

Authorizations:
httpBearer
Request Body schema: application/x-www-form-urlencoded
email
required
string
name
required
string
newsletter
required
boolean
password
required
string

Responses

Ask for password recovery mail

Request Body schema: application/x-www-form-urlencoded
email
required
string

Responses

Modify password via mail recovery

Request Body schema: application/x-www-form-urlencoded
password
required
string
password_confirmation
required
string
token
required
string

Responses

profile

Remove user card

Remove access to Stripe credit card.

Authorizations:
httpBearer
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
last_four
required
integer <int32>

Last four numbers

Responses

Get List of Country Codes

Get list of supported countries.

Authorizations:
httpBearer

Responses

media

Get User Media Library

Returns the list of media files that were added to the user's media library

Authorizations:
httpBearer

Responses

Get User Media's biggest file in base-64 encoding

Returns the biggest media file representation in base64

Authorizations:
httpBearer

Responses

Delete User Media

Remove a list of uploaded media files from the media library

Authorizations:
httpBearer
header Parameters
Content-Type
required
string
Example: image/png
Request Body schema: application/x-www-form-urlencoded
mediaId[0]
required
integer <int32>

Responses

Get Image Upload URL

This calls returns a form, that can be used to add media files to a user's media library

Authorizations:
httpBearer

Responses

pages

Get Pages for Platform

Get list of pages the user has given access to (ex: Facebook pages)

Authorizations:
httpBearer
path Parameters
platformId
required
integer <int32>
Example: 2

Responses

orders

API calls to read user invoices and manage marketing spend

Get Orders List

Get the list of invoices for the current user

Authorizations:
httpBearer

Responses

Get Order Details

Get details for a given invoice (amount, date, etc)

Authorizations:
httpBearer
path Parameters
orderId
required
integer <int32>
Example: 8967

Responses

payments

API calls to add credit to a user account.

Set Automatic Billing Status

Activate or deactivate auto-billing for a business. Auto-billed businesses will have new credits automatically billed when they reach zero balance.

Authorizations:
httpBearer
Request Body schema: application/json
active
required
boolean

Responses

Request samples

Content type
application/json
{
  • "active": false
}

Get list of supported currencies

Authorizations:
httpBearer

plans

List of API calls to read and manage user subscriptions

Select Free Plan

Downdgrade user back to free plan.

Authorizations:
httpBearer

Start Stripe Plan Transaction

Get a session id you can use to redirert the user to Stripe Checkout.

Authorizations:
httpBearer
path Parameters
plan
required
string
Example: grow9

available plans:

  • grow9
  • pro99
  • enterprise
query Parameters
return_url
required
string
Example: return_url={{app_url}}

Responses

vouchers

Get User Vouchers

Get list of vouchers that are claimed, accessible or unavalaible for this user.

Authorizations:
httpBearer

Responses

Redeem Voucher

Use a voucher. If claimed succesfully, user will receive credits or paid plan according to voucher settings.

Authorizations:
httpBearer
path Parameters
voucher_code
required
string
Example: {{voucher_code}}

Responses

Stripe

Start Stripe Credit Transaction

Initiate a Stripe transaction for the user to add credit to his account. User will have to redirect to Stripe to authorize the transaction if this is his first time payment.

Authorizations:
httpBearer
path Parameters
amount
required
integer <int32>
Example: 123

Amount in euros

product
required
integer <int32>
Example: 10

Set product type to 10 to add credits

query Parameters
publish_campaign_id
required
string
Example: publish_campaign_id={{test_campaign_id}}

optional, publish campaign directly if payment succeed

return_url
required
string
Example: return_url={{app_url}}

Responses

PayPal

Start PayPal Credit Transaction

Initiate a PayPal transaction for the user to add credit to his account. User will have to redirect to PayPal to authorize the transaction.

Authorizations:
httpBearer
path Parameters
amount
required
integer <int32>
Example: 20
product
required
integer <int32>
Example: 10
query Parameters
return_url
required
string
Example: return_url={{app_url}}

Responses

Stop PayPal Recurring Payments

Stop recurring payments for user.

Authorizations:
httpBearer
path Parameters
product
required
integer <int32>
Example: 10

Type of product purchased (10 = standard recharge)

Responses

Business

Create Business

Add a new business to current user. Businesses need a valid website and are used to publish campaigns.

Authorizations:
httpBearer
Request Body schema: application/x-www-form-urlencoded
name
string
website
required
string

Responses

Shopping Products Lists

Shopping products lists are a group of products from an online shop

Get Shopping Products Lists

Authorizations:
httpBearer
path Parameters
businessId
required
string

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create Shopping Products List

Authorizations:
httpBearer
path Parameters
businessId
required
string
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Update Shopping Products List

Authorizations:
httpBearer
path Parameters
businessId
required
string

Responses

Response samples

Content type
application/json
{ }

Customer Lists

List of customers associated to a Business. Can be used for re-marketing or other purposes

Set Customer List

Replace all customers in a customer list

Authorizations:
httpBearer
path Parameters
customerListId
required
string
Request Body schema: application/json
stringarray

Responses

Request samples

Content type
application/json
{
  • "customers": [
    ]
}

Add to Customer List

Add new customers to an existing customer list

Authorizations:
httpBearer
path Parameters
customerListId
required
string
Request Body schema: application/json
object

Request samples

Content type
application/json
{
  • "customers": [
    ]
}

Get all customer lists

Authorizations:
httpBearer
path Parameters
businessIdInt
required
string

Create a new customer list

Authorizations:
httpBearer
path Parameters
businessIdInt
required
string
Request Body schema: application/json
object

Request samples

Content type
application/json
{ }

audience

Update Campaign Audience

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
Request Body schema: application/json
interests
required
Array of strings
language
required
string
locations
required
Array of strings
required
Array of objects (LocationsArea)
required
Array of objects (LocationsCountry)

Responses

Request samples

Content type
application/json
{
  • "language": "1000",
  • "locations": [ ],
  • "locations_areas": [
    ],
  • "locations_countries": [
    ],
  • "interests": [ ]
}

DEPRECATED Update Campaign Geolocation

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
Request Body schema: application/json
required
Array of objects (Area)
required
Array of objects (Country)

Responses

Request samples

Content type
application/json
{
  • "areas": [
    ],
  • "countries": [
    ]
}

Update Campaign Phone

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
phone_number
required
string

phone number of the business to advertize

Responses

Link Platform Page to Campaign

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
platform_page_id
required
integer <int64>

Responses

Update Campaign Website

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
description
required
string
url
required
string

Responses

budget

Update Campaign Budget

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
daily_budget
required
integer <int32>

Responses

creation

Create a new Campaign

Authorizations:
httpBearer
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
business_id
required
integer <int32>

Give the business id you want to make a campaign for

goal_type
required
integer <int32>

Give a goal type.: WEB_TRAFFIC = 0; LEADS_CALLS = 1; ONLINE_SALES = 2; OFFLINE_VISITORS = 3; CHAT_MESSAGES = 4;

platform_code
required
integer <int32>

Set platform type: 0 = Google, 1 = Bing, 2 = Facebook

Responses

Duplicate a Campaign

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded

Responses

Update Draft Campaign Platform and Network

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
network_type
required
integer <int32>

0 = Search, 1 = Display, 2 = Shopping

platform_code
required
integer <int32>

0 = Google, 1 = Bing, 2 = Facebook

Responses

Update Draft Campaign Goal

Update campaign

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
goal
required
integer <int32>

Responses

Update Draft Campaign Platform Ad Account

Authorizations:
httpBearer
path Parameters
account
required
integer <int64>
Example: 4572760437
campaignId
required
string
Example: {{test_campaign_id}}

Responses

Publish a Draft Campaign

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}

Responses

display campaigns

Add Display Ad Template To Campaign

Post choice of initial list of keywords for user validation

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/json
Request Body schema: application/x-www-form-urlencoded
business_name
required
string
descriptions[0]
required
string
headlines[0]
required
string
headlines[1]
required
string
images[0]
required
integer <int32>

Te id of the media you would like to add to the ad template

long_headline
required
string

Responses

Get Display Ad Template For Campaign

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}

Responses

search campaigns

Update Campaign Template Ad

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
description
required
string

1 to 90 characters

title1
required
string

1 to 30 characters

title2
required
string

1 to 30 characters

title3
required
string

1 to 30 characters. Optional.

Responses

Post initial keywords proposed by user

Get initial list of keywords for user validation

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/json
Request Body schema: application/x-www-form-urlencoded
keywords[0]
required
string
keywords[1]
required
string
keywords[2]
required
string

Responses

Get keyword suggestions to validate

Get initial list of keywords for user validation

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}

Responses

Post validated keywords

Post choice of initial list of keywords for user validation

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
Request Body schema: application/json
required
Array of objects (KeywordTable)

Responses

Request samples

Content type
application/json
{
  • "keywordTable": [
    ]
}

campaign status

Update Campaign Publishing Status

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
header Parameters
Content-Type
required
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
status
required
string

status can be ENABLED or PAUSED

Responses

optimization

Get Campaign Keywords Optimization

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}

Responses

Set Campaign Keywords Optimization

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
Request Body schema: application/json
keywordsToAdd
required
Array of strings
keywordsToRemove
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "keywordsToAdd": [
    ],
  • "keywordsToRemove": [
    ]
}

Get Campaign Sentences Optimization

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Set Campaign Sentences Optimization

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
Request Body schema: application/json
required
Array of objects (Sentence)

Responses

Request samples

Content type
application/json
{
  • "sentences": [
    ]
}

campaign reports

Get Campaign Performance Report

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
query Parameters
date_end
required
integer <int32>
Example: date_end=20200206
date_start
required
integer <int32>
Example: date_start=20200204

Responses

Response samples

Content type
application/json
{
  • "report": {
    },
  • "status": "success"
}

Get Campaign Time Report

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
query Parameters
date_end
required
integer <int32>
Example: date_end=20200204
date_start
required
integer <int32>
Example: date_start=20200206

Responses

Response samples

Content type
application/json
{
  • "report": {
    },
  • "status": "success"
}

Get Campaign Gender Report

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
metric
required
string
Example: impressions
query Parameters
date_end
required
integer <int32>
Example: date_end=20200204
date_start
required
integer <int32>
Example: date_start=20200206

Responses

Response samples

Content type
application/json
{
  • "report": {
    },
  • "status": "success"
}

Get Campaign Device Report

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
metric
required
string
Example: impressions
query Parameters
date_end
required
integer <int32>
Example: date_end=20200204
date_start
required
integer <int32>
Example: date_start=20200206

Responses

Response samples

Content type
application/json
{
  • "report": {
    },
  • "status": "success"
}

Get Campaign Age Report

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
metric
required
string
Example: impressions
query Parameters
date_end
required
integer <int32>
Example: date_end=20200204
date_start
required
integer <int32>
Example: date_start=20200206

Responses

Response samples

Content type
application/json
{
  • "report": {
    },
  • "status": "success"
}

Get Keywords Report

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
query Parameters
date_end
required
integer <int32>
Example: date_end=20200204
date_start
required
integer <int32>
Example: date_start=20200206

Responses

Get Ads Report

Authorizations:
httpBearer
path Parameters
campaignId
required
string
Example: {{test_campaign_id}}
query Parameters
date_end
required
integer <int32>
Example: date_end=20200204
date_start
required
integer <int32>
Example: date_start=20200206

Responses

account reports

suggestions

Suggestions are actions that are recommended to a given user in order to improve marketing results.

Get Suggestions

Get list of suggestions for the user in order to improve his campaigns or setup his account.

Authorizations:
httpBearer

Responses

Skip User Suggestion

Skip a suggestion made to this user.

Authorizations:
httpBearer
path Parameters
suggestionId
required
integer <int32>
Example: 121

Responses

dashboard

Get Dashboard Metrics

Get list of core metrics for the user. These metrics are aggregated among all advertising platforms.

Authorizations:
httpBearer

Responses

Get Latest Blog Articles

Get latest blog articles about digital marketing from Instaon.

Authorizations:
httpBearer

Responses