Socital public API

Introduction

This document contains all public API calls that can be performed to api.socital.com. This hostname offers an authenticated API for giving access of data to customers and data team.

By 'user' we mean the API user, ie you.

By 'social user' we mean the page visitor that uses a plugin on a user's website.

POST calls always accept JSON unless noted otherwise.

Authentication

Socital uses JSON Web Tokens (JWT) as a mechanism of authentication and authorization.

All API endpoints that need authentication require a valid JWT in the Authorization header. See the authentication example below on how to perform such a request via cURL.

All tokens expire by default after one month. It is the user's responsibility to renew them in time, manually or automatically if necessary.

Pagination

Calls that result in a potentially large amount of data use pagination.Paginated endpoints accept a page parameter that specifies the page number to fetch, and a pageSize parameter that specifies the maximum number of items per page.

The first page is always 1.

Each response subject to pagination always returns the following metadata:

 
pagination: {
  page: X, // Current page number.
  pageSize: Y // Max number of items in each page.
  total: Z // Total number of results.
}

API endpoints

Authentication

POST /api/v1/rpc/auth/authenticate

Used to authenticate user and give him a JWT token, to access all calls that require authentication.

Example:

 
curl -X POST -H "Content-Type: application/json" -d'{"email":"...","password":"..."}' api.socital.com/api/v1/rpc/auth/authenticate

Reply:

 
{
  "token": "<raw JWT data>"
}

This token should be inserted to the Bearer header on each subsequent call that requires authentication, as follows:

 
curl -X POST -H "Authorization: Bearer <raw JWT data>" -H "Content-Type: application/json" ...

POST /api/v1/rpc/auth/verifyAuthToken

Used to verify the validity of a JWT; checks if the JWT is valid and not expired.

This call requires a valid JWT.

Example:

 
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <raw JWT data>" api.socital.com/api/v1/rpc/auth/verifyAuthToken

Reply:

 
{
  "success": true
}

User data retrieval

GET /api/v1/user

User to get user data, such as your ID.

This call requires a valid JWT.

This call supports pagination.

This call requires one of the following parameters:

Example:

 
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <raw JWT data>" "api.socital.com/api/v1/user"

Reply:

 
{
  "result": [
    {
      "_id": "...",
      "provider": "...",
      "name": "Socital Test Account",
      "email": "...",
      "company": "Socital",
      "registrationDate": "2014-11-14T12:09:45.732Z",
      "email_verified": true,
      "trustedURLs": [],
      "phones": [],
      "isActive": true,
      "role": "user",
      "audiences": {
        "Example audience": {
          "usedPluginNames": [
            "Example Plugin Name"
          ]
        }
      }
    }
  ],
  "code": 200,
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 1
  }
}

Social user data retrieval

GET /api/v1/socialUserID

This call is DEPRECATED, see /api/v1/socialUser instead

This call requires a valid JWT.

This call supports pagination.

Returns the IDs of the social users that have logged in the site via one of the specified user's registered applications.

This call requires the following parameter:

Example:

 
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <raw JWT data>" api.socital.com/api/v1/socialUserID?userID=<your user id>

Reply:

 
{
  "result": [
    "<first id>",
    "<second id>"
  ],
  "code": 200,
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 2
  }
}

GET /api/v1/socialUser

This call requires a valid JWT.

This call supports pagination.

Returns the IDs of the social users that have logged in the site via one of the specified user's registered applications.

This call has the following optional parameters:

Example:

 
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer <raw JWT data>" "api.socital.com/api/v1/socialUser"

Reply:

 
{
  "result": [
    {
      "updatedAt": "2017-01-11T10:20:27.632Z",
      "age": 44,
      "acquisitionDay": "Friday",
      "acquisitionDate": 1482477266484,
      "browserName": "Chrome",
      "clientID": "...",
      "deviceType": "desktop",
      "email": "...",
      "influence": 1000,
      "interests": [],
      "isEnglishSpeaker": "no",
      "languages": [
        "English"
      ],
      "locales": [
        "en-US",
        "en"
      ],
      "location": "Athens, Nomarchia Athinas, Attica, Greece",
      "locationsOfInterest": [],
      "loginPluginID": "...",
      "loginPluginName": "",
      "loginURL": "https://test.site.com",
      "loginHostname": "test.site.com",
      "personality": [],
      "OSname": "Windows",
      "providers": [
        "email"
      ],
      "socialUserID": "...",
      "spendingCapacity": 2,
      "timeZone": "(UTC+02:00)",
      "topLevelInterests": [],
      "surveysData": [],
      "usedPluginIDs": [
        "..."
      ],
      "usedPluginNames": [
        "Example Plugin Name"
      ],
      "urlsOfInterest": []
    }
  ],
  "code": 200,
  "pagination": {
    "page": 1,
    "pageSize": 1,
    "total": 23
  }
}