Social Report API

The Social Report SDKs gets your app connected quickly and easily, so you can focus on creating an experience. Social Report exposes its data via an Application Programming Interface (API), so developers can interact in a programmatic way with the Social Report website. This document is the official reference for that functionality.

The purpose of this API is to allow anyone to build applications that interact with social networks using a unified API without having to worry about integrating with each network separately.

The current API version is 1.3 Authentication

All requests have to be signed using an api key that. Simply add "api_key" request header when making all requests. For testing purposes you can also pass "api_key" as a parameter. This is not a recommended option however for obvious security reasons.

Obtain API Key

If you have an existing Social Report account you can find your API in My Account > API Access section. If you don't have an account - you can create it here. Rate limits

API calls are limited to 500 calls per hour. You may request higher API quota by contact our support. To monitor your API rate limits refer to response headers: X-Rate-Limit-Limit (total per hour limit) and X-Rate-Limit-Remaining (remaining calls this hour).

Create an Account

List Projects

Get a list of all projects belonging to the owner of the API key.

Parameters

  • user: user identifier (optional)

Output
                                                    
[
    {
        "id": "56783",
        "name": "SocialReport.com",
        "user": 5,
        "timezone": "America/New_York",
        "created": "02/08/2012 18:30 -0500",
    },
    {
        "id": "76897",
        "name": "WebAlgorithm LLC"
        "user": 5,
        "timezone": "America/New_York",
        "created": "05/28/2014 12:13 -0500",
    },
    {
        "id": "45765",
        "name": "ConcreteMedia Inc",
        "user": 7,
        "timezone": "America/Santiago",
        "created": "05/28/2014 12:13 -0500",
    }

]
                                                    
                                                

Create a new project

Project is a way of grouping a set of social properties. Typically project represents a client, a business or a marketing initiative.

