NAV
shell

Introduction

Welcome to the Sociality.io API reference! You can use our API endpoints to access Sociality.io functionality.

The Sociality.io API is organized around REST. Our API accepts form-encoded request bodies and returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

You can view code examples in the area to the right, and you can switch the programming language of the examples with the tabs in the top right. Currently, we are providing a Curl example but more coming soon.

Authentication

To authorize, use this code:

# With cURL, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Make sure to replace YOUR_API_KEY with your API key.

The Sociality.io API uses API keys to authenticate requests. You can view and manage your API keys in the Sociality.io Management Panel.

Sociality.io expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR_API_KEY

Me

GET /v1/me

curl "https://api.sociality.io/v1/me" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE

{
    "name": "API Key Name",
    "expires_at": "2030-09-24T19:11:58.130000Z",
    "updated_at": "2020-09-24T19:11:58.140000Z",
    "created_at": "2020-01-01T19:11:58.140000Z"
}

Retrieves the details of the API token.

Accounts

An Account is a social media profile that is connected to your Sociality.io's account. You can retrieve individual accounts as well as a list of all your accounts.

The Account Object

The Account Object

{
  "id": "5a29c75819971e0007569505",
  "name": "Sociality.io",
  "username": "sociality.io",
  "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
  "link": "https://www.facebook.com/sociality.io/",
  "channel": "facebook",
  "is_active": true,
  "is_token_active": true,
  "timezone": "Europe/London",
  "updated_at": "2020-05-27T12:19:44.000000Z",
  "created_at": "2017-12-07T22:57:28.741000Z"
}

The definition of the parameters in the account object.

Parameter Type Description
id string Unique identifier for the object.
name string The account's full name.
username string The account's user name.
image string The account's image link.
link string The account's page link.
channel enum The account's social media platform. Enum values are: facebook, twitter, instagrambusiness, youtube, linkedinbusiness
is_active boolean Whether the account is active for publishing new posts. If not you can't publish posts through this account.
is_token_active boolean Whether the account is connected correctly to the social media platform. If not you can't publish posts through this account.
timezone string The timezone used for this account. A list of possible time zone values is maintained at the IANA Time Zone Database.
updated_at datetime Indicates the datetime when the account was updated.
created_at datetime Indicates the datetime when the account was created.

List All Accounts

GET /v1/accounts

curl "https://api.sociality.io/v1/accounts" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE:

[
  {
    "id": "5a29c75819971e0007569505",
    "name": "Sociality.io",
    "username": "sociality.io",
    "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
    "link": "https://www.facebook.com/sociality.io/",
    "channel": "facebook",
    "is_active": true,
    "is_token_active": true,
    "timezone": "Europe/London",
    "updated_at": "2020-05-27T12:19:44.000000Z",
    "created_at": "2017-12-07T22:57:28.741000Z"
  },
  {
    "id": "5a5e5fd38b747e000a2984e2",
    "name": "Sociality.io",
    "username": "SocialityIO",
    "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
    "link": "https://twitter.com/SocialityIO",
    "channel": "twitter",
    "is_active": true,
    "is_token_active": true,
    "timezone": "America/New_York",
    "updated_at": "2020-10-06T00:04:31.335000Z",
    "created_at": "2018-01-16T20:25:55.000000Z"
  }
]

Returns a list of your accounts. The accounts are returned sorted by creation date, with the most recent accounts appearing first.

Retrieve an Account

GET /v1/accounts/:id

curl "https://api.sociality.io/v1/accounts/5a29c75819971e0007569505" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE

{
  "id": "5a29c75819971e0007569505",
  "name": "Sociality.io",
  "username": "sociality.io",
  "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
  "link": "https://www.facebook.com/sociality.io/",
  "channel": "facebook",
  "is_active": true,
  "is_token_active": true,
  "timezone": "Europe/London",
  "updated_at": "2020-05-27T12:19:44.000000Z",
  "created_at": "2017-12-07T22:57:28.741000Z"
}

Retrieves the details of an existing account. You need only supply the unique account identifier.

Posts

A Post is a social media post that is created under one of your Account. The API allows you to create, delete, and update your posts. You can retrieve individual posts as well as a list of all your posts.

The Post Object

The Post Object

{
  "id": "5db49251a33753001653cca4",
  "account_id": "5a29c75819971e0007569505",
  "code": "443291732542137_1128817387322898",
  "link": "https://www.facebook.com/443291732542137/posts/1128817387322898/",
  "is_published": true,
  "status": 3,
  "published_at": "2019-10-22T12:07:46.000000Z",
  "entry": {
    "type": "photo",
    "text": "We are at the Facebook iD8 event in Berlin to meet and learn from Facebook team members and Facebook developers and partners.",
    "title": null,
    "media": [
      "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png"
      "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_PdaJuCtkBJAnoFBsoIVUcI1IkQH0wkIARU6esdFn.jpeg"
    ]
  },
  "stat": {
    "like_count": 3,
    "comment_count": 0,
    "share_count": 0,
    "view_count": 0,
    "reactions_like_count": 3,
    "reactions_love_count": 0,
    "reactions_wow_count": 0,
    "reactions_haha_count": 0,
    "reactions_sad_count": 0,
    "reactions_angry_count": 0,
    "reactions_thankful_count": 0
  },
  "updated_at": "2019-10-26T20:36:41.000000Z",
  "created_at": "2019-10-26T18:37:05.000000Z"
}

