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.0 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. 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).

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",
        "email": "user1@company.com",
        "active": "yes",
        "firstName": "roger",
        "deleted": "no"
    },
    {
        "id": "11317",
        "lastName": "robinson",
        "added": "20111031",
        "created": "20100901",
        "email": "user2@company.com",
        "active": "no",
        "firstName": "peter",
        "deleted": "no"
    }
]
                            			

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
  • 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: can user publish. Available values - no_approve or requires_approve
  • publicationApprove: can user approve publications of others. 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.
  • type: account network type.
  • active: activity indicator (true if active, false if paused).
  • image: account icon.
  • access: true if access is ok, false is access is lost.
  • publish: true if account can be published to.


[
    {
        "id": 123181,
        "name": "Social Report",
        "active": true,
        "type": "Active Campaign Account",
        "image": "http://socialreport.com/images/icons/actvecmp-24x24.png",
        "access": true,
        "publish": false
    },
    {
        "id": 45678,
        "name": "SocialReport.com",
        "active": false,
        "type": "Facebook Page",
        "image": "https://graph.facebook.com/341093549238622/picture",
        "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",
        "access": true,
        "publish": true
    }
]
                            			

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, myspace, linkedin, youtube, foursquare, googleanalytics, vimeo, meetup, ebay, orkut, googleplus, shopify, tumblr, clicky, addthis, blogger, reddit, instagram,
  • 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
  • accessKey2: additional access key. Required only for orkut account
  • accessSecret2: additional access secret. Required only for orkut account
  • 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
  • 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])
  • schedule: JSON array of schedule objects see below example
  • image: if you are including an image, specify its url here
  • roi: return on investment configuration, see below example
  • targeting: specialized publication targeting, see below example


{
    "project": 1,
    "name": "My First Publication",
    "accounts": [10031,275],
    "schedule":  {
        "20141012 12 12 EST": {
            "message": "message 1 text http://www.socialreport.com",
            "twitterMessage": "twitter message 1 #smm"
        },
        "20141015 12 12 EST": {
            "message": "message 2 text http://www.socialreport.com",
            "twitterMessage": "twitter message 2 #smm"
        }
    },
    "image": "http://www.socialreport.com/includes/logo.png",
    "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.
  • type: campaign type (i.e. L - manual, RSS - rss syndication)
  • status: current campaign status.


[
    {
        "id": "1061",
        "status": "pending",
        "name": "sr blog",
        "type": "RSS",
        "approved": "yes"
    },
    {
        "id": "1059",
        "status": "inprogress",
        "name": "monday 9:37",
        "type": "L",
        "approved": "yes"
    }
]
                                                

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"
        }
    },
    "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 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, myspace, linkedin, youtube, foursquare, googleanalytics, vimeo, meetup, ebay, orkut, googleplus, shopify, tumblr, clicky, addthis, blogger, reddit, instagram,
  • 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
  • accessKey2: additional access key. Required only for orkut account
  • accessSecret2: additional access secret. Required only for orkut account
  • profileUrl: profile url

Output

  • id: unique account identifier.


[
    {
        "id": "326"
    }
]
                            			

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"
    }
]
                                                

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",
            "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)
  • 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

Get a project summary for a project - analytical summary of social trend

Parameters

  • export_type: support types: account, campaign, agent, conversation, address-book
  • account: account (required if export_type=account)
  • campaign: account (required if export_type=campaign)
  • project: account (required if export_type=address-book)
  • project: account (required if export_type=address-book or conversation)
  • accounts: account (required if export_type=conversation)
  • from: from date offset (i.e. 20110925)
  • to: to date offset (i.e. 20111025). note that maximum allowed date range is 30 days.

Optional Parameters

  • 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_messages: export twitter messages. 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
  • 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

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: image url
  • title: image title (optional)
  • description: image description (optional)

Output

{
    "id":12333
}