Parameters

  • name: project name
  • user: project owner user identifier (optional).
  • timezone: for example America/New_York.
    List of available timezones:

    (UTC-10:00) America/Adak
    (UTC-10:00) America/Atka
    (UTC-09:00) America/Anchorage
    (UTC-09:00) America/Juneau
    (UTC-09:00) America/Metlakatla
    (UTC-09:00) America/Nome
    (UTC-09:00) America/Sitka
    (UTC-09:00) America/Yakutat
    (UTC-08:00) America/Dawson
    (UTC-08:00) America/Ensenada
    (UTC-08:00) America/Los_Angeles
    (UTC-08:00) America/Santa_Isabel
    (UTC-08:00) America/Tijuana
    (UTC-08:00) America/Vancouver
    (UTC-08:00) America/Whitehorse
    (UTC-07:00) America/Boise
    (UTC-07:00) America/Cambridge_Bay
    (UTC-07:00) America/Chihuahua
    (UTC-07:00) America/Denver
    (UTC-07:00) America/Edmonton
    (UTC-07:00) America/Inuvik
    (UTC-07:00) America/Mazatlan
    (UTC-07:00) America/Ojinaga
    (UTC-07:00) America/Shiprock
    (UTC-07:00) America/Yellowknife
    (UTC-06:00) America/Bahia_Banderas
    (UTC-06:00) America/Chicago
    (UTC-06:00) America/Indiana/Knox
    (UTC-06:00) America/Indiana/Tell_City
    (UTC-06:00) America/Knox_IN
    (UTC-06:00) America/Matamoros
    (UTC-06:00) America/Menominee
    (UTC-06:00) America/Merida
    (UTC-06:00) America/Mexico_City
    (UTC-06:00) America/Monterrey
    (UTC-06:00) America/North_Dakota/Beulah
    (UTC-06:00) America/North_Dakota/Center
    (UTC-06:00) America/North_Dakota/New_Salem
    (UTC-06:00) America/Rainy_River
    (UTC-06:00) America/Rankin_Inlet
    (UTC-06:00) America/Resolute
    (UTC-06:00) America/Winnipeg
    (UTC-05:00) America/Detroit
    (UTC-05:00) America/Fort_Wayne
    (UTC-05:00) America/Havana
    (UTC-05:00) America/Indiana/Indianapolis
    (UTC-05:00) America/Indiana/Marengo
    (UTC-05:00) America/Indiana/Petersburg
    (UTC-05:00) America/Indiana/Vevay
    (UTC-05:00) America/Indiana/Vincennes
    (UTC-05:00) America/Indiana/Winamac
    (UTC-05:00) America/Indianapolis
    (UTC-05:00) America/Iqaluit
    (UTC-05:00) America/Kentucky/Louisville
    (UTC-05:00) America/Kentucky/Monticello
    (UTC-05:00) America/Louisville
    (UTC-05:00) America/Montreal
    (UTC-05:00) America/Nassau
    (UTC-05:00) America/New_York
    (UTC-05:00) America/Nipigon
    (UTC-05:00) America/Pangnirtung
    (UTC-05:00) America/Thunder_Bay
    (UTC-05:00) America/Toronto
    (UTC-04:00) America/Asuncion
    (UTC-04:00) America/Campo_Grande
    (UTC-04:00) America/Cuiaba
    (UTC-04:00) America/Glace_Bay
    (UTC-04:00) America/Goose_Bay
    (UTC-04:00) America/Halifax
    (UTC-04:00) America/Moncton
    (UTC-04:00) America/Thule
    (UTC-04:00) Atlantic/Bermuda
    (UTC-03:-30) America/St_Johns
    (UTC-03:00) America/Godthab
    (UTC-03:00) America/Miquelon
    (UTC-03:00) America/Sao_Paulo
    (UTC-01:00) America/Scoresbysund
    (UTC-01:00) Atlantic/Azores
    (UTC+00:00) Africa/Casablanca
    (UTC+00:00) Africa/El_Aaiun
    (UTC+00:00) Atlantic/Canary
    (UTC+00:00) Atlantic/Faeroe
    (UTC+00:00) Atlantic/Faroe
    (UTC+00:00) Atlantic/Madeira
    (UTC+00:00) Europe/Belfast
    (UTC+00:00) Europe/Dublin
    (UTC+00:00) Europe/Guernsey
    (UTC+00:00) Europe/Isle_of_Man
    (UTC+00:00) Europe/Jersey
    (UTC+00:00) Europe/Lisbon
    (UTC+00:00) Europe/London
    (UTC+01:00) Africa/Ceuta
    (UTC+01:00) Africa/Windhoek
    (UTC+01:00) Atlantic/Jan_Mayen
    (UTC+01:00) Europe/Amsterdam
    (UTC+01:00) Europe/Andorra
    (UTC+01:00) Europe/Belgrade
    (UTC+01:00) Europe/Berlin
    (UTC+01:00) Europe/Bratislava
    (UTC+01:00) Europe/Brussels
    (UTC+01:00) Europe/Budapest
    (UTC+01:00) Europe/Busingen
    (UTC+01:00) Europe/Copenhagen
    (UTC+01:00) Europe/Gibraltar
    (UTC+01:00) Europe/Ljubljana
    (UTC+01:00) Europe/Luxembourg
    (UTC+01:00) Europe/Madrid
    (UTC+01:00) Europe/Malta
    (UTC+01:00) Europe/Monaco
    (UTC+01:00) Europe/Oslo
    (UTC+01:00) Europe/Paris
    (UTC+01:00) Europe/Podgorica
    (UTC+01:00) Europe/Prague
    (UTC+01:00) Europe/Rome
    (UTC+01:00) Europe/San_Marino
    (UTC+01:00) Europe/Sarajevo
    (UTC+01:00) Europe/Skopje
    (UTC+01:00) Europe/Stockholm
    (UTC+01:00) Europe/Tirane
    (UTC+01:00) Europe/Vaduz
    (UTC+01:00) Europe/Vatican
    (UTC+01:00) Europe/Vienna
    (UTC+01:00) Europe/Warsaw
    (UTC+01:00) Europe/Zagreb
    (UTC+01:00) Europe/Zurich
    (UTC+02:00) Africa/Johannesburg
    (UTC+02:00) Asia/Amman
    (UTC+02:00) Asia/Beirut
    (UTC+02:00) Asia/Damascus
    (UTC+02:00) Asia/Gaza
    (UTC+02:00) Asia/Hebron
    (UTC+02:00) Asia/Istanbul
    (UTC+02:00) Asia/Jerusalem
    (UTC+02:00) Asia/Nicosia
    (UTC+02:00) Asia/Tel_Aviv
    (UTC+02:00) Europe/Athens
    (UTC+02:00) Europe/Bucharest
    (UTC+02:00) Europe/Chisinau
    (UTC+02:00) Europe/Helsinki
    (UTC+02:00) Europe/Istanbul
    (UTC+02:00) Europe/Kaliningrad
    (UTC+02:00) Europe/Kiev
    (UTC+02:00) Europe/Mariehamn
    (UTC+02:00) Europe/Nicosia
    (UTC+02:00) Europe/Riga
    (UTC+02:00) Europe/Sofia
    (UTC+02:00) Europe/Tallinn
    (UTC+02:00) Europe/Tiraspol
    (UTC+02:00) Europe/Uzhgorod
    (UTC+02:00) Europe/Vilnius
    (UTC+02:00) Europe/Zaporozhye
    (UTC+03:00) Europe/Minsk
    (UTC+03:00) Europe/Moscow
    (UTC+03:00) Europe/Volgograd
    (UTC+03:30) Asia/Tehran
    (UTC+04:00) Asia/Baku
    (UTC+04:00) Asia/Dubai
    (UTC+04:00) Asia/Tbilisi
    (UTC+04:00) Asia/Yerevan
    (UTC+04:00) Europe/Samara
    (UTC+04:00) Indian/Mahe
    (UTC+04:00) Indian/Mauritius
    (UTC+04:00) Indian/Reunion
    (UTC+04:30) Asia/Kabul
    (UTC+05:00) Asia/Aqtau
    (UTC+05:00) Asia/Ashgabat
    (UTC+05:00) Asia/Dushanbe
    (UTC+05:00) Asia/Karachi
    (UTC+05:00) Asia/Tashkent
    (UTC+05:00) Asia/Yekaterinburg
    (UTC+05:30) Asia/Calcutta
    (UTC+05:45) Asia/Kathmandu
    (UTC+06:00) Asia/Almaty
    (UTC+06:00) Asia/Bishkek
    (UTC+06:00) Asia/Dacca
    (UTC+06:00) Asia/Novosibirsk
    (UTC+06:00) Asia/Omsk
    (UTC+06:00) Asia/Thimbu
    (UTC+07:00) Asia/Bangkok
    (UTC+07:00) Asia/Ho_Chi_Minh
    (UTC+07:00) Asia/Hovd
    (UTC+07:00) Asia/Jakarta
    (UTC+07:00) Asia/Pontianak
    (UTC+07:00) Asia/Saigon
    (UTC+08:00) Asia/Brunei
    (UTC+08:00) Asia/Choibalsan
    (UTC+08:00) Asia/Harbin
    (UTC+08:00) Asia/Hong_Kong
    (UTC+08:00) Asia/Irkutsk
    (UTC+08:00) Asia/Kuala_Lumpur
    (UTC+08:00) Asia/Manila
    (UTC+08:00) Asia/Shanghai
    (UTC+08:00) Asia/Singapore
    (UTC+08:00) Asia/Ulaanbaatar
    (UTC+08:00) Asia/Ulan_Bator
    (UTC+09:00) Asia/Seoul
    (UTC+09:00) Asia/Tokyo
    (UTC+09:00) Asia/Yakutsk
    (UTC+09:30) Australia/Adelaide
    (UTC+09:30) Australia/Broken_Hill
    (UTC+09:30) Australia/South
    (UTC+09:30) Australia/Yancowinna
    (UTC+10:00) Asia/Vladivostok
    (UTC+10:00) Australia/ACT
    (UTC+10:00) Australia/Canberra
    (UTC+10:00) Australia/Currie
    (UTC+10:00) Australia/Hobart
    (UTC+10:00) Australia/Melbourne
    (UTC+10:00) Australia/NSW
    (UTC+10:00) Australia/Sydney
    (UTC+10:00) Australia/Tasmania
    (UTC+10:00) Australia/Victoria
    (UTC+10:30) Australia/LHI
    (UTC+10:30) Australia/Lord_Howe
    (UTC+12:00) Asia/Kamchatka
    (UTC+12:00) Pacific/Auckland
    (UTC+12:00) Pacific/Fiji
    (UTC+12:45) Pacific/Chatham
    (UTC+13:00) Pacific/Apia
    (UTC+13:00) Pacific/Enderbury
    (UTC+13:00) Pacific/Fakaofo
    (UTC+13:00) Pacific/Tongatapu
    (UTC+14:00) Pacific/Kiritimati