The definition of the parameters in the post object.

Parameter Type Description
id string Unique identifier for the object.
account_id string The unique identifier of the account this post is associated with. You can retrieve the details of the account.
code string Unique social media platform identifier of the post.
link string The post's permalink.
is_published boolean Whether the post is published on the social media platform.
status integer The current status of the post. Status values are: 0 for the post waiting for approval, 1 for the approved post and will be published by the platform, 2 for the post that is publishing right now, 3 for the post which is already published on the social media platform, -1 for the post that was not able to publish on social media platform (When an error occurred on the social media APIs or servers)
published_at datetime Indicates the datetime when the post was published or will be published.
entry.type enum The post's type. Enum values are: status for the post that includes only text, photo for the post that includes image(s), video for the post that includes video, gif for the post that includes a GIF, link for the post that includes a main link, carousel for the post that includes multiple images and/or videos.
entry.text string The post's text.
entry.title string The post's title. The entry.title is used in the video type posts.
entry.media array An array containing the media links of the post.
stat array The engagement metrics for the published post. The metrics are varying by the social media platform of the post.
updated_at datetime Indicates the datetime when the post was updated.
created_at datetime Indicates the datetime when the post was created.

List All Posts

GET /v1/posts

curl "https://api.sociality.io/v1/posts" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d account_id[]=5a29c75819971e0007569505 \
  -d account_id[]=5a5e5fd38b747e000a2984e2 \
  -d published_at_start="2018-01-01 00:00:00" \
  -d published_at_end="2020-10-01 00:00:00" \
  -d skip=0 \
  -G

RESPONSE:

[
    {
    "id": "5db49251a33753001653cca4",
    "account_id": "5a29c75819971e0007569505",
    "code": "443291732542137_1128817387322898",
    "link": "https://www.facebook.com/443291732542137/posts/1128817387322898/",
    "is_published": true,
    "status": 3,
    "published_at": "2019-10-22T12:07:46.000000Z",
    "entry": {
      "type": "photo",
      "text": "We are at the Facebook iD8 event in Berlin to meet and learn from Facebook team members and Facebook developers and partners.",
      "title": null,
      "media": [
        "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png"
        "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_PdaJuCtkBJAnoFBsoIVUcI1IkQH0wkIARU6esdFn.jpeg"
      ]
    },
    "stat": {
      "like_count": 3,
      "comment_count": 0,
      "share_count": 0,
      "view_count": 0,
      "reactions_like_count": 3,
      "reactions_love_count": 0,
      "reactions_wow_count": 0,
      "reactions_haha_count": 0,
      "reactions_sad_count": 0,
      "reactions_angry_count": 0,
      "reactions_thankful_count": 0
    },
    "updated_at": "2019-10-26T20:36:41.000000Z",
    "created_at": "2019-10-26T18:37:05.000000Z"
  },
  {
    "id": "5e77ce98291931001a695862",
    "account_id": "5a5e5fd38b747e000a2984e2",
    "code": "1230760087427239936",
    "link": "https://twitter.com/socialityIO/status/1230760087427239936",
    "is_published": true,
    "status": 3,
    "published_at": "2020-02-21T07:44:05.000000Z",
    "entry": {
      "type": "status",
      "text": "Hello twitter!",
      "title": null,
      "media": null
    },
    "stat": {
      "retweet_count": 10,
      "favorite_count": 5
    },
    "updated_at": "2020-03-22T20:46:16.959000Z",
    "created_at": "2020-03-22T20:46:16.853000Z"
  }
]

Returns a list of the posts that are belonging to the account(s) you sent. The posts are returned sorted by published date, with the most recent published date posts appearing first.

Parameters

Parameter Type Required Description
account_id array required The unique identifier of the account(s) that the posts are associated with.
published_at_start datetime optional Return results where the published_at value is greater than this value.
published_at_end datetime optional Return results where the published_at value is less than this value.
skip integer optional A cursor for use in pagination. skip is an integer that defines your place in the list.

Retrieve a Post

GET /v1/posts/:id

curl "https://api.sociality.io/v1/posts/5db49251a33753001653cca4" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE

{
  "id": "5db49251a33753001653cca4",
  "account_id": "5a29c75819971e0007569505",
  "code": "443291732542137_1128817387322898",
  "link": "https://www.facebook.com/443291732542137/posts/1128817387322898/",
  "is_published": true,
  "status": 3,
  "published_at": "2019-10-22T12:07:46.000000Z",
  "entry": {
    "type": "photo",
    "text": "We are at the Facebook iD8 event in Berlin to meet and learn from Facebook team members and Facebook developers and partners.",
    "title": null,
    "media": [
      "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png"
      "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_PdaJuCtkBJAnoFBsoIVUcI1IkQH0wkIARU6esdFn.jpeg"
    ]
  },
  "stat": {
    "like_count": 3,
    "comment_count": 0,
    "share_count": 0,
    "view_count": 0,
    "reactions_like_count": 3,
    "reactions_love_count": 0,
    "reactions_wow_count": 0,
    "reactions_haha_count": 0,
    "reactions_sad_count": 0,
    "reactions_angry_count": 0,
    "reactions_thankful_count": 0
  },
  "updated_at": "2019-10-26T20:36:41.000000Z",
  "created_at": "2019-10-26T18:37:05.000000Z"
}

Retrieves the details of an existing post. You need only supply the unique post identifier.

Create a Post

POST /v1/posts

curl "https://api.sociality.io/v1/posts" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d account_id=5a29c75819971e0007569505 \
  -d text="Hello World" \
  -d media[]="http://example.com/sample1.png" \
  -d media[]="http://example.com/sample1.png" \
  -d is_publish_now=0 \
  -d published_at="2020-12-01 10:00:00" \
  -G

RESPONSE

{
  "id": "5db49251a33753001653cca4",
  "account_id": "5a29c75819971e0007569505",
  "code": null,
  "link": null,
  "is_published": false,
  "status": 1,
  "published_at": "2020-12-01T10:00:00.000000Z",
  "entry": {
    "type": "photo",
    "text": "Hello World",
    "title": null,
    "media": [
      "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png"
      "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_PdaJuCtkBJAnoFBsoIVUcI1IkQH0wkIARU6esdFn.jpeg"
    ]
  },
  "stat": null,
  "updated_at": "2020-10-26T20:36:41.000000Z",
  "created_at": "2020-10-26T18:37:05.000000Z"
}

Creates a new post object. You can schedule or publish your posts on the social media platforms using this API endpoint.

Parameters

Parameter Type Required Description
account_id string required The unique identifier of the account that the post is associated with.
text string required if the media is empty The post's text.
title string optional The post's title. The title is used in the video type posts.
media array required if the text is empty An array containing the media links of the post. These media types are supported: jpeg, jpg, png, mp4,and gif (Gif is supported only on the Twitter platform)
is_publish_now boolean optional If true, the post is published on the social media platform(s) right away without checking published_at parameter.
published_at datetime required if the is_publish_now is empty or false Indicates the datetime when the post will be published.

Update a Post

PUT /v1/posts/:id

curl "https://api.sociality.io/v1/posts/5db49251a33753001653cca4" \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d text="Hello New World" \
  -d published_at="2021-01-01 10:00:00" \
  -G

RESPONSE

{
  "id": "5db49251a33753001653cca4",
  "account_id": "5a29c75819971e0007569505",
  "code": null,
  "link": null,
  "is_published": false,
  "status": 1,
  "published_at": "2021-01-01T10:00:00.000000Z",
  "entry": {
    "type": "photo",
    "text": "Hello New World",
    "title": null,
    "media": [
      "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png"
      "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_PdaJuCtkBJAnoFBsoIVUcI1IkQH0wkIARU6esdFn.jpeg"
    ]
  },
  "stat": null,
  "updated_at": "2020-11-26T20:36:41.000000Z",
  "created_at": "2020-10-26T18:37:05.000000Z"
}

Updates the specific post by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Updating a post is only possible if it was not published on the social media platform. You should check out the is_published value of the post before sending your update request.

Parameters

Parameter Type Required Description
text string required if the media is empty The post's text.
title string optional The post's title. The title is used in the video type posts.
is_publish_now boolean optional If true, the post is published on the social media platform(s) right away without checking published_at parameter.
published_at datetime required if the is_publish_now is empty or false Indicates the datetime when the post will be published.

Delete a Post

DELETE /v1/posts/:id

curl "https://api.sociality.io/v1/posts/5f8767f6a5f1b900090c0b02" \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE

{
    "object": "post",
    "id": "5f8767f6a5f1b900090c0b02",
    "deleted": true
}

Deletes an existing post. Deleting a post is only possible if it was not published on the social media platform. You should check out the is_published value of the post before sending your delete request.

Keywords

A Keyword is a listening topic that Sociality.io tracks over social media platforms, blogs and, the web. You can retrieve individual keywords as well as a list of all your keywords.

The Keyword Object

The Keyword Object

{
  "id": "5a29c75819971e0007569505",
  "name": "Brand Listening",
  "query": {
    "or": [
      "sociality.io", 
      "socialityio"
    ], 
    "and": [], 
    "not": [
      "social", 
    ]
  },
  "is_active": true,
  "color": "#002e5f",
  "timezone": "Europe/London",
  "updated_at": "2020-05-27T12:19:44.000000Z",
  "created_at": "2017-12-07T22:57:28.741000Z"
}

The definition of the parameters in the keyword object.

Parameter Type Description
id string Unique identifier for the object.
name string The keyword's defined name.
query json The defined search query for the keyword.
is_active boolean Whether the keyword is active for tracking new mentions.
color string The hex color code of the keyword.
timezone string The timezone used for this keyword. A list of possible time zone values is maintained at the IANA Time Zone Database.
updated_at datetime Indicates the datetime when the keyword was updated.
created_at datetime Indicates the datetime when the keyword was created.

List All Keywords

GET /v1/keywords

curl "https://api.sociality.io/v1/keywords" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE:

[
  {
    "id": "5a29c75819971e0007569505",
    "name": "Brand Listening",
    "query": {
      "or": [
        "sociality.io", 
        "socialityio",
        "#socialityio"
      ], 
      "and": [], 
      "not": [
        "social", 
      ]
    },
    "is_active": true,
    "color": "#002e5f",
    "timezone": "Europe/London",
    "updated_at": "2020-05-27T12:19:44.000000Z",
    "created_at": "2017-12-07T22:57:28.741000Z"
  },
  {
    "id": "5a5e5fd38b747e000a2984e2",
    "name": "Competitor Listening",
    "query": {
      "or": [
        "buffer", 
        "bufferapp"
      ], 
      "and": [], 
      "not": []
    },
    "is_active": true,
    "color": "#2c4bfe",
    "timezone": "Europe/London",
    "updated_at": "2020-05-27T12:19:44.000000Z",
    "created_at": "2017-12-07T22:57:28.741000Z"
  }
]

Returns a list of your keywords. The keywords are returned sorted by creation date, with the most recent keywords appearing first.

Retrieve a Keyword

GET /v1/keywords/:id

curl "https://api.sociality.io/v1/keywords/5a29c75819971e0007569505" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE

{
  "id": "5a29c75819971e0007569505",
  "name": "Brand Listening",
  "query": {
    "or": [
      "sociality.io", 
      "socialityio",
      "#socialityio"
    ], 
    "and": [], 
    "not": [
      "social", 
    ]
  },
  "is_active": true,
  "color": "#002e5f",
  "timezone": "Europe/London",
  "updated_at": "2020-05-27T12:19:44.000000Z",
  "created_at": "2017-12-07T22:57:28.741000Z"
}

Retrieves the details of an existing keyword. You need only supply the unique keyword identifier.

Mentions

A Mention is an object that belongs to a keyword. A mention has one of these types: tweet or Instagram post or youtube post or web page or news or blog. You can retrieve individual mentions as well as a list of all your mentions.

The Mention Object

The Mention Object

{
  "id": "5a29c75819971e0007569505",
  "keyword_id": "5eca8a06952a3661b8563012",
  "code": "1345095357739331584",
  "category": "social_media",
  "source": "twitter.com",
  "link": "https://twitter.com/instagram/status/1345095357739331584",
  "published_at": "2021-01-01T19:51:44.000000Z",
  "entry": {
    "message": "Looking at 2021 like... #WeeklyFluff",
    "link": "https://twitter.com/instagram/status/1345095357739331584",
    "description": null,
    "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
    "video": null,
    "user": {
      "followers_count": 34845000,
      "id": "1191410135576518656",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "name": "Instagram",
      "username": "instagram"
    },
  },
  "processed": {
    "sentiment": "notr", 
    "category": "product", 
    "attribute": "suggestion", 
    "tag": null
  },
  "updated_at": "2020-05-27T12:19:44.000000Z",
  "created_at": "2017-12-07T22:57:28.741000Z"
}

The definition of the parameters in the mention object.

Parameter Type Description
id string Unique identifier for the object.
keyword_id string The unique identifier of the keyword this mention is associated with. You can retrieve the details of the keyword.
code string Unique social media platform or web page identifier of the mention.
category enum The category of the mention. Enum values are: social_media for the mention that published in one the social media platforms, news for the mention that published in a news website, blog for the mention that published in a blog website, web for the mention that published in any website.
source string The domain name of the platform that the mention published.
link string The mention's permalink.
published_at datetime Indicates the datetime when the mention was published.
entry object The detailed data of the mention object.
processed.sentiment enum The sentiment of the mention. Enum values are: positive for the mention that includes positive emotion, negative for the mention that includes negative emotion, notr for the mention that has no emotion.
processed.category string The mention's processed category.
processed.attribute string The mention's processed attribute.
processed.tag string The mention's processed tag.
updated_at datetime Indicates the datetime when the mention was updated.
created_at datetime Indicates the datetime when the mention was created.

List All Mentions

GET /v1/mentions