Output
                                                    
[
    {
        "id": "56783"
    }
]
                            			            
                                                

Delete an existing project

Delete a project and all related accounts, publications and users.

Parameters

  • project: project identifier

Output
                                                    
[
    {
        "status": "ok"
    }
]
                                                    
                                                

Project Summary

Get a project analytical summary. More detailed reporting is available in the Export endpoint.

Parameters

  • project: project identifier

Output

 {
    "project": 56783,
    "name": "SocialReport.com",
    "summary": {
        "date": "20120502",
        "accounts": 25,
        "networks": 19,
        "friends": 2107,
        "mostPopulaNetwork": "LinkedIn",
        "mostPopulaNetworkShare": 0.0002,
        "mostPopularLanguages": "English,Spanish,Italian",
        "membershipGrowth": 0.00128,
        "activityGrowth": -0.00729,
        "activeCountries": "United States,Italy,India",
        "engagement": 0.601,
        "engagementGrowth": 0.001,
        "dailyClicks": 0.011,
        "averageAge": 35,
        "countries": 47,
        "numberOfLanguages": 37,
        "mostActiveCities": "New York,Brooklyn,Jersey City",
        "mostActiveStates": "Connecticut,Illinois"
    }  
  }                          		
                            			

Project Users

Get a list of users with access to specified project.

Parameters

  • project: project identifier

Output

[
    {
        "id": "11833",
        "lastName": "johnson",
        "added": "20111031",
        "lastLogin": "20150830",
        "email": "user1@company.com",
        "active": "yes",
        "firstName": "roger",
        "deleted": "no",
        "photo": "User photo as base64"
    },
    {
        "id": "11317",
        "lastName": "robinson",
        "added": "20111031",
        "created": "20100901",
        "lastLogin": "20150904",
        "email": "user2@company.com",
        "active": "no",
        "firstName": "peter",
        "deleted": "no",
        "photo": "User photo as base64"
    }
]
                            			

Add User

Add user to the project. Each user gets a very specific set of permissions.

Parameters

  • project: project identifier
  • email: user email address
  • firstName: user's first name (only required for first time user setup)
  • lastName: user's last name (only required for first time user setup)
  • company: user's company (only required for first time user setup)
  • username: user's username (only required for first time user setup)
  • password: user's password (only required for first time user setup)
  • active: can user get access to project (optional) yes - user can access to project (default), no - user can't access to project
  • currencyCode: currency code (optional)
  • timezone: timezone code (optional)
  • accounts: can user get access to accounts. Available values - yes or no
  • addAccount: can user add new account to project. Available values - yes or no
  • agents: can user get access to keyword agents. Available values - yes or no
  • campaigns: can user get access to campaigns. Available values - yes or no
  • publish: can user publish. Available values - no_approve or requires_approve
  • publication_review: can user review publications of others. Available values - yes or no
  • contacts: can user get access to address book. Available values - yes or no
  • export: can user get access to data export. Available values - yes or no
  • goals: can user get access to goals. Available values - yes or no
  • reports: can user get access to reports. Available values - yes or no
  • api: can user execute api requests. Available values - yes or no
  • notifications: can user get notifications. Available values - yes or no
  • automations: can manage automations. Available values - yes or no
  • users: can manager users. Available values - yes or no

Output
  • id: unique user identifier.

[
    {
        "id": "6543"
    }
]
                                                

Remove User

Remove user from the project. This strips the user from all access to specified project. This does not deactivate the user.

Parameters

  • project: project identifier
  • user: user identifier.

Output

[
    {
       "status": "ok"
    }
]
                            			

Modify User

Make changes to a project user - profile data and permissions.

Parameters

  • project: project identifier
  • user: user identifier
  • active: can user get access to project (optional) yes - user can access to project (default), no - user can't access to project
  • currencyCode: currency code
  • timezone: timezone code
  • accounts: can user get access to accounts. Available values - yes or no
  • addAccount: can user add new account to project. Available values - yes or no
  • agents: can user get access to keyword agents. Available values - yes or no
  • campaigns: can user get access to campaigns. Available values - yes or no
  • contacts: can user get access to address book. Available values - yes or no
  • export: can user get access to data export. Available values - yes or no
  • goals: can user get access to goals. Available values - yes or no
  • reports: can user get access to reports. Available values - yes or no
  • api: can user execute api requests. Available values - yes or no
  • notifications: can user get notifications. Available values - yes or no
  • publish: how user can create publications. Available values - no_approve or requires_approve
  • publicationApprove: can user approve publications. Available values - yes or no

Output

  • id: unique user identifier.


[
    {
        "id": "5221"
    }
]
                                                

Add Account

Add an existing social account to project

Parameters

  • account: account identifier
  • project: project identifier

Output

[
    {
        "status": "ok"
    }
]
                            			

Remove Account

Remove account from project

Parameters

  • account: account identifier
  • project: project identifier

Output

[
    {
        "status": "ok"
    }
]
                                                

Account List

Get a list of all accounts for a specified project. Accounts are the actual social properties: twitter profiles, facebook pages, etc.

Parameters

  • project: project identifier

Output

  • id: unique account identifier.
  • name: account name.
  • nick: account nick name.
  • type: account network type.
  • active: activity indicator (true if active, false if paused).
  • image: account icon.
  • profileUrl: link to profile.
  • access: true if access is ok, false is access is lost.
  • publish: true if account can be published to.
  • boards: boards list. Available only for Pinterest account with access key


[
    {
        "id": 123181,
        "name": "Social Report",
        "active": true,
        "type": "Active Campaign Account",
        "image": "http://socialreport.com/images/icons/actvecmp-24x24.png",
        "networkIcon": "http://socialreport.com/images/icons/activecampaign-32x32.png",
        "access": true,
        "publish": false
    },
    {
        "id": 45678,
        "name": "SocialReport.com",
        "active": false,
        "type": "Facebook Page",
        "image": "https://graph.facebook.com/341093549238622/picture",
        "networkIcon": "http://socialreport.com/images/icons/facebook-32x32.png",
        "access": false,
        "publish": false
    },
    {
        "id": "62821",
        "name": "SocialReport.com",
        "active": true,
        "type": "LinkedIn Company",
        "image": "https://media.licdn.com/mpr/mpr/p/1/00/471f.png",
        "networkIcon": "http://socialreport.com/images/icons/linkedin-32x32.png",
        "access": true,
        "publish": true
    },
    {
        "id": "63459",
        "name": "SocialReport.com",
        "active": true,
        "type": "Pinterest Profile",
        "image": "https://s-media-cache-ak0.pinimg.com/avatars/socialreport_1369751408_140.jpg",
        "networkIcon": "http://socialreport.com/images/icons/pinterest-32x32.png",
        "access": true,
        "publish": true,
        "boards": [
                   {
                   "id":"4575449013423",
                   "name":"Reports",
                   "image": "https://s-media-cache-ak0.pinimg.com/216x146/cd/7a/74/cd7a74f36849da482ffe1c267aa486c8.jpg",
                   "url": "https://www.pinterest.com/socialreport/reports/"
                   },
                   {
                   "id":"4744645556642",
                   "name":"Social",
                   "image": "https://s-media-cache-ak0.pinimg.com/216x146/7a/fb/c6/7afbc60e46da19838aa3ef4033fa040c.jpg",
                   "url": "https://www.pinterest.com/manobyte/social/"
                   }
                  ]
    }
]
                            			

Account Create

Create a new social account. Don't forget to add your account to a project.

Parameters

  • uid: unique network account identifier
  • type: network type. Supported types - facebook, twitter, bitly, googl, yelp, wordpress, linkedin, youtube, foursquare, googleanalytics, vimeo, meetup, ebay, googleplus, shopify, tumblr, clicky, addthis, blogger, reddit, instagram, pinterest
  • name: account name
  • nickname: account nick name
  • firstName: user first name
  • lastName: user last name
  • username: account user name
  • accessKey: access key
  • accessSecret: access secret
  • profileUrl: profile url