curl "https://api.sociality.io/v1/mentions" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d keyword_id[]=5eca8a06952a3661b8563012 \
  -d keyword_id[]=5ee1f7fd952a3644e1022ae8 \
  -d query="" \
  -d published_at_start="2018-01-01 00:00:00" \
  -d published_at_end="2021-01-15 00:00:00" \
  -d skip=0 \
  -G

RESPONSE:

[
  {
    "id": "5a29c75819971e0007569505",
    "keyword_id": "5eca8a06952a3661b8563012",
    "code": "1345095357739331584",
    "category": "social_media",
    "source": "twitter.com",
    "link": "https://twitter.com/instagram/status/1345095357739331584",
    "published_at": "2021-01-01T19:51:44.000000Z",
    "entry": {
      "message": "Looking at 2021 like... #WeeklyFluff",
      "link": "https://twitter.com/instagram/status/1345095357739331584",
      "description": null,
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "video": null,
      "user": {
        "followers_count": 34845000,
        "id": "1191410135576518656",
        "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
        "name": "Instagram",
        "username": "instagram"
      },
    },
    "processed": {
      "sentiment": "notr", 
      "category": "product", 
      "attribute": "suggestion", 
      "tag": null
    },
    "updated_at": "2020-05-27T12:19:44.000000Z",
    "created_at": "2017-12-07T22:57:28.741000Z"
  },
  {
    "id": "5a29c75819971e0007569505",
    "keyword_id": "5ee1f7fd952a3644e1022ae8",
    "code": "a9e903a7c73a0328035a2ad84d63f526",
    "category": "web",
    "source": "amazon.com",
    "link": "https://www.amazon.com/Gillette-Fusion5-Razor-Blades-Count/dp/B073ZL4N94",
    "published_at": "2021-01-01T19:51:44.000000Z",
    "entry": {
      "message": "Gillette Fusion5 Men's Razor Blades, 4 Blade",
      "link": "https://www.amazon.com/Gillette-Fusion5-Razor-Blades-Count/dp/B073ZL4N94",
      "description": "Gillette razors for men with 5 anti-friction blades. A shave you barely feel; Men's razor with ...",
      "image": null,
      "video": null,
      "user": {
        "followers_count": null,
        "id": null,
        "image": null,
        "name": null,
        "username": "amazon.com"
      },
    },
    "processed": {
      "sentiment": "positive", 
      "category": null, 
      "attribute": null, 
      "tag": null
    },
    "updated_at": "2020-05-27T12:19:44.000000Z",
    "created_at": "2017-12-07T22:57:28.741000Z"
  }
]

Returns a list of the mentions that are belonging to the keyword(s) you sent. The mentions are returned sorted by published date, with the most recent published date mentions appearing first.

Parameters

Parameter Type Required Description
keyword_id array required The unique identifier of the keyword(s) that the mentions are associated with.
published_at_start datetime optional Return results where the published_at value is greater than this value.
published_at_end datetime optional Return results where the published_at value is less than this value.
query string optional Return the results includes the query value.
skip integer optional A cursor for use in pagination. skip is an integer that defines your place in the list.

Retrieve a Mention

GET /v1/mentions/:id

curl "https://api.sociality.io/v1/mentions/5a29c75819971e0007569505" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE

{
  "id": "5a29c75819971e0007569505",
  "keyword_id": "5eca8a06952a3661b8563012",
  "code": "1345095357739331584",
  "category": "social_media",
  "source": "twitter.com",
  "link": "https://twitter.com/instagram/status/1345095357739331584",
  "published_at": "2021-01-01T19:51:44.000000Z",
  "entry": {
    "message": "Looking at 2021 like... #WeeklyFluff",
    "link": "https://twitter.com/instagram/status/1345095357739331584",
    "description": null,
    "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
    "video": null,
    "user": {
      "followers_count": 34845000,
      "id": "1191410135576518656",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "name": "Instagram",
      "username": "instagram"
    },
  },
  "processed": {
    "sentiment": "notr", 
    "category": "product", 
    "attribute": "suggestion", 
    "tag": null
  },
  "updated_at": "2020-05-27T12:19:44.000000Z",
  "created_at": "2017-12-07T22:57:28.741000Z"
}

Retrieves the details of an existing mention. You need only supply the unique mention identifier.

Conversations

A Conversation is a thread (messages/mentions/comments) that Sociality.io tracks from your own social media profiles. You can retrieve individual conversations as well as a list of all your conversations.

The Conversation Object

The Conversation Object

{
  "id": "5ff399723aca570d052d20ea",
  "account_id": "5a29c75819971e0007569505",
  "code": "17869584047227710",
  "type": "comment",
  "done": false,
  "marked": false,
  "read": true,
  "published_at": "2021-01-01T19:51:44.000000Z",
  "entry": {
    "message": "Hello world!",
    "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
    "description": null,
    "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
    "video": null,
    "user": {
      "followers_count": 34845000,
      "id": "1191410135576518656",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "name": "Instagram",
      "username": "instagram"
    },
  },
  "updated_at": "2020-05-27T12:19:44.000000Z",
  "created_at": "2017-12-07T22:57:28.741000Z"
}