Output

  • id: unique account identifier.


[
    {
        "id": "326"
    }
]
                                                

Modify Account

Update an existing social account

Parameters

  • account: account identifier
  • name: account name
  • nickname: account nick name
  • accessKey: access key
  • accessSecret: access secret
  • type: user type, used in body.class and allows css/js customizations
  • accessKey2: additional access key. Required only for google accounts
  • accessSecret2: additional access secret. Required only for google accounts
  • profileUrl: profile url

Output

  • id: unique account identifier.


[
    {
        "id": "326"
    }
]
                            			

Delete Account

Delete an existing account. If account is no longer associated with any project - no further analytics gathering will occur for this account.

Parameters

  • account: account identifier

Output

[
    {
        "status": "ok"
    }
]
                                                

Create a new publication

Create a new publication or update an existing publication. This method only accepts "POST" requests.

Parameters

  • project: project identifier
  • campaign: campaign identifier (optional)
  • name: publication name required but only used to publish to Blogger, LinkedIn Groups and WordPress
  • accounts: JSON array of accounts (i.e. [10031,275])
  • customization: JSON object of publication customization (i.e. {"10031":{"shortener":true|false, "pinterest_board_id":"2328743430"}}). pinterest_board_id only to publish to Pinterest
  • schedule: JSON array of schedule objects see below example (interval_type - day, hour or minute)
  • image: if you are including a media (image or video), specify its url here
  • mediaType: type of media (image or video). Image by default
  • roi: return on investment configuration, see below example
  • targeting: specialized publication targeting, see below example


{
    "project": 1,
    "name": "My First Publication",
    "accounts": [10031,275],
    "customization": {"10031":{"shortener":true,"pinterest_board_id":"2328743430"}},
    "schedule":  {
        "20151012 11:02": {
            "message": "message 1 text http://www.socialreport.com",
            "twitterMessage": "twitter message 1 #smm",
            "image": "http://www.socialreport.com/includes/logo.png",
            "link": {
               "url": "URL of a link to attach to the post.",
               "title": "link title",
               "description": "link description"
            },
            "repeat": {
               "interval_type": "day",
               "interval_value":3,
               "total_posts":4
            }
        },
        "20151015 11:35": {
            "message": "message 2 text http://www.socialreport.com",
            "twitterMessage": "twitter message 2 #smm",
            "publishAsImage": "true"
        }
    },
    "roi": {
        "campaignCost": 15,
        "conversionValue": 10,
        "conversionCost": 1
    },
    "call_action": {
        "type": "LEARN_MORE",
        "title": "Sample Call To Action Title"
        },
    "targeting": {
        "geo": {
            "longitude": 90,
            "latitude": 80
        },
        "countries": ["ES","US"],
        "age": {
            "from": 14,
            "to": 35
        },
        "gender": ["male","female"],
        "relationshipStatus": ["married","single"]
    }
}

                            			

 

Output

[
    {
        "id":"5567532"
    }
]
                                                

List Publications

Get a list of all publications for a project. Campaigns are publications into mutliple social channels with ability to track clicks and conversions.

Parameters

  • project: project identifier

Output

  • id: unique campaign identifier.
  • name: campaign name.
  • created_utc: campaign created time
  • suspened_utc: campaign suspened time
  • status: current campaign status (active, suspened).
  • rss: RSS Syndication url


[
    {
        "name": "Videos",
        "id": "2629",
        "created_utc": "1467133962000",
        "status": "active"
    }, {
        "rss": "http://www.computerweekly.com/rss/All-Computer-Weekly-content.xml",
        "name": "ComputerWeely RSS",
        "id": "1940",
        "created_utc": "1409814729000",
        "status": "active"
    }
]
                                                

Publication Detail

Retrieve complete performance report of a particular publication as well as all scheduled posts.

Parameters

  • id: publication identifier

Output