The definition of the parameters in the conversation object.

Parameter Type Description
id string Unique identifier for the object.
account_id string The unique identifier of the account this conversation is associated with. You can retrieve the details of the account.
code string Unique social media platform identifier of the conversation.
type enum The type of the conversation. Enum values are: comment for the comments, message for the direct messages, post_user for the visitor posts, ad_comment for the promoted posts comments, mentioned_media for the posts that mentioned your account, mentioned_comment for comments that mentioned your account.
done boolean Whether the conversation is done/archived.
marked boolean Whether the conversation is starred/marked.
read boolean Whether the conversation is read.
published_at datetime Indicates the datetime when the conversation was published.
entry object The detailed data of the social media post that the conversation associated with.
updated_at datetime Indicates the datetime when the conversation was updated.
created_at datetime Indicates the datetime when the conversation was created.

List All Conversations

GET /v1/conversations

curl "https://api.sociality.io/v1/conversations" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d account_id[]=5a29c75819971e0007569505 \
  -d account_id[]=5ef6581e952a3662bd1f1ac2 \
  -d type[]=comment \
  -d type[]=message \
  -d published_at_start="2018-01-01 00:00:00" \
  -d published_at_end="2021-01-15 00:00:00" \
  -d done=false \
  -d marked=false \
  -d query="" \
  -d skip=0 \
  -G

RESPONSE:

[
  {
    "id": "5ff399723aca570d052d20ea",
    "account_id": "5a29c75819971e0007569505",
    "code": "17869584047227710",
    "type": "comment",
    "done": false,
    "marked": false,
    "read": true,
    "published_at": "2021-01-01T19:51:44.000000Z",
    "entry": {
      "message": "Hello world!",
      "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
      "description": null,
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "video": null,
      "user": {
        "followers_count": 34845000,
        "id": "1191410135576518656",
        "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
        "name": "Instagram",
        "username": "instagram"
      },
    },
    "updated_at": "2020-05-27T12:19:44.000000Z",
    "created_at": "2017-12-07T22:57:28.741000Z"
  },
  {
    "id": "5ff399723aca570d052d20ea",
    "account_id": "5ef6581e952a3662bd1f1ac2",
    "code": "1291137954320358",
    "type": "message",
    "done": false,
    "marked": false,
    "read": false,
    "published_at": "2021-01-11T20:12:12.000000Z",
    "entry": {
      "message": "Hello world!",
      "link": "https://business.facebook.com/socialityio/inbox/1291137954320358",
      "description": null,
      "image": null,
      "video": null,
      "user": null,
    },
    "updated_at": "2020-05-27T12:19:44.000000Z",
    "created_at": "2017-12-07T22:57:28.741000Z"
  }
]

Returns a list of the conversations that are belonging to the account(s) you sent. The conversations are returned sorted by published date, with the most recent published date conversations appearing first.

Parameters

Parameter Type Required Description
account_id array required The unique identifier of the account(s) that the conversations are associated with.
type array optional The type of the conversations. If empty all types of conversations return.
published_at_start datetime optional Return results where the published_at value is greater than this value.
published_at_end datetime optional Return results where the published_at value is less than this value.
done boolean optional Return results where the done value is equal to this value.
marked boolean optional Return results where the marked value is equal to this value.
query string optional Return the results includes the query value.
skip integer optional A cursor for use in pagination. skip is an integer that defines your place in the list.

Retrieve a Conversation

GET /v1/conversations/:id

curl "https://api.sociality.io/v1/conversations/5ff399723aca570d052d20ea" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE

{
  "id": "5ff399723aca570d052d20ea",
  "account_id": "5a29c75819971e0007569505",
  "code": "17869584047227710",
  "type": "comment",
  "done": false,
  "marked": false,
  "read": true,
  "published_at": "2021-01-01T19:51:44.000000Z",
  "entry": {
    "message": "Hello world!",
    "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
    "description": null,
    "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
    "video": null,
    "user": {
      "followers_count": 34845000,
      "id": "1191410135576518656",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "name": "Instagram",
      "username": "instagram"
    },
  },
  "conversation_items": [
    {
      "id": "5e0f293d6805ff06e57070c0",
      "account_id": "5a29c75819971e0007569505",
      "conversation_id": "5ff399723aca570d052d20ea",
      "code": "18042179905285881",
      "published_at": "2021-01-01T20:15:44.000000Z",
      "entry": {
        "message": "Thanks!",
        "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
        "description": null,
        "image": null,
        "video": null,
        "user": {
          "followers_count": 4890,
          "id": "5a29c75819971e0007569505",
          "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
          "name": "Sociality.io",
          "username": "sociality.io"
        },
        "recipient": {
          "followers_count": 34845000,
          "id": "1191410135576518656",
          "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
          "name": "Instagram",
          "username": "instagram"
        }
      },
      "processed": {
        "sentiment": "positive", 
        "category": null, 
        "attribute": null, 
        "tag": null
      },
      "updated_at": "2020-12-07T22:57:28.741000Z",
      "created_at": "2020-12-07T22:57:28.741000Z"
    },
    {
      "id": "5ff399733aca570d052d20eb",
      "account_id": "5a29c75819971e0007569505",
      "conversation_id": "5ff399723aca570d052d20ea",
      "code": "17869584047227710",
      "published_at": "2021-01-01T19:51:44.000000Z",
      "entry": {
        "message": "Great",
        "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
        "description": null,
        "image": null,
        "video": null,
        "user": {
          "followers_count": 34845000,
          "id": "1191410135576518656",
          "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
          "name": "Instagram",
          "username": "instagram"
        },
        "recipient": {
          "followers_count": 4890,
          "id": "5a29c75819971e0007569505",
          "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
          "name": "Sociality.io",
          "username": "sociality.io"
        },
      },
      "processed": {
        "sentiment": "positive", 
        "category": "product", 
        "attribute": "pleasure", 
        "tag": null
      },
      "updated_at": "2020-12-07T22:57:28.741000Z",
      "created_at": "2020-12-07T22:57:28.741000Z"
    }
  ],
  "updated_at": "2020-05-27T12:19:44.000000Z",
  "created_at": "2017-12-07T22:57:28.741000Z"
}

Retrieves the details of an existing conversation. Also the conversation items associated with the conversation are included. You need only supply the unique conversation identifier.

Conversation Items

A Conversation Item is a message/mention/comment item that belongs to a conversation. You can create conversation items, retrieve individual conversation items as well as a list of all your conversation items.

The Conversation Item Object

The Conversation Item Object

{
  "id": "5ff399733aca570d052d20eb",
  "account_id": "5a29c75819971e0007569505",
  "conversation_id": "5ff399723aca570d052d20ea",
  "code": "17869584047227710",
  "published_at": "2021-01-01T19:51:44.000000Z",
  "entry": {
    "message": "Great",
    "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
    "description": null,
    "image": null,
    "video": null,
    "user": {
      "followers_count": 34845000,
      "id": "1191410135576518656",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "name": "Instagram",
      "username": "instagram"
    },
    "recipient": {
      "followers_count": 4890,
      "id": "5a29c75819971e0007569505",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
      "name": "Sociality.io",
      "username": "sociality.io"
    },
  },
  "processed": {
    "sentiment": "positive", 
    "category": "product", 
    "attribute": "pleasure", 
    "tag": null
  },
  "updated_at": "2020-12-07T22:57:28.741000Z",
  "created_at": "2020-12-07T22:57:28.741000Z"
}

The definition of the parameters in the conversation item object.

Parameter Type Description
id string Unique identifier for the object.
account_id string The unique identifier of the account this conversation item is associated with. You can retrieve the details of the account.
conversation_id string The unique identifier of the conversation this conversation item is associated with. You can retrieve the details of the conversation.
code string Unique social media platform identifier of the conversation item.
published_at datetime Indicates the datetime when the conversation item was published.
entry object The detailed data of the conversation item object.
processed.sentiment enum The sentiment of the conversation item. Enum values are: positive for the conversation item that includes positive emotion, negative for the conversation item that includes negative emotion, notr for the conversation item that has no emotion.
processed.category string The conversation item's processed category.
processed.attribute string The conversation item's processed attribute.
processed.tag string The conversation item's processed tag.
updated_at datetime Indicates the datetime when the conversation item was updated.
created_at datetime Indicates the datetime when the conversation item was created.

List All Conversation Items

GET /v1/conversation_items

curl "https://api.sociality.io/v1/conversation_items" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d account_id[]=5a29c75819971e0007569505 \
  -d account_id[]=5ef6581e952a3662bd1f1ac2 \
  -d published_at_start="2018-01-01 00:00:00" \
  -d published_at_end="2021-01-15 00:00:00" \
  -d query="" \
  -d skip=0 \
  -G

RESPONSE:

[
  {
    "id": "5e0f293d6805ff06e57070c0",
    "account_id": "5a29c75819971e0007569505",
    "conversation_id": "5ff399723aca570d052d20ea",
    "code": "18042179905285881",
    "published_at": "2021-01-01T20:15:44.000000Z",
    "entry": {
      "message": "Thanks!",
      "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
      "description": null,
      "image": null,
      "video": null,
      "user": {
        "followers_count": 4890,
        "id": "5a29c75819971e0007569505",
        "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
        "name": "Sociality.io",
        "username": "sociality.io"
      },
      "recipient": {
        "followers_count": 34845000,
        "id": "1191410135576518656",
        "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
        "name": "Instagram",
        "username": "instagram"
      }
    },
    "processed": {
      "sentiment": "positive", 
      "category": null, 
      "attribute": null, 
      "tag": null
    },
    "updated_at": "2020-12-07T22:57:28.741000Z",
    "created_at": "2020-12-07T22:57:28.741000Z"
  },
  {
    "id": "5ff399733aca570d052d20eb",
    "account_id": "5a29c75819971e0007569505",
    "conversation_id": "5ff399723aca570d052d20ea",
    "code": "17869584047227710",
    "published_at": "2021-01-01T19:51:44.000000Z",
    "entry": {
      "message": "Great",
      "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
      "description": null,
      "image": null,
      "video": null,
      "user": {
        "followers_count": 34845000,
        "id": "1191410135576518656",
        "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
        "name": "Instagram",
        "username": "instagram"
      },
      "recipient": {
        "followers_count": 4890,
        "id": "5a29c75819971e0007569505",
        "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
        "name": "Sociality.io",
        "username": "sociality.io"
      },
    },
    "processed": {
      "sentiment": "positive", 
      "category": "product", 
      "attribute": "pleasure", 
      "tag": null
    },
    "updated_at": "2020-12-07T22:57:28.741000Z",
    "created_at": "2020-12-07T22:57:28.741000Z"
  }
]

Returns a list of the conversation items that are belonging to the account(s) you sent. The conversation items are returned sorted by published date, with the most recent published date conversation items appearing first.

Parameters

Parameter Type Required Description
account_id array required The unique identifier of the account(s) that the conversation items are associated with.
published_at_start datetime optional Return results where the published_at value is greater than this value.
published_at_end datetime optional Return results where the published_at value is less than this value.
query string optional Return the results includes the query value.
skip integer optional A cursor for use in pagination. skip is an integer that defines your place in the list.

Retrieve a Conversation Item

GET /v1/conversation_items/:id

curl "https://api.sociality.io/v1/conversation_items/5ff399733aca570d052d20eb" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

RESPONSE

{
  "id": "5ff399733aca570d052d20eb",
  "account_id": "5a29c75819971e0007569505",
  "conversation_id": "5ff399723aca570d052d20ea",
  "code": "17869584047227710",
  "published_at": "2021-01-01T19:51:44.000000Z",
  "entry": {
    "message": "Great",
    "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
    "description": null,
    "image": null,
    "video": null,
    "user": {
      "followers_count": 34845000,
      "id": "1191410135576518656",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "name": "Instagram",
      "username": "instagram"
    },
    "recipient": {
      "followers_count": 4890,
      "id": "5a29c75819971e0007569505",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
      "name": "Sociality.io",
      "username": "sociality.io"
    },
  },
  "processed": {
    "sentiment": "positive", 
    "category": "product", 
    "attribute": "pleasure", 
    "tag": null
  },
  "updated_at": "2020-12-07T22:57:28.741000Z",
  "created_at": "2020-12-07T22:57:28.741000Z"
}

Retrieves the details of an existing conversation item. You need only supply the unique conversation identifier.

Create a Conversation Item

POST /v1/conversation_items

curl "https://api.sociality.io/v1/conversation_items" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d conversation_id=5ff399723aca570d052d20ea \
  -d text="Thank you for your feedback." \
  -G

RESPONSE

{
  "id": "5ff399733aca570d052d20eb",
  "account_id": "5a29c75819971e0007569505",
  "conversation_id": "5ff399723aca570d052d20ea",
  "code": "17869584047227721",
  "published_at": "2021-01-02T19:51:44.000000Z",
  "entry": {
    "message": "Thank you for your feedback.",
    "link": "https://www.instagram.com/p/CG9WNcoH-Gg/",
    "description": null,
    "image": null,
    "video": null,
    "user": {
      "followers_count": 4890,
      "id": "5a29c75819971e0007569505",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/138fb79662618f1a3ee4a5082d5d2541.png",
      "name": "Sociality.io",
      "username": "sociality.io"
    },
    "recipient": {
      "followers_count": 34845000,
      "id": "1191410135576518656",
      "image": "https://s3-eu-west-1.amazonaws.com/sociality/public/files/59ad2e769d294d00055cfc83_tY1XAELsAbZlIo4atLJtI7gYZOYEOMbSbJJCxkSh.png",
      "name": "Instagram",
      "username": "instagram"
    },
  },
  "processed": {
    "sentiment": "positive", 
    "category": null, 
    "attribute": null, 
    "tag": null
  },
  "updated_at": "2021-01-02T19:50:44.000000Z",
  "created_at": "2021-01-02T19:50:44.000000Z"
}

Creates a new conversation item object. You can response messages/mentions/comments on the social media platforms using this API endpoint.

Parameters

Parameter Type Required Description
conversation_id string required The unique identifier of the conversation this conversation item is associated with.
text string required The conversation item's text.

Errors

The Sociality.io API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong or no valid API key provided.
403 Forbidden -- The API key doesn't have permissions to perform the request.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a Sociality.io with an invalid method.
429 Too Many Requests -- Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.