{
    "id": 1326,
    "project": 111117,
    "name": "Your publication title",
    "status": "published",
    "created_utc": 1358513008000,
    "approved": "yes"
    "schedule": {
        "20140118 15 43 +0300": {
        "id": 1397,
        "date_utc": 1358513008000,
        "message": "Your publication message will go here",
        "link": {
            "url": "published link",
            "title": "link title",
            "description": "link description"
        }
    },
    "accounts": [
        277,
        259,
        273
    ],
    "publications": [
        {
            "account": 273,
            "date_utc": 1367478322000,
            "schedule_id": 1397,
            "post_id": "iEgcb1QP9L1EmB_9pKq5fuXO1OCJ53dCZR9Sjeko9Cc"
        },
        {
            "account": 277,
            "date_utc": 1367478315000,
            "schedule_id": 1397,
            "post_id": "371193063000486",
            "post_url": "http://www.facebook.com/permali..."
        },
        {
            "account": 259,
            "date_utc": 1367478309000,
            "schedule_id": 1397,
            "post_id": "UNIU-149754396-5735619739678437376-SHARE",
            "post_url": "http://www.linkedin.com/update...."
        },
        {
            "account": 259,
            "date_utc": 1367477876000,
            "schedule_id": 1397
        },
        {
            "account": 10031,
            "date_utc": 1367477876000,
            "schedule_id": 1397,
            "post_id": "389746597783209",
            "post_url": "http://www.facebook.com/302294..."
        }

    ],
    "result": {
        "clicks": 11,
        "conversions": 4
    }
}
                            			

Search Agent List

Get a list of all search agents for a project. Search agents allow you to search social space for keywords that interest you.

Parameters

  • project: project identifier

Output

  • id: unique keyword agent identifier.
  • name: agent name.
  • initialized: indicates if initial search has been completed.


[
    {
        "id": "65299",
        "name": "social media",
        "initialized": "yes"
    },
    {
        "id": "54321",
        "name": "social report",
        "initialized": "yes"
    }
]
                                                

Create New Agent

Create a new keyword agent.

Parameters

  • name: agent name
  • scope: search scope. network - only in registered accounts, global - everywhere
  • selection: search criteria. and - all keywords, or - any keywords
  • keywords: keywords list with ~~~ delimiter
  • project: project identifier

Output

  • id: unique keyword agent identifier.


[
    {
        "id": "326"
    }
]
                            			

Agent Detail

Get agent details.

Parameters

  • agent: agent identifier

Output

  • Agent information


{
    "id": 176,
    "name": "American candidates",
    "scope": "global",
    "selection": "or",
    "initialized": true,
    "keywords": [
       {"name": "trump", "exclude": false},
       {"name": "sanders", "exclude": false},
       {"name": "clinton", "exclude": false},
       {"name": "cruz", "exclude": false}
    ],
    "recipiends": [{"name": "John Smith", "email": "test@gmail.com"}]
}
                                                

Modify Search Agent

Modify an existing keyword agent.

Parameters

  • agent: agent identifier
  • name: agent name
  • scope: search scope. network - only in registered accounts, global - everywhere
  • selection: search criteria. and - all keywords, or - any keywords
  • keywords: keywords list with ~~~ delimiter

Output

  • id: unique agent identifier.


[
    {
       "id": "326"
    }
]
                                                

Delete Search Agent

Delete an existing keyword agent

Parameters

  • agent: agent identifier

Output

[
    {
        "status": "ok"
    }
]
                            			

Add Customer

Register new customers. Note that this API must be used over SSL and only accepts "POST" request.

Parameters

  • user.firstName: customer first name
  • user.lastName: customer last name
  • user.email: customer email
  • user.username: customer username
  • user.password: customer password
  • packageOption: plan. 1 - "Starter", 2 - "Business", 3 - "Agency", 4 - "Ultimate"
  • billing.firstName: billing first name
  • billing.lastName: billing last name
  • billing.address1: billing street address
  • billing.city: billing city
  • billingCountry: two letter custom code
  • billing.postCode: billing post code
  • payment.cardholderNamecardhold name
  • payment.numbercredit card number
  • payment.cvv2card's cvv code
  • expirationMonthcard's expiration month: January, Feburary, etc
  • expirationYearcard's expiration year: 2012, 2014, etc

Output

[
    {
        "status": "ok",
        "user_id": "595959532"
    }
]
                                                

Delete Search Agent

Modify state an existing keyword agent.

Parameters

  • agent: agent identifier
  • status: agent state (yes - activate agent, no - suspend agent)

Output

[
    {
        "status": "ok"
    }
]
                                                

Add Customer

Register new customers. Note that this API must be used over SSL and only accepts "POST" request.

Parameters

  • user.firstName: customer first name
  • user.lastName: customer last name
  • user.email: customer email
  • user.username: customer username
  • user.password: customer password
  • packageOption: plan. 1 - "Starter", 2 - "Business", 3 - "Agency", 4 - "Ultimate"
  • billing.firstName: billing first name
  • billing.lastName: billing last name
  • billing.address1: billing street address
  • billing.city: billing city
  • billingCountry: two letter custom code
  • billing.postCode: billing post code
  • payment.cardholderNamecardhold name
  • payment.numbercredit card number
  • payment.cvv2card's cvv code
  • expirationMonthcard's expiration month: January, Feburary, etc
  • expirationYearcard's expiration year: 2012, 2014, etc

Output

[
    {
        "status": "ok",
        "user_id": "595959532"
    }
]
                                                

List Customers

Retrieve your customers. If you are an affiliate and/or have an integrated registration process - this method will allow you to retrieve all of your customers and their payment details.

Output

[
    {
        "id": "877272",
        "enabled": "no",
        "firstName": "Brian",
        "lastName": "Gordon",
        "subscription": {
            "plan": "Professional",
            "balance": "0",
            "expected": "0",
            "monthly": "39",
            "nextPaymentDate": "20111210",
            "payments": []
        },
        "created": "20111110"
    },
    {
        "id": "3311111",
        "enabled": "yes",
        "firstName": "Jason",
        "lastName": "Smith",
        "subscription": {
            "plan": "Professional",
            "balance": "39",
            "expected": "78",
            "monthly": "39",
            "nextPaymentDate": "20111210",
            "payments": [
                {
                    "date": "20110910",
                    "amount": "39",
                    "status": "ok"
                },
                {
                    "date": "20111010",
                    "amount": "39",
                    "status": "failed"
                }
            ]
        },
        "created": "20111109"
    }
]

                            			

User Details

Get user details

Parameters

  • id: user's identifier

Output

[
    {
        "user":
        {
            "user_id": 43309756,
            "firstName": "John",
            "lastName": "Smith",
            "email": "john@gmail.com",
            "packageOption": 4,
            "username": "johnSmith",
            "company": "IBM",
            "defaultLanguage": "en",
            "timezoneId": "Europe/London",
            "currencyCode": "USD",
            "photo": "User photo as base64",
            "customization":
            {
                "api_key": "jghrkgfg4564r4fwkeff",
                "name": "SocialCompany",
                "domain": "socialcompany.com",
                "logoutLink": "socialcompany.com/logout.html",
                "language": "en",
                "email": "johnsmith@socialcompany.com",
                "affiliateCode": "social",
                "showAskUs": "yes",
                "showNews": "yes",
                "showUserProfile": "no",
                "showNotifications": "no",
                "logo": "socialcompany.jpg",
                "favicon": "socialcompany.ico",
                "active": "yes",
                "whiteLabel": "yes"
            }
        },
        "projects": {
                "owned": [
                    {
                        "id": 4645763,
                        "name": "Facebook and Twitter"
                    },
                    {
                        "id": 4643444,
                        "name": "LinkedIn and Xing"
                    }
            ],
                "accessible": [
                    {
                        "id": 6765554,
                        "name": "Auto on Facebook",
                        "permissions": {
                        "accounts": "yes",
                        "addAccount": "no",
                        "agents": "no",
                        "campaigns": "yes",
                        "contacts": "no",
                        "export": "yes",
                        "goals": "yes",
                        "reports": "yes",
                        "api": "no",
                        "notifications": "yes"
                    }
                }
            ]
        }
    }
]

                                                

Create User

Create a new user

Parameters

  • user.firstName: user's first name
  • user.lastName: user's last name
  • user.email: user's email
  • user.username: user's username
  • user.password: user's password
  • user.defaultLanguage: user's default language code (optional)
  • user.timezoneId: user's timezone identifier (optional)
  • user.currencyCode: user's currency code (optional)
  • user.type: user type, used in body.class and allows css/js customizations (optional)
  • packageOption: reseller's package option

Output

[
    {
        "status": "ok",
        "user_id":"1232245"
    }
]
                            			

Update User

Update an existing user.

Parameters

  • id: user's identifier
  • firstName: user's first name (optional)
  • lastName: user's last name (optional)
  • email: user's email (optional)
  • defaultLanguage: dashboard language code (optional)
  • timezoneId: user's timezone identifier (optional)
  • currencyCode: user's currency code (optional)
  • password: user's password (optional)
  • enabled: user's status. on - user can access to dashboard, off - user can't access to dashboard

Output

[
    {
        "status": "ok",
        "user_id":"1232245"
    }
]
                                                

Authentication

Authenticates the user, generates single sign-on token. You can then use generate token direct your user to

https://[www.socialreport.com or white labeled domain]/sso.htm?token=generated_token

which will seamlessly log the user into his or her Social Report account. Note that if you are using a white labeled domain - you can substitute www.socialreport.com with your domain. Generated tokens are only valid for 30 seconds once generated.

Parameters

  • user_id: user identifier

Output

[
    {
        "token": "0hokth7bh7rbbmravhabcam4uo27gx9cec46"
    }
]
                            			

Export

All data available within Social Report can be exported. Exports are delivered in a ZIP archive containing CSV files for each metric you are exporting. If you need coding samples of how to process the results - just ask our support team. Note that export results are cached for 1 hour. Also note that you can easily test exports right from the dashboard by clicking on 'Export Data'.

Example
<?php

// this example shows how to export account data.

$accountId REPLACE_WITH_SYSTEM_ACCOUNT_ID;
$apiKey "REPLACE_WITH_YOUR_API_KEY"// under my account > api

$url "https://api.socialreport.com/export.svc?account=".$accountId."&export_type=account&activity=1&from=20160601&to=20160628&api_key=".$apiKey;
$zipFile "activity.zip";
$zipResource fopen($zipFile"w");


// Step 1: Make the request, save file
$ch curl_init();
curl_setopt($chCURLOPT_URL$url);
curl_setopt($chCURLOPT_FILE$zipResource);
$page curl_exec($ch);
if(!
$page) {
 echo 
"Error :- ".curl_error($ch);
}
curl_close($ch);

// Step 2: Unzip the file
$zip = new ZipArchive;
if(
$zip->open($zipFile) != "true"){
 echo 
"Error :- Unable to open the Zip File";

/* Extract Zip File */
$zip->extractTo(".");
$zip->close();

// Step 3: Parse the desired CSV
$csv array_map('str_getcsv'file('activity_'.$accountId.'.csv'));

$row 0;

foreach (
$csv as &$row) {

    if (
$row++ > 0) {
        
// to find all column indexes - please download these export manually first (either user api or using the dashboard)
        
$accountId $row[0];
        
$date $row[4];
    }
}

?>

Example Requests
Export Twitter account activity, followers, and statues:
https://api.socialreport.com/export.svc?export_type=account&account=111&activity=1&followers=1&twitter_status=1

Export Instagram account activity, followers, media and comments:
https://api.socialreport.com/export.svc?export_type=account&account=111&activity=1&instagram_followers=1&instagram_media=1&instagram_comments=1

Export Search agent results:
https://api.socialreport.com/export.svc?export_type=agent&agent=5

Export Content Group (publications):
https://api.socialreport.com/export.svc?export_type=campaign&campaign=7

Parameters

  • export_type: supported types: account, campaign, agent, address-book
  • account: account identifier (required if export_type=account)
  • campaign: campaign identifier (required if export_type=campaign)
  • project: account identifier (required if export_type=address-book or conversation)
  • agent: agent identifier (required if export_type=agent or conversation)
  • accounts: comma delimited list of account identifiers (required if export_type=conversation)
  • from: from date offset (i.e. 20150925)
  • to: to date offset (i.e. 20151025). note that maximum allowed date range is 30 days.

Metrics
Optional metric parameters to limit the amount of data returned (i.e. ?activity=1&countries=1 will only return general activity data and geo)

  • activity: export activity.
  • countries: export geo by countries.
  • cities: export geo by cities.
  • interests: export interests.
  • followers: export followers. Twitter only
  • following: export following. Twitter only
  • twitter_list: export lists. Twitter only
  • twitter_reference: export references. Twitter only
  • twitter_status: export twitter statuses. Twitter only
  • twitter_klout: export klout results. Twitter only
  • friends: export friends. Facebook, Meetup, Linkedin, MySpace, Vimeo, Yelp, YouTube only
  • job_titles: export jobs titles. Facebook, Linkedin only
  • school: export schools. Facebook, Linkedin only
  • posts: export posts. Facebook only
  • foursquare_checkins: export checkins. Foursquare only
  • foursquare_tips: export tips. Foursquare only
  • foursquare_users: export users. Foursquare only
  • linkedin_jobs: export jobs. Linkedin only
  • subscribers: export subscribers. YouTube only
  • video: export videos. YouTube only
  • video_activity: export activity by video. YouTube only
  • video_demographic: export demographic by video. YouTube only
  • video_geo: export geo by video. YouTube only
  • video_referrers: export referrers by video. YouTube only
  • hostname: export hostnames. GoogleAnalytics only
  • social: export social performance. GoogleAnalytics only
  • keyword_activity: export activity by keywords. GoogleAnalytics only
  • geo: export geo. GoogleAnalytics, Bitly only
  • link_activity: export activity by links. Bitly only
  • geo_activity: export activity by geo. Bitly only
  • referral_activity: export activity by referrerak. Bitly only
  • browsers: export data by browsers. Goo.ly only
  • clicks: export data by clicks. Goo.ly only
  • referrals: export referrals. Goo.ly only
  • links: export data by links. Goo.ly only
  • post_activity: export activity by posts. WordPress only
  • comment_activity: export activity by comments. WordPress only
  • search_term_activity: export activity by search terms. WordPress only
  • users: export users. WordPress only
  • orders: export orders. Shopify only
  • products: export products. Shopify only
  • customers: export customers. Shopify only
  • ebay_items: export items. Ebay only
  • ebay_orders: export orders. Ebay only
  • ebay_users: export users. Ebay only
  • etsy_listings: export listings. Etsy only
  • etsy_shops: export shops. Etsy only
  • etsy_transaction: export transactions. Etsy only
  • etsy_users: export users. Etsy only
  • orkut_post: export posts. Orkut only
  • orkut_scraps: export scraps. Orkut only
  • orkut_testimonials: export testimonials. Orkut only
  • orkut_makamakas: export makamakas. Orkut only
  • orkut_comments: export comments. Orkut only
  • orkut_videos: export videos. Orkut only
  • orkut_photos: export photos. Orkut only
  • orkut_users: export users. Orkut only
  • digg_diggs: export users. Digg only
  • digg_comments: export comments. Digg only
  • digg_followers: export followers. Digg only
  • digg_followings: export followings. Digg only
  • gplus_posts: export posts. Google+ only
  • gplus_reshares: export reshares. Google+ only
  • gplus_plusoners: export plusoners. Google+ only
  • gplus_resharers: export resharers. Google+ only
  • blogger_posts: export posts. Blogger only
  • blogger_comments: export comments. Blogger only
  • blogger_pages: export pages. Blogger only
  • blogger_search_terms: export search terms. Blogger only
  • blogger_users: export users. Blogger only
  • reddit_reddits: export reddits. Reddit only
  • reddit_comments: export comments. Reddit only
  • reddit_friends: export friends. Reddit only
  • instagram_media: export media. Instagram only
  • instagram_comments: export comments. Instagram only
  • instagram_followers: export followers. Instagram only
  • instagram_followings: export followings. Instagram only

Output

  • zip file: downloadable zip file with comma delimited files representing different aspects of account data.

Add Media

Add new media to library

  • project: project identifier
  • url: media url (video or image)
  • mediaType: type of media (image or video). Image by default
  • title: image title (optional)
  • description: image description (optional)

Output

{
    "id":12333
}