Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Guide
Version 35.0, Winter 16
@salesforcedocs
Last updated: December 8, 2015
Copyright 20002015 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS
METHODS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 3: Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Retrieve Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Create Author Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Delete Author Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Delete Author Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Create Comment for Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Retrieve Comment for Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Delete Author Comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Chapter 4: Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Retrieve Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Chapter 5: Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Retrieve Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Retrieve User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Create User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Update User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Reset Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Modify Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Chapter 6: Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Retrieve Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Contents
Retrieve Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Create Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Update Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Delete Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Create Workspace Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Delete Workspace Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Chapter 13: Create Topic Profile and Retrieving Posts with Keyword Groups . . . . . . . 126
Contents
1
Introducing Social Studio REST API Enable API Applications for your Organization
3. Select the Developers can create API Applications checkbox under the API Applications heading.
2
Introducing Social Studio REST API Enable API Applications for your Organization
4. Review the Marketing Cloud Social API Usage Agreement and click I Accept the Terms and Conditions.
3
Introducing Social Studio REST API Enable API Applications for your Organization
5. Enter the details for your new API application: Name Application Description Callback URL
4
Introducing Social Studio REST API Authentication
6. Click Save.
7. To view the details of your application, find it in the applications list and click on it. A dialog will appear on the left side of your screen
that contains all of your application details.
Authentication
You can receive the client key and secret issued for the application via self-serve by a Social Studio super user or an administration by
logging into socialstudio.radian6.com/admin. When creating the credentials for the application, you must specify the redirect URL for
the application. The authentication server will redirect the user to this URL with an authorization code.
Supported Flows
Social Studio currently supports the following OAuth flows:
5
Introducing Social Studio REST API Authorization Code
IN THIS SECTION:
Authorization Code
Requesting an Access Token (Resource Owner Password)
Make Requests
Refresh the Access Token
Revoking an Access Token
Authorization Code
This authentication method redirects the user to an authorization page, which permits the user to grant authorization to the application
to act. The page displays a login prompt with the message Please log in to grant access to the application. Once the user logs in and grants
access, the page will redirect the user to the application redirect URL as specified when generating their client credentials.
Authorization URL: https://api.socialstudio.radian6.com/login/oauth/authorize
Request
Query String Parameter Value
client_id The application client key
state A unique value included in the redirect call that maintains the state
between the request and the response
redirect_url
Response
The call returns the repsonse of this endpoint to the client application be redirecting back to their returned URL with certain query string
parameters set.
6
Introducing Social Studio REST API Requesting an Access Token (Resource Owner Password)
*redirectUrl* - the call specifies this value when creating the client credentials.
*authorizationCode* - the application can handle the authorizationCode as outlined in the
section *Requesting an Access Token*.
*state* - use thestate value you specified in your requests.
*scope* - at present, we do not support specific scopes, so use the default value of OOB
Request
POST /oauth/token HTTP/1.1
Host: api.socialstudio.radian6.com
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
grant_type=password&client_id={clientKey}&client_secret={clientSecret}&username={r6username}&password={r6password}
cURL Example
curl -X POST -H "Cache-Control: no-cache" -H "Content-Type:
application/x-www-form-urlencoded" -d
'grant_type=password&client_id=your_marketing_cloud_api_key&client_secret=your_marketing_cloud_api_secret&username=your_r6_username&password=your_r6_password'
'https://api.socialstudio.radian6.com/oauth/token'
Response
{
"access_token": "bc0fb4f7-2f51-4aa6-9192-f559e481e02f",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "d0e05be9-fb84-4dfb-93a5-8d781024cdc8",
7
Introducing Social Studio REST API Make Requests
"scope": "oob"
}
*access_token* - value used to make requests (as shown in the *Make Requests* section)
*expiresIn* - number of seconds before the token expires
*refresh_token* - value to save and use to refresh the access token (as shown in the
*Refresh the Access Token* section)
Make Requests
You can use a new API host that supports Oauth:
api.socialstudio.radian6.com
Requests to this URL require only an access token and do not require an auth_token or auth_appkey value.
Request
GET {host}v3/user/me HTTP/1.1
Host: api.socialstudio.radian6.com
Connection: keep-alive
Accept: text/html,application/xhtml+xml,application/json;q=0.9,*/*;q=0.8
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8
access_token: 5545b2f1-9a8e-4bdd-a2ee-9d0c70f8fb08
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Request-ID: IsZ0g0ryksn0Cvk6
Content-Encoding: gzip
Content-Type: application/json
Content-Length: 156
Date: Tue, 18 Jun 2013 19:49:02 GMT
{
"data": [
{
"id": "7914",
"username": "john.doe@domain.com",
"displayName": "John Doe",
"email": "john.doe@domain.com",
"timeZone": "America/Halifax",
"enabled": true,
"orgRoleId": 1,
"languageId": 1,
"createdDate": "2014-10-27T14:41:48Z",
"internalUserAvatarUrl": null,
"userAvatarUrl": null,
"clientId": 1
}
],
"meta": {
8
Introducing Social Studio REST API Refresh the Access Token
"totalCount": 1
}
}
Alternatively, you can supply the access token using the header (188+):
Authorization: Bearer {access_token}
cURL Example
curl -X GET -H "access_token: your_access_token" -H "Cache-Control: no-cache"
'https://api.socialstudio.radian6.com/v3/users/me'
{
"error": {
"message": "Validation error",
"statusCode": 401,
"errorCode": "MC-Unknown",
"requestId":"9a135ab7-9e56-49d7-8c1d-7805f2df6ee1"
},
"meta": null
}
An application can wait for this error message and then attempt to refresh the token, or it can use the expires_in time that comes with
the access token to determine when the token needs to be refreshed. The token can be refreshed at any time.
The end point for refreshing an access token is the same as that for requesting an access token, but uses slightly different parameters.
api.socialstudio.radian6.com/oauth/token
Request
POST /oauth/token HTTP/1.1
Host: api.socialstudio.radian6.com
Content-Length: 169
Content-Type: application/x-www-form-urlencoded
Accept: */*
Accept-Encoding: gzip,deflate,sdch
grant_type=refresh_token&refresh_token={refreshToken}&client_id={clientKey}&client_secret={clientSecret}
9
Introducing Social Studio REST API Revoking an Access Token
In this case, the grant_type is refresh_token and instead of supplying a code the parameter is refresh_token.
Response
If the refresh token has been revoked by the user or has become invalid for some other reason, then the refresh call will fail with the
following error:
{
"error":"invalid_request",
"error_description":"Invalid refresh token"
}
Request
GET /oauth/revoke?access_token={access_token} HTTP/1.1
Host: api.socialstudio.radian6.com
Accept: */*
Accept-Encoding: gzip,deflate,sdch
Response
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Encoding: gzip
Content-Type: text/xml;charset=UTF-8
Content-Length: 31
Date: Wed, 07 Aug 2013 18:29:04 GMT
<revoked />
10
GENERAL DEVELOPER INFO
11
Rate Limiting Response Headers
Response Headers
The Social Studio API sends additional headers containing rate limit information with each response. These headers help track application
usage and quotas.
12
METHODS
CHAPTER 3 Authors
In this chapter ... The Authors endpoint allows you to get detailed information on an author. You can also apply additional
metadata by adding and managing tags and notes associated with those authors. Use author tags to
Retrieve Authors identify VIP customers, promoters, or detractors of a brand. Use notes to record additional important
Create Author Tag information on an author record.
Delete Author Tag
Delete Author Tags
Retrieve an Author
Create Comment for
Author
You can retrieve information on an author using the following call:
Retrieve Comment
for Author GET /v3/authors/{id}
Delete Author
Comment
cURL Example
curl -X GET -H "access_token: 0682240d-f531-4dc1-a9a6-c80eba9cb533"
'https://api.socialstudio.radian6.com/v3/authors/36221001'
cURL Example
curl -X POST -H "access_token: 0682240d-f531-4dc1-a9a6-c80eba9cb533"
-H "Content-Type: application/json" -d '{
"value":"VIP"
}' 'https://api.socialstudio.radian6.com/v3/authors/36221001/tags'
13
Authors
cURL Example
curl -X DELETE -H "access_token: 0682240d-f531-4dc1-a9a6-c80eba9cb533"
-H "Content-Type: application/json" -d '{
"value":"VIP"
}'
'https://api.socialstudio.radian6.com/v3/authors/36221001/tags/6265'
14
Authors Retrieve Authors
Retrieve Authors
This method retrieves the specified author.
/v3/authors/{id}
HTTP method
GET
Request Parameters
Sample Request
GET /v3/authors/{id}
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "2184",
"title": "R6APITestUser1",
"externalId": "429245766",
"externalLegacyId": null,
"authorFullName": "API 1 APIQE ",
"avatar": "http://pbs.twimg.com/profile_images/1815149549/b-410745-
animated_dog_normal.jpg",
"authorTags": [
{
"id": "13434",
"value": "Sample tag"
}
],
"authorComments": [
{
"id": "454545",
"value": "Sample note"
}
15
Authors Create Author Tag
],
"bio": "Sample bio ",
"verified": false,
"authorData": {
"blogId": "62550515"
}
}
],
"meta": {
"totalCount": 1
}
}
HTTP Method
POST
Request Parameters
16
Authors Create Author Tag
JSON Parameters
*value* - string value including the tag value to apply to the author
Sample Request
The call below passes a single tag to the author.
POST /v3/authors/1/tags
{
"value":"vino"
}
Sample Response
A successful call returns a 201 code with a Location header for the location of the new tag and an ID value. If you pass an array of tags,
that response will include a Location header and an array of IDs for the tags.
[
{
"id": "154"
},
{
"id": "155"
},
{
"id": "156"
}
]
A call including an invalid JSON object will return a 400 code. Ensure you correctly formed the JSON object.
A call referencing an invalid author ID will return a 404 code. Ensure you referenced the correct author value.
A duplicate tag returns a 409 code. Ensure you include a unique tag value in your call.
17
Authors Delete Author Tag
HTTP Method
DELETE
Request Parameters
Sample Request
DELETE /v3/authors/12345/tags/123
Sample Response
A successful call returns a 204 code.
A call referencing an invalid author ID or tag ID will return a 404 code. Ensure you referenced the correct values.
A internal error during creation returns a 500 Internal Server Error. Try your create call again at a later time.
HTTP Method
DELETE
18
Authors Create Comment for Author
Request Parameters
Sample Request
DELETE /v3/authors/12345/tags
Sample Response
A successful call returns a 204 code.
A call that could not remove all tags from an author returns a 400 code.
A call referencing an invalid author ID will return a 404 code. Ensure you referenced the correct author value.
A internal error during creation returns a 500 Internal Server Error. Try your create call again at a later time.
HTTP Method
POST
Request Parameters
Sample Request
POST /v3/authors/{id}/comments
{
19
Authors Retrieve Comment for Author
Sample Response
A successful call returns a 201 code with the applicable Location header.
A call including an invalid JSON object returns a 400 code.
A call including an invalid author returns a 404 code.
A call encountering an internal server error while adding the comment returns a 500 code.
HTTP Method
GET
Request Parameters
Sample Request
GET /v3/authors/{id}/comments
Sample Request
A successful call returns the following response:
{
"data" : [
{
"id": "2751",
"authorId": 53,
20
Authors Delete Author Comment
Sample Response
A call referencing a nonexistent author returns a 404 error.
A call that encounters an internal error while retrieving the author returns a 500 error.
HTTP Method
DELETE
Request Parameters
21
Authors Delete Author Comment
Sample Request
DELETE /v3/authors/{id}/comments/{commentId}
Sample Response
A successful call returns a 204 No Content code.
A call including an invalid author, a previously deleted note, or a nonexistent note returns a 404 code.
A call encountering an internal server error while deleting the comment returns a 500 code.
22
CHAPTER 4 Clients
In this chapter ... Use the Clients endpoint to retrieve basic information about the Social Studio organization (such as org
name, ID, timezone, and language).
Retrieve Clients
cURL Example
curl -X GET -H "access_token: 82200099-7799-4023-b76d-11bb7c941bf1"
'https://api.socialstudio.radian6.com/v3/clients'
23
Clients Retrieve Clients
Retrieve Clients
This method retrieves the Social Studio organization for your company. At this time, this call returns only the client for the authenticated
user.
/v3/clients
HTTP method
GET
Request Parameters
None
Sample Request
GET /v3/clients
Sample Response
{
"data": [
{
"id": "1",
"title": "Radian6 Technologies",
"email": null,
"timeZone": "America/Halifax",
"languageId": 1,
"sessionTimeoutMillis": 28800000,
"aviaryEnabled": false,
"apiSelfServeEnabled": true
}
],
"meta": {
"totalCount": 1
}
}
24
Clients Retrieve Clients
25
CHAPTER 5 Users
In this chapter ... Use the Users endpoint to manage basic aspects of Social Studio user accounts.
Retrieve Users
Retrieve User Retrieve a User
Create User
Update User GET /v3/users/{id}
Reset Password
Modify Password
cURL Example
curl -X GET -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e"
'https://api.socialstudio.radian6.com/v3/users/me'
Create a User
POST /v3/users
cURL Example
curl -X POST -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e"
-H "Content-Type: application/json" -d ' {
"title": "API User",
"username": "APIUser",
"displayName": "API User",
"email": "email@salesforce.com",
"timeZone": "Europe/London",
"enabled": true,
"avatarURL": null,
"userRoleId": 6,
"orgRoleId": 1,
"languageId": 1,
"clientId": 1
}' 'https://api.socialstudio.radian6.com/v3/users'
26
Users Retrieve Users
Retrieve Users
This method retrieves information for all users within an account
/v3/users
HTTP Method
GET
Request Parameters
None
Query Parameters
*q* - string value including characters to search for in title (minimum of 3 characters)
*enabled* - boolean value indicating whether to retrieve only active users
*true* - string value indicating return only active users
*false* - string value indicating return all users
*limit* - integer value indicating number of results to return (defaults to 100,000)
*offset* - integer value indicating result to start with (defaults to 0)
Sample Request
GET /v3/users
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "3339",
"title": "Admin",
"username": "admin",
"displayName": "Admin",
"email": "testuser@example.com",
"timeZone": "America/Goose_Bay",
"enabled": true,
"orgRoleId": 1,
"languageId": 1,
"createdDate": "2014-05-09T03:00:00Z",
"internalUserAvatarUrl": null,
"userAvatarUrl": null,
"clientId": 1
},
27
Users Retrieve User
],
"meta": {
"totalCount" : 52
}
}
Retrieve User
This method retrieves information for a specified user within an account
/v3/users/{id}
HTTP Method
GET
Request Parameters
*id* - integer value indicating unique ID for user (you may also use the *me* shorthand
in place of this value)
Sample Request
GET /v3/users/{id}
Sample Response
A successful call returns the following response:
{
"data": [
{
28
Users Create User
"id": "3339",
"title": "Admin",
"username": "admin",
"displayName": "Admin",
"email": "testuser@example.com",
"timeZone": "America/Goose_Bay",
"enabled": true,
"orgRoleId": 1,
"languageId": 1,
"createdDate": "2014-05-09T03:00:00Z",
"internalUserAvatarUrl": null,
"userAvatarUrl": null,
"clientId": 1
},
],
"meta": {
"totalCount" : 1
}
}
Create User
This method creates a new user within a Social Studio tenant.
/v3/users
HTTP Method
POST
Request Parameters
None
29
Users Create User
JSON Parameters
Sample Request
POST /v3/users
{
"username": "Matt.Jones@example.com",
"displayName": "Matt Jones",
"email": "Matt.Jones@example.com",
"timeZone": "Europe/London",
"enabled": true,
"avatarURL":
"http://a0.twimg.com/profile_images/1284202467/laptop-vector-model-122171296611479Nq0_normal.png",
"languageId": 1,
"internalUserAvatarUrl":
"http://socialstudio.s3.amazonaws.com/avatars/ad816b59936d93dc3ec36a43e15cbb8c"
}
Sample Response
A successful call returns a 201 code, indicating a successful creation.
A internal server error occuring during the call returns a 500 code. Try your call again later.
30
Users Update User
Update User
This method retrieves information for a specified user within a Social Studio tenant.
/v3/users/{id}
HTTP Method
PUT
Request Parameters
*id* - integer value indicating unique ID for user (you may also use the *me* shorthand
in place of this value)
JSON Parameters
Sample Request
PUT /v3/users/{id}
{
"username": "Matt.Jones@example.com",
"displayName": "Matt Jones",
"email": "Matt.Jones@example.com",
"timeZone": "Europe/London",
31
Users Reset Password
"enabled": true,
"avatarURL":
"http://a0.twimg.com/profile_images/1284202467/laptop-vector-model-122171296611479Nq0_normal.png",
"languageId": 1,
"internalUserAvatarUrl":
"http://socialstudio.s3.amazonaws.com/avatars/ad816b59936d93dc3ec36a43e15cbb8c"
}
Sample Response
A successful call returns a 204 No Content code, indicating a successful update.
A call referencing an invalid ID returns a 404 Not Found code. Ensure your call uses the correct ID.
A internal server error occuring during the call returns a 500 code. Try your call again later.
Reset Password
This method resets the password for an internal user account. A successful call also sends an email message (from support@radian6.com)
containing a link the user can click to set a new password value. This call requires administrative privileges.
/v3/users/{userId}/password?action=reset
HTTP Method
POST
Request Parameters
*userId* - integer value indicating unique ID for user (also accepts me shorthard)
Sample Request
POST /v3/users/12345/password?action=reset
Sample Response
A successful call returns a 204 No Content code, indicating a successful update.
A call referencing an invalid ID returns a 404 Not Found code. Ensure your call uses the correct ID.
A internal server error occurring during the call returns a 500 code. Try your call again later.
32
Users Modify Password
Modify Password
This method triggers a password reset operation for a user
/users/{id}/password
HTTP Method
POST
Request Parameters
None
Sample Request
POST /users/1/password?action=change
33
CHAPTER 6 Workspaces
In this chapter ... Workspaces collect resources to support multiple social teams across a brand or regions. Workspaces
also support collaboration with agencies while controlling application access. This section helps you
Retrieve Workspaces create a workspace and add resources.
Retrieve Workspace
Create Workspace
Update Workspace
Get Workspaces
Delete Workspace
Before you create a new workspace, perform a retrieve on your existing workspaces to ensure one does
Create Workspace not already exist that would fit your needs:
Resources
GET /v1/workspaces
Delete Workspace
Resources
cURL Example
curl -X GET -H "access_token: ce5c9c9f-470b-4efc-8254-db8649ed77bd"
-H "Content-Type: application/json"
'https://api.socialstudio.radian6.com/v1/workspaces'
Create Workspaces
Add a new workspace using the following call:
POST /v1/workspaces
cURL Examples
curl -X POST -H "access_token: ce5c9c9f-470b-4efc-8254-db8649ed77bd"
-H "Content-Type: application/json" -d '{
"name": "Workspace Name",
"description": "This workspace is for Campaign X",
"logo": "/Pictures/workspace logo.png"
}' 'https://api.socialstudio.radian6.com/v1/workspaces'
34
Workspaces
cURL Examples
curl -X POST -H "access_token: your_access_token" -H "Content-Type:
application/json" -d '{
"workspace_id": "b8e4c9c4-9e3c-411f-ae80-7c2b3d6e2ab0",
"resource_type": "user",
"resource_id": "79799125",
"access": "contributor"
}' 'https://api.socialstudio.radian6.com/v1/workspaces'
35
Workspaces Retrieve Workspaces
Retrieve Workspaces
This method retrieves a paginated list of workspaces within the Social Studio organization.
/v1/workspaces
HTTP Method
GET
Request Parameters
*page* - integer value indicating which page to display from retrieved data (default of
1)
*perpage* - integer value indicating how many results to include in a page (value must
be greater than 1 and not exceed 25, default of 10)
*search* - string value indicating which characters to search for at start of workspace
name (only at beginning, not within name strings)
*orderBy* - string value indicating order of returned results:
*name* - name of workspace (default)
*updated* - last modified timestamp
*order* - string value indicating display direction for retrieved content:
*desc* - descending order
*asc* - ascending order (default)
*user* - string value identifying workspace user. This parameter defaults to *default*
value. The call ignores other values and returns an error for non-admin users.
*isMember* - boolean value that pairs with *user* parameter to return on workspaces with
an assigned role for the user.
*visibility* - string value indicating whether a workspace appears to all users:
*private* - does not appear (default)
*public* - does appear
*include* - comma-separated string values of additional information to include:
*permissions* - string value containing user permissions for the workspace
*defaultPublishProfile* - string value of default publish profile for workspace
*view* - can view social assets and posts
*edit_content* - same as *view* and can create content (such as posts)
*admin* - same as *edit_content* and can perform admin actions on workspace
*delete* - can delete workspace
*membercount* - string value containing total number of users for workspace
*socialassetcount* - string value containing total number of social assets for workspace
36
Workspaces Retrieve Workspaces
Sample Request
The call below retrieves the workplaces within an account:
GET /v1/workspaces?visibility=public&search=salesforce&include=permissions,membercount
Sample Response
A successful call returns the following response:
{
"status": true,
"response": [
{
"name": "workspace A",
"id": "46e66860-25fe-11e3-b1a1-168170973bd5",
"visibility": "public",
"logo": "a_logo.png",
"description": "A great workspace",
"group_id": "123"
},
{
"name": "Workspace B",
"id": "46f96860-25fe-11e3-b1a1-168170973bd5",
"visibility": "public",
"logo": "b_logo.png",
"description": "B successful workspace",
"group_id": "234"
}
],
"meta": {
"total": 400,
"page": 2
"perpage": 2,
"current": "{HOST}/v1/workspaces?page=2&perpage=2&visibility=public",
"prev": "{HOST}/v1/workspaces?page=1&perpage=2&visibility=public",
"next": "{HOST}/v1/workspaces?page=3&perpage=2&visibility=public"
}
}
Error Responses
A call finding no workspaces returns the following response:
{
"status": true,
"response": [],
"meta": {
"total": 0,
"page": 1,
"perpage": 10,
37
Workspaces Retrieve Workspace
"current": "{HOST}/v1/workspaces?page=1&perpage=10&visibility=public",
"prev": "",
"next": ""
}
}
{
"status": false,
"response": {
"errors": [
{
"code": "error.bad_request",
"message": ""
}
]
},
"meta": []
}
Retrieve Workspace
This method retrieves a single workspace within the Social Studio organization.
/v1/workspaces/{id}
HTTP Method
GET
Request Parameters
38
Workspaces Retrieve Workspace
Query Parameters
Sample Request
The call below retrieves the specified workplace:
GET /v1/workspaces/46e66860-25fe-11e3-b1a1-168170973bd5?include=permissions,membercount
Sample Response
A successful call returns the following response:
{
"status": true,
"response": {
"name": "A new workspace for the system",
"id": "46e66860-25fe-11e3-b1a1-168170973bd5",
"visibility": "private",
"logo": "workspace_logo.png",
"description": "A brand new workspace!",
"group_id": "123"
},
"meta": []
}
A call returning information on a private workspace the user cannot access returns the following response:
{
"status": true,
"response": {
"name": "PRIVATE WORKSPACE",
"id": "46e66860-25fe-11e3-b1a1-168170973bd5",
"visibility": "private"
},
"meta": []
}
39
Workspaces Retrieve Workspace
"id": "46e66860-25fe-11e3-b1a1-168170973bd5",
"visibility": "public",
"name": "A new workspace for the system",
"logo": "",
"description": "",
"group_id": "123",
"permissions": [
"view",
"edit_content",
"admin",
"delete"
],
"membercount": 100,
"socialassetcount": 50,
"engage": [
"view",
"edit"
]
},
"meta": []
}
Error Responses
A call referencing an invalid workspace returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.not_found",
"message": ""
}
]
},
"meta": []
}
40
Workspaces Retrieve Workspace
"meta": []
}
{
"status": true,
"response": {
"id": "46e66860-25fe-11e3-b1a1-168170973bd5",
"visibility": "public",
"name": "A new workspace for the system",
"logo": "",
"description": "",
"group_id": "123",
"permissions": [
"view",
"edit_content",
"admin",
"delete"
],
"membercount": 100,
"socialassetcount": 50,
"engage": [
"view",
"edit"
]
},
"meta": []
}
*view*
*edit_content*
*admin*
*delete*
*membercount* - integer value including number of worksapce members
*socialassetcount* - integer value including number of worksapce members
*engage* - array of actions associated with engage functions in workspace
*view*
*"edit*
41
Workspaces Create Workspace
Create Workspace
This method creates a workspace within a Social Studio organization.
/v1/workspaces
HTTP Method
POST
Request Parameters
*name* - string value containing name of new workspace (required). This value includes a
maximum of 255 characters. The call removes leading and trailing whitespaces. The call
replaces multiple consecutive whitespaces with a single whitespace.
*visibility* - string value indicating whether a workspace appears to all users:
*private* - does not appear (default)
*public* - does appear
*description* - string value containing text describing the new workspace (defaults to
empty string)
*logo* - string value indicating the location of a workspace image file (defaults to empty
string)
Sample Request
The call below creates a new piece of shared content with the specified message:
POST -d "name=A new workspace for the system" -d "visibility=private" -d
"logo=workspace_logo.png" -d "description=A brand new workspace." {HOST}/v1/workspaces
Sample Response
A successful call returns the following response:
{
"status": true,
"response": {
"id": "95b75fac-0453-11e3-8d6f-168170973bd5"
},
"meta": []
}
42
Workspaces Update Workspace
Error Responses
An unsuccessful call due to a duplicate name returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.conflict",
"message": ""
}
]
},
"meta": []
}
Update Workspace
This method updates a workspace within a Social Studio organization.
/v1/workspaces
HTTP Method
PATCH
Request Parameters
*id* - string value containing the ID value for the workspace (required)
43
Workspaces Update Workspace
Query Parameters
*name* - string value containing name of new workspace. This value includes a maximum of
255 characters. The call removes leading and trailing whitespaces. The call replaces
multiple consecutive whitespaces with a single whitespace.
*visibility* - string value indicating whether a workspace appears to all users:
*private* - does not appear (default)
*public* - does appear
*description* - string value containing text describing the new workspace (defaults to
empty string)
*logo* - string value indicating the location of a workspace image file (defaults to empty
string)
Sample Request
The call below creates a new piece of shared content with the specified message:
PATCH -d "visibility=private" {HOST}/v1/workspaces/46e66860-25fe-11e3-b1a1-168170973bd5
Sample Response
A successful call returns the following response:
{
"status": true,
"response": true,
"meta": []
}
Error Responses
An call referencing a nonexistent workspace returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.not.found",
"message": ""
}
]
},
"meta": []
}
44
Workspaces Delete Workspace
Delete Workspace
This method deletes a workspace within the Social Studio organization. This process results in the loss of any scheduled posts.
/v1/workspaces/{id}
HTTP Method
DELETE
Request Parameters
Sample Request
The call below deletes the workspace and all associated content.
DELETE {HOST}/v1/workspaces/46e66860-25fe-11e3-b1a1-168170973bd5
45
Workspaces Delete Workspace
Sample Response
A successful call returns the following response:
{
"status": true,
"response": true,
"meta": []
}
Error Responses
An call referencing a nonexistent workspace returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.not.found",
"message": ""
}
]
},
"meta": []
}
46
Workspaces Create Workspace Resources
"meta": []
}
HTTP Method
POST
Request Parameters
None
JSON Parameters
Each JSON payload includes the resource type:
*topic_profile*
*engage_macro*
*template*
*social_property*
*user*
*publish_macro*
*resource_id* - string value containing identifier for the workspace resource
Sample Request
The call below creates a new piece of shared content with the specified message:
POST /v1/workspaceresources
{
47
Workspaces Delete Workspace Resources
"workspace_id": "44dfccf0-ed00-4988-a256-0913281dcb89",
"resource_type": "topic_profile",
"resource_id": "19212"
}
Sample Response
A successful call returns the following response:
{
"status": true,
"response": {
"resource_type": "topic_profile",
"resource_id": "19212",
"workspace_group_id": "8152"
},
"meta": []
}
HTTP Method
DELETE
Request Parameters
None
48
Workspaces Delete Workspace Resources
JSON Parameters
Each JSON payload includes information on the shared content:
Sample Request
The call below creates a new piece of shared content with the specified message:
DELETE /v1/workspaceresources
{
"workspace_id": "44dfccf0-ed00-4988-a256-0913281dcb89",
"resource_type": "topic_profile",
"resource_id": "19212"
}
Sample Response
A successful call returns the following response:
{
"status": true,
"response": {
"resource_type": "topic_profile",
"resource_id": "19212",
"workspace_group_id": "8152"
},
"meta": []
}
49
CHAPTER 7 Imported Posts
In this chapter ... Use this endpoint to retrieve all brand posts and associated metrics. These posts could include any posts
created within Social Studio or imported to Social Studio after posting on the social network itself. Make
Retrieve Posts & sure to include the specific metric parameters you want returned for the posts.
Metrics
cURL Example
curl -X POST -H "access_token: your_access_token" -H "Content-Type:
application/json"
'https://api.socialstudio.radian6.com/v1/importedposts?startDate=1136500800&endDate=1437105599&metrics=comments'
50
Imported Posts Retrieve Posts & Metrics
HTTP Method
GET
Request Parameters
None
Query Parameters
51
Imported Posts Retrieve Posts & Metrics
*favorites*
*link_clicks*
*engagement*
*engagement_rate*
*linkedin*
*likes*
*comments*
*link_clicks*
*engagement*
*gplus*
*plusone*
*reshares*
*comments*
*link_clicks*
*engagement*
*youtube*
*views*
*likes*
*dislikes*
*comments*
*link_clicks*
*engagement*
*instagram*
*likes*
*comments*
*pinterest*
*likes*
*comments*
*repins*
*link_clicks*
*labels* - string value (in a comma-delimited list) indicating labels to use in filter
*type* - string value indicating media type to use in filter
*orderBy* - string value indicating parameter used to sort results (defaults to date)
*order* - string value indicating display direction for retrieved content (defaults to
DESC):
*DESC* - descending order (default)
*ASC* - ascending order
*page* - integer value indicating which page to display from retreived data (defaults to
1)
*perpage* - integer value indicating how many results to include in a page (defaults to
10)
*filter* - string value indicating publish status of post (defaults to unpublished)
Sample Request
The call below retrieves all imported posts from a specified workspace:
GET /v1/importedposts?workspace=1
52
Imported Posts Retrieve Posts & Metrics
The call below retrieves all imported Facebook posts from a specified workspace:
GET /v1/importedposts?workspace=1&network=facebook
The call below retrieves all imported Facebook posts from a specified workspace with specified metrics:
GET /v1/importedposts?workspace=1&network=facebook&metrics=likes,comments
The call below retrieves all imported Facebook posts from a specified workspace with specified metrics:
GET /v1/importedposts?workspace=1&network=facebook&metrics=likes,comments&orderBy=comments
Sample Response
Each imported post includes the following properties:
A successful call returns posts from all networks in last seven days in descending order:
{
"status": true,
"response": [
{
"id": "35db3b27-edd5-4d35-8ef7-574b0f483524",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
53
Imported Posts Retrieve Posts & Metrics
"assets": {
"id": 46,
"created": "2013-08-12T10:48:28-0400",
"metadata": "{\"link_type\":\"link\",\"title\":\"CRM and Cloud Computing
To Grow Your Business -
Salesforce.com\",\"caption\":\"http://Salesforce.com\",\"description\":\"You can change
stuff
here\",\"images\":[\"http://www.sfdcstatic.com/common/assets/img/logo-company.png\"],\"image_index\":0,\"thumbnail\":true,\"share_link\":false,\"url\":\"http://Salesforce.com\",\"video_src\":null,\"type\":\"link\"}",
"post_id": "35db3b27-edd5-4d35-8ef7-574b0f483524",
"type": 3,
"updated": "2013-08-12T10:48:28-0400",
"url": "http://Salesforce.com"
},
"date": "2013-08-13 09:45:03",
"message": "Salesforce.com is cool!",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234
},
{
"id": "b93ab12e-37cd-4344-bffa-3a59f5053580",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
"assets": [ ],
"date": "2013-08-12 15:29:40",
"message": "yahoo.com",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234
},
{
"id": "9bc25322-49ca-4b9c-ae81-20ff1b593edf",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
"assets": {
"id": 47,
"created": "2013-08-12T10:48:29-0400",
"metadata": "{\"link_type\":\"link\",\"title\":\"CRM and Cloud Computing
To Grow Your Business -
Salesforce.com\",\"caption\":\"http://Salesforce.com\",\"description\":\"You can change
stuff
here\",\"images\":[\"http://www.sfdcstatic.com/common/assets/img/logo-company.png\"],\"image_index\":0,\"thumbnail\":true,\"share_link\":false,\"url\":\"http://Salesforce.com\",\"video_src\":null,\"type\":\"link\"}",
"post_id": "9bc25322-49ca-4b9c-ae81-20ff1b593edf",
"type": 3,
54
Imported Posts Retrieve Posts & Metrics
"updated": "2013-08-12T10:48:29-0400",
"url": "http://Salesforce.com"
},
"date": "2013-08-12 09:45:03",
"message": "Salesforce.com is cool!",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234
}
...
],
"meta": {
"total": 6,
"perpage": 10,
"current": 1,
"prev": "",
"next": ""
}
}
A successful call returns posts from Facebook in last seven days in descending order:
{
"status": true,
"response": [
{
"id": "35db3b27-edd5-4d35-8ef7-574b0f483524",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
"assets": {
"id": 46,
"created": "2013-08-12T10:48:28-0400",
"metadata": "{\"link_type\":\"link\",\"title\":\"CRM and Cloud Computing
To Grow Your Business -
Salesforce.com\",\"caption\":\"http://Salesforce.com\",\"description\":\"You can change
stuff
here\",\"images\":[\"http://www.sfdcstatic.com/common/assets/img/logo-company.png\"],\"image_index\":0,\"thumbnail\":true,\"share_link\":false,\"url\":\"http://Salesforce.com\",\"video_src\":null,\"type\":\"link\"}",
"post_id": "35db3b27-edd5-4d35-8ef7-574b0f483524",
"type": 3,
"updated": "2013-08-12T10:48:28-0400",
"url": "http://Salesforce.com"
},
"date": "2013-08-13 09:45:03",
"message": "Salesforce.com is cool!",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234
55
Imported Posts Retrieve Posts & Metrics
},
{
"id": "9bc25322-49ca-4b9c-ae81-20ff1b593edf",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
"assets": {
"id": 47,
"created": "2013-08-12 10:48:29",
"metadata": "{\"link_type\":\"link\",\"title\":\"CRM and Cloud Computing
To Grow Your Business -
Salesforce.com\",\"caption\":\"http://Salesforce.com\",\"description\":\"You can change
stuff
here\",\"images\":[\"http://www.sfdcstatic.com/common/assets/img/logo-company.png\"],\"image_index\":0,\"thumbnail\":true,\"share_link\":false,\"url\":\"http://Salesforce.com\",\"video_src\":null,\"type\":\"link\"}",
"post_id": "9bc25322-49ca-4b9c-ae81-20ff1b593edf",
"type": 3,
"updated": "2013-08-12T10:48:29-0400",
"url": "http://Salesforce.com"
},
"date": "2013-08-12 09:45:03",
"message": "Salesforce.com is cool!",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234
}
...
],
"meta": {
"total": 16,
"perpage": 10,
"current": 1,
"prev": "",
"next": ""
}
}
A successful call returns posts from Facebook in last seven days in descending order with metrics:
{
"status": true,
"response": [
{
"id": "35db3b27-edd5-4d35-8ef7-574b0f483524",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
"assets": {
"id": 46,
"created": "2013-08-12T10:48:28-0400",
"metadata": "{\"link_type\":\"link\",\"title\":\"CRM and Cloud Computing
To Grow Your Business -
56
Imported Posts Retrieve Posts & Metrics
"post_id": "35db3b27-edd5-4d35-8ef7-574b0f483524",
"type": 3,
"updated": "2013-08-12T10:48:28-0400",
"url": "http://Salesforce.com"
},
"date": "2013-08-13 09:45:03",
"message": "Salesforce.com is cool!",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234,
"metrics": {
"likes": 300,
"comments": 400
}
},
{
"id": "9bc25322-49ca-4b9c-ae81-20ff1b593edf",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
"assets": {
"id": 47,
"created": "2013-08-12T10:48:29-0400",
"metadata": "{\"link_type\":\"link\",\"title\":\"CRM and Cloud Computing
To Grow Your Business -
Salesforce.com\",\"caption\":\"http://Salesforce.com\",\"description\":\"You can change
stuff
here\",\"images\":[\"http://www.sfdcstatic.com/common/assets/img/logo-company.png\"],\"image_index\":0,\"thumbnail\":true,\"share_link\":false,\"url\":\"http://Salesforce.com\",\"video_src\":null,\"type\":\"link\"}",
"post_id": "9bc25322-49ca-4b9c-ae81-20ff1b593edf",
"type": 3,
"updated": "2013-08-12T10:48:29-0400",
"url": "http://Salesforce.com"
},
"date": "2013-08-12 09:45:03",
"message": "Salesforce.com is cool!",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234,
"metrics": {
"likes": 100,
"comments": 800
}
}
57
Imported Posts Retrieve Posts & Metrics
...
],
"meta": {
"total": 16,
"perpage": 10,
"current": 1,
"prev": "",
"next": ""
}
}
A successful call returns posts from Facebook in last seven days sorted by comments in descending order with metrics:
{
"status": true,
"response": [
{
"id": "35db3b27-edd5-4d35-8ef7-574b0f483524",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
"assets": {
"id": 46,
"created": "2013-08-12T10:48:28-0400",
"metadata": "{\"link_type\":\"link\",\"title\":\"CRM and Cloud Computing
To Grow Your Business -
Salesforce.com\",\"caption\":\"http://Salesforce.com\",\"description\":\"You can change
stuff
here\",\"images\":[\"http://www.sfdcstatic.com/common/assets/img/logo-company.png\"],\"image_index\":0,\"thumbnail\":true,\"share_link\":false,\"url\":\"http://Salesforce.com\",\"video_src\":null,\"type\":\"link\"}",
"post_id": "35db3b27-edd5-4d35-8ef7-574b0f483524",
"type": 3,
"updated": "2013-08-12T10:48:28-0400",
"url": "http://Salesforce.com"
},
"date": "2013-08-13 09:45:03",
"message": "Salesforce.com is cool!",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234,
"metrics": {
"likes": 300,
"comments": 800
},
"blogPostId": 1234
},
{
"id": "9bc25322-49ca-4b9c-ae81-20ff1b593edf",
"socialAsset": "200012913364042",
"socialProperty": 8307,
"slug": "/Buddy-The-Dog/200012913364042",
"assets": {
58
Imported Posts Retrieve Posts & Metrics
"id": 47,
"created": "2013-08-12T10:48:29-0400",
"metadata": "{\"link_type\":\"link\",\"title\":\"CRM and Cloud Computing
To Grow Your Business -
Salesforce.com\",\"caption\":\"http://Salesforce.com\",\"description\":\"You can change
stuff
here\",\"images\":[\"http://www.sfdcstatic.com/common/assets/img/logo-company.png\"],\"image_index\":0,\"thumbnail\":true,\"share_link\":false,\"url\":\"http://Salesforce.com\",\"video_src\":null,\"type\":\"link\"}",
"post_id": "9bc25322-49ca-4b9c-ae81-20ff1b593edf",
"type": 3,
"updated": "2013-08-12T10:48:29-0400",
"url": "http://Salesforce.com"
},
"date": "2013-08-12 09:45:03",
"message": "Salesforce.com is cool!",
"network": "facebook",
"targeting": [ ],
"labels" : [ ],
"type": "status",
"socialAssetName": "Buddy - The Dog",
"blogPostId": 1234,
"metrics": {
"likes": 100,
"comments": 600
}
}
...
],
"meta": {
"total": 16,
"perpage": 10,
"current": 1,
"prev": "",
"next": ""
}
}
59
CHAPTER 8 Shared Content
In this chapter ... Share content across teams using this functionality. Agencies can also share content after finishing the
planning phase for your content. Create the content from an existing post, then share it to other
Retrieve Shared workspaces or send it to another tool (such as a content management system).
Content
Share & Unshare
Content Create Shared Content
Create Shared
Content Ensure you host the image before sharing it:
Archive & Unarchive POST /v1/clips
Shared Content
Delete Shared
Content cURL Example
curl -X POST -H "access_token: a133c435-dd3a-4727-8c07-08e09f0b1a97"
-H "Content-Type: application/json" -d '{
"message":"Message text",
"description":"Optional description about why I am sharing this
content to others",
"assets": [{"url":"http://www.foo.com/images/foo.png", "type":2,
"metadata":""}],
"workspaces": ["88c282e3-b33e-4109-bb86-9040c368bf75"],
"workspace_id": "b8e4c9c4-9e3c-411f-ae80-7c2b3d6e2ab0"
}' 'https://api.socialstudio.radian6.com/v1/clips'
cURL Example
curl -X POST -H "access_token: 67fbd2fa-c885-4c53-a383-9d4d18e1763b"
-H "Content-Type: application/json" -H -d '{
"post_id": "65fe0314-9737-4fd3-acd5-a7c1cf636b7a",
"message": "This duplicates that content from an existing post
60
Shared Content
cURL Example
curl -X DELETE -H "access_token: a133c435-dd3a-4727-8c07-08e09f0b1a97"
-H
'https://api.socialstudio.radian6.com/v1/clips/e15318fa-c194-45e1-99d3-05f39e103e0f'
cURL Example
curl -X POST -H "access_token: 67fbd2fa-c885-4c53-a383-9d4d18e1763b"
-H "Content-Type: application/json"
-d ''
'https://api.socialstudio.radian6.com/v1/clips/22a27159-832c-47f1-9313-5533dfe40a8d?action=archive'
61
Shared Content
cURL Example
curl -X POST -H "access_token: 67fbd2fa-c885-4c53-a383-9d4d18e1763b"
-H "Content-Type: application/json" -d '{
"workspaces": ["a0fd4ce7-af4c-48b1-b6e8-0cb4ce54b2fc",
"c2e918d2-4309-11e3-bb55-1cb63b08732c"]
}'
'https://api.socialstudio.radian6.com/v1/clips/22a27159-832c-47f1-9313-5533dfe40a8d?action=unshare'
62
Shared Content Retrieve Shared Content
HTTP Method
GET
Request Parameters
None
Query Parameters
*workspace* - string value indicating workspace from which to retrieve content (required)
*filter* - string value indicating which content to retrieve:
*all* - any content (default)
*owner* - any content owned by a specific owner
*shared* - any content shared for use
*include* - string value requesting additional information:
*metrics* - analytics information for specified content
*sort* - string value indicating order to display retrieved content:
*created* - sort by created date (default)
*avg_engagement* - sort by average number of engagement
*direction* - string value indicating display direction for retrieved content:
*desc* - descending order (default)
*asc* - ascending order
*page* - integer value indicating which page to display from retreived data (defaults to
1)
*perpage* - integer value indicating how many results to include in a page (defaults to
10)
Sample Request
The call below retrieves all clips from the specified workplace with analytics data:
GET /v1/clips?workspace=584d3ad3-2f7b-11e3-b8e3-168170973bd5&filter=all&include=metrics
63
Shared Content Retrieve Shared Content
Sample Response
A successful call requesting all clips with analytics data returns the following response:
{
"status": true,
"response": [
{
"id": "35543aba-18b2-4995-bb76-ea1132fe544a",
"source_type": "post",
"source_id": "93023aba-18b2-4995-bb76-ea1132fe544a",
"organization_id": "10567",
"archived": 0,
"deleted": 0,
"message": "Post message",
"description": "Clip comment",
"start_date": null,
"end_date": null,
"created": "2014-02-02 11:00:00",
"updated": "2014-02-03 11:00:00",
"assets": [
{
"url": "https://d2ee3wvl22m8i7.cloudfront.net/_blue.jpg",
"type": "2",
"metadata": null
}
],
"owner_workspace":
{
"id": "75443f9c-349b-4bfa-a124-b188d4a8719f",
"owner": "1",
"name": "Buddy - The Dog",
"logo": null
},
"shared_workspace_count": 0,
"shared_workspaces": [
{
"id": "adlskasdaf-dsafada",
"name": "workspace 1",
"logo": "http://image.jpg"
},
{
"id": "adlskasdaf-dsafada",
"name": "workspace 2",
"logo": "http://image.jpg"
}
],
"post_count": 19,
"metrics": {
"engagement": 354,
"average_engagement": 177,
"engagement_rate": {
"facebook": 1.4,
"twitter": 1.5
}
64
Shared Content Retrieve Shared Content
}
},
{
...
},
...
]
"meta": {
"total": 5,
"perpage": 10,
"current": 1,
"prev": "",
"next": "/clips?page=2&perpage=10"
}
}
A successful call for a specific piece of content returns the following response:
{
"status": true,
"response": {
"id": "35543aba-18b2-4995-bb76-ea1132fe544a",
"source_type": "post",
"source_id": "93023aba-18b2-4995-bb76-ea1132fe544a",
"organization_id": "10567",
"archived": 0,
"deleted": 0,
"message": "Post message",
"description": "Clip comment",
"start_date": null,
"end_date": null,
"created": "2014-02-02 11:00:00",
"updated": "2014-02-03 11:00:00",
"assets": [
{
"url": "https://d2ee3wvl22m8i7.cloudfront.net/_blue.jpg",
"type": "2",
"metadata": null
}
],
"owner_workspace":
{
"id": "75443f9c-349b-4bfa-a124-b188d4a8719f",
"owner": "1",
"name": "Buddy - The Dog",
"logo": null
},
"shared_workspace_count": 0,
"shared_workspaces": [
{
"id": "adlskasdaf-dsafada",
"name": "workspace 1",
"logo": "http://image.jpg"
},
{
65
Shared Content Retrieve Shared Content
"id": "adlskasdaf-dsafada",
"name": "workspace 2",
"logo": "http://image.jpg"
}
],
"post_count": 19,
"metrics": {
"engagement": 354,
"average_engagement": 177,
"engagement_rate": {
"facebook": 1.4,
"twitter": 1.5
}
}
},
"meta": []
}
66
Shared Content Share & Unshare Content
HTTP Method
POST
Request Parameters
JSON Parameters
*workspaces* - array of string value indicating the workspaces with which to share the
content
Sample Request
The call below shares the specified content:
POST v1/clips/35543aba-18b2-4995-bb76-ea1132fe544a?action=share
67
Shared Content Create Shared Content
Sample Response
A successful call returns the following response:
# HTTP 200 Success
{
"status": true,
"response": {},
"meta": {},
}
HTTP Method
POST
Request Parameters
None
JSON Parameters
Each JSON payload includes information on the shared content:
*message* - string value indicating the message to share (required). The JSON payload must
include a *message* value or an *assets* value. You can include both.
*assets* - string value indicating URL and type of content (required). The JSON payload
must include a *message* value or an *assets* value. You can include both.
*url* - string value indicating URL for content
*type* - integer value indicating the media type for the imported content:
*1* - MEDIA_TYPE_ALBUM
*2* - MEDIA_TYPE_LINK
*3* - MEDIA_TYPE_PHOTO
*4* - MEDIA_TYPE_STATUS
*5* - MEDIA_TYPE_VIDEO
*workspaces* - string value identifying the workspace in which you can access the content
68
Shared Content Create Shared Content
(required).
*workspace_id* - string value identifying owner of shared content (required). You can leave
this value blank.
*description* - string value containing text describing the shared content.
*post_id* - string value containing the GUID for the existing post containing the shared
content to link and use for performance reporting
*clip_id* - string value containing a GUID for a clip containing the shared content to
link and use for performance reporting
Sample Request
The call below creates a new piece of shared content with the specified message:
{
"message": "This is a test message",
"workspaces": ["c2e918d2-4309-11e3-bb55-1cb63b08732d"],
"workspace_id": "584d3ad3-2f7b-11e3-b8e3-168170973bd5"
}
The call below creates a new piece of shared content with the specified asset:
{
"assets": [{"url":"http://www.foo.com", "type":2}}],
"workspaces": ["c2e918d2-4309-11e3-bb55-1cb63b08732d"],
"workspace_id": "584d3ad3-2f7b-11e3-b8e3-168170973bd5"
}
The call below creates a new piece of shared content and shares it to the specified workspaces:
{
"message": "This is a test message",
"workspace_id": "584d3ad3-2f7b-11e3-b8e3-168170973bd5",
"description": "This is a test comment",
"assets": [{"url":"http://www.foo.com", "type":3,
"metadata":"{\"url\":\"http://www.foo.com\"}"}],
"workspaces": ["c2e918d2-4309-11e3-bb55-1cb63b08732d"]
}
The call below creates a new piece of shared content containing an image from an existing post:
{
"post_id": "82e6c061-2c5a-11e3-b1a1-168170973bd5"
"message": "This is a test message",
"workspace_id": "584d3ad3-2f7b-11e3-b8e3-168170973bd5",
"description": "This is a test comment",
"assets": [{"url":"http://www.foo.com/images/foo.png", "type":2}],
"workspaces": ["c2e918d2-4309-11e3-bb55-1cb63b08732d"]
}
The call below duplicate a piece of shared content containing an link from an existing clip:
{
"clip_id": "82e6c061-2c5a-11e3-b1a1-168170973bd5"
"message": "This is a test message",
"workspace_id": "584d3ad3-2f7b-11e3-b8e3-168170973bd5",
"description": "This is a test comment",
69
Shared Content Archive & Unarchive Shared Content
Sample Response
A successful call returns the following response:
# HTTP 201 Created
{
status: true,
response: {
id: "35543aba-18b2-4995-bb76-ea1132fe544a",
},
meta: {},
}
HTTP Method
POST
Request Parameters
70
Shared Content Delete Shared Content
Sample Request
The call below archives the specified content:
POST v1/clips/35543aba-18b2-4995-bb76-ea1132fe544a?action=archive
Sample Response
A successful call returns the following response:
# HTTP 200 Success
{
"status": true,
"response": {},
"meta": {},
}
HTTP Method
DELETE
Request Parameters
Sample Request
The call below deletes the specified content:
DELETE v1/clips/35543aba-18b2-4995-bb76-ea1132fe544a
71
Shared Content Delete Shared Content
Sample Response
A successful call returns the following response:
# HTTP 200 Success
{
"status": true,
"response": {},
"meta": {},
}
72
CHAPTER 9 Short URLs
In this chapter ... Short URLs allow nrands to manage URL shortening services within the suite. Currently, Social Studio
supports shortening and tracking clicks on links using the Bitly URL shortening service. Add your own
Retrieve Short URLs Bitly accounts in order to shorten links using your own vanity URLs and track clicks both within Bitly as
Retrieve Short URL well as within Social Studio. Link tracking only applies to links published via Social Studio.
Create Short URL
Delete Short URL
Add a Bitly Account
Add a Bitly account to a workspace using the following call:
POST /v1/shorturls
cURL Example
curl -X POST -H access_token: 418adb62-b49f46f7-be1e-c4d82c4b0fef
https://api.socialstudio.radian6.com/v1/shorturls?workspace=b8e4c9c49e3c411f-ae807c2b3d6e2ab0&accessToken={{bitlyToken}}
73
Short URLs Retrieve Short URLs
HTTP Method
GET
Request Parameters
None
Query Parameters
Sample Request
curl GET
'{HOST}/v1/shorturls?workspace=028e2d63-0914-11e3-8d6f-168170973bd5&page=2&perpage=2'
Sample Response
A successful call returns the folowing response:
{
"status": true,
"response": [
{
"customShortDomain": "gofi.gs ",
"id": "5239534f-0b58-11e3-8d6f-168170973bd5",
"login": "dummy",
"token": "thisisatestaccesstoken1"
},
74
Short URLs Retrieve Short URLs
{
"customShortDomain": "gofi.gs ",
"id": "9e9318c5-0c00-11e3-8441-168170973bd5",
"login": "dummy",
"token": "thisisatestaccesstoken2"
}
],
"meta": {
"total": 4,
"page": 1,
"perpage": 2,
"current":
"{HOST}/v1/shorturls?perpage=2&workspace=028e2d63-0914-11e3-8d6f-168170973bd5&page=1",
"prev": "",
"next":
"{HOST}/v1/shorturls?perpage=2&workspace=028e2d63-0914-11e3-8d6f-168170973bd5&page=2"
}
}
A call that returns no results based on the provided criteria includes the following response:
{
"status": true,
"response": [],
"meta": {
"total": 0,
"page": 1,
"perpage": 10,
"current":
"{HOST}/v1/shorturls?workspace=14a6e8f7-2c59-11e3-b1a1-168170973bd5&page=1",
"prev": "",
"next": ""
}
}
75
Short URLs Retrieve Short URL
"meta": []
}
HTTP Method
GET
Request Parameters
Sample Request
curl GET {HOST}/v1/shorturls/123
Sample Response
A successful call returns the folowing response:
{
"status": true,
"response": [
{
"customShortDomain": "www.cus.tom",
"id": "5239534f-0b58-11e3-8d6f-168170973bd5",
"login": "dummy",
"token": "thisisatestaccesstoken3"
}
],
}
76
Short URLs Create Short URL
*id* - string value indicating unique ID for Bitly account within workspace
*login* - string value indicating Bitly account user
*token* - string value indicating OAuth user token
A call that returns no results based on the provided criteria includes the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.not_found",
"message": "Could not find a shorturl with that id"
}
]
},
"meta": []
}
HTTP Method
POST
Request Parameters
None
77
Short URLs Create Short URL
JSON Parameters
*id* - string value including the unique identifier for the workspace
*accessToken* - string value containing the OAuth access token generated for accessing the
bit.ly account
Sample Request
curl -X POST -d "workspace=95b75fac-0453-11e3-8d6f-168170973bd5" -d
"accessToken=thisisatestaccesstoken" {HOST}/v1/shorturls
Sample Response
A successful call returns the following response:
{
"status":true,
"response":{
"id":"5239534f-0b58-11e3-8d6f-168170973bd5"
},
"meta":[]
}
*id* - string value indicating unique ID for the URL shortener within the workspace
A call referencing an account already associated with a workspace returns the following response:
{
"status":false,
"response":{
"errors":[
{
"code":"error.conflict",
"message":"this login already exists in the workspace."
}
]
},
"meta":[]
}
Ensure that you create a new account for the workspace or use an update call.
A call containing an invalid parameter returns the following response:
{
"status":false,
78
Short URLs Delete Short URL
"response":{
"errors":[
{
"code":"error.bad_request",
"message":"Workspace not found"
}
]
},
"meta":[]
}
HTTP Method
DELETE
Request Parameters
Sample Request
curl -X DELETE {HOST}/v1/shorturls/740a25ea-0b57-11e3-8d6f-168170973bd5
Sample Response
A successful call returns the following response:
{
"status":true,
"response":{
"id":"5239534f-0b58-11e3-8d6f-168170973bd5"
},
"meta":[]
}
79
Short URLs Delete Short URL
A call that returns no results based on the provided criteria includes the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.not_found",
"message": "Could not find a shorturl with that id"
}
]
},
"meta": []
}
80
CHAPTER 10 Publish Macros
In this chapter ... Publish Macros allow you to configure predefined metadata for several attributes for use (even
automatically applied) when creating a brand post within a workspace.
Retrieve Publish
Macros
Attributes refer to categories of metadata, such web analytics, publish labels, or social accounts.
Retrieve Publish
Macro Creating a Publish Macro
Retrieve Publish
Macro Attribute This example includes creating a new publish macro with attributes for web analytics tracking codes in
Create Publish Macro the Social Studio organization
Delete Publish Macro
POST /v3/publishprofiles
cURL Example
curl -X POST -H access_token: a78cabb9-c00e4f989127248003a7d9a1
-H Content-Type: application/json -d {
name: My Publish Profile 2.1,
webAnalytics: [
{
key : sample_key,
value : sample_value
},
{
key : sample_key2,
value : sample_value2
}
]
} https://api.socialstudio.radian6.com/v3/publishprofiles
After you create a publish macro, add it to a workspace to be used within the application. You can only
use publish macros within a single workspace. See /workspaceresources for more information on how
to add a publish macro to a workspace.
81
Publish Macros Retrieve Publish Macros
HTTP Method
GET
Request Parameters
None
Query Parameters
*workspace* - string value indicating the unique ID for the workspace from which to retrieve
publish macros (required)
*page* - integer value indicating which page to display from retreived data (defaults to
1)
*limit* - integer value indicating the number of results to display per page (defaults to
20)
*orderBy* - string value indicating parameter used to sort results (defaults to date)
*order* - string value indicating display order for retrieved content:
*desc* - descending order
*asc* - ascending order (default)
*search* - string value indicating charaters to search for in name, returns paginated
results from name matches
Sample Call
curl
'{HOST}/v3/publishProfiles?workspace=028e2d63-0914-11e3-8d6f-168170973bd5&page=2&limit=2'
Sample Response
A successful call returns the following response:
{
"publishProfiles": [
{
id: 000ca3cf-3ed1-4b7d-8253-0d50fe1e93fd,
82
Publish Macros Retrieve Publish Macros
"type": "publish",
"name": "My Publish Profile",
"description": "testing",
"owner": 6834,
"created": 'created_date',
"socialPropertyIds": '/v3/publishProfiles/:id/socialPropertyIds',
"youtubePlaylists": '/v3/publishProfiles/:id/youtubePlaylists',
"targetingIds": '/v3/publishProfiles/:id/targetingIds'
},
{
id: 000ca3cf-3ed1-4b7d-8253-0d50fe1e93fd,
"type": "publish",
"name": "My Publish Profile",
"description": "testing",
"owner": 6834,
"created": 'created_date',
"socialPropertyIds": '/v3/publishProfiles/:id/socialPropertyIds',
"targetingIds": '/v3/publishProfiles/:id/targetingIds'
}
],
"count": 4,
"next": "{HOST}/v3/publishProfiles?limit=2&workspace=:workspaceId&page=2"
}
83
Publish Macros Retrieve Publish Macro
HTTP Method
GET
Request Parameters
Sample Call
GET /v3/publishprofiles/740a25ea-0b57-11e3-8d6f-168170973bd5
Sample Response
A successful call returns the following response:
{
id: 740a25ea-0b57-11e3-8d6f-168170973bd5,
"type": "publish",
"name": "My Publish Profile",
"description": "testing",
"owner": 6834,
"created": 'created_date',
"socialPropertyIds": '/v3/publishProfiles/:id/socialPropertyIds',
"targetingIds": '/v3/publishProfiles/:id/targetingIds'
}
84
Publish Macros Retrieve Publish Macro Attribute
*targetingIds* - array of string values indicating the social network and the category to
target
HTTP Method
GET
Request Parameters
*id* - string value indicating unique identifier for publish macro (required)
*type* - string value indicating property to retrieve:
*targetingIds* - array of string values indicating the social network and the category
to target
*socialPropertyIds* - array of integer values indicating social properties associated
with publish macro
*webAnalytics* - array of key and value pairs indicating web analytical information
to include with publish macro
Sample Call
GET /v3/publishprofiles/740a25ea-0b57-11e3-8d6f-168170973bd5/targetingIds
Sample Response
A successful call for targeting IDs returns the following response:
{
"targetingIds": [
"li_geo_af.dz",
"li_geo_af.eg"
],
"count": 9,
"next":
"{HOST}/v3/publishProfiles/0151bc2e-ee3d-4108-b7cf-b3bb0d207b91/targetingIds&page=2"
}
85
Publish Macros Create Publish Macro
HTTP Method
POST
Request Parameters
None
86
Publish Macros Create Publish Macro
JSON Parameters
Sample Request
curl -X POST {HOST}/v3/publishprofiles
{
"name": "My Publish Profile",
"description": "My Publish Profile Description",
"socialPropertyIds": ['3211', '4567'],
"youtubePlaylists": [
{
"key" : "3211",
"value" : "11"
},
{
"key" : "3211",
"value" : "22"
}
],
"targetingIds": ['li_ag', 'fb_nj'],
"webAnalytics": [
{
"key" : "sample_key",
"value" : "sample_value"
},
{
"key" : "sample_key2",
"value" : "sample_value2"
}
]
}
87
Publish Macros Delete Publish Macro
Sample Response
A successful call returns an ID value for the newly created publish macro:
{
"id":"5239534f-0b58-11e3-8d6f-168170973bd5"
}
HTTP Method
DELETE
Request Parameters
Sample Call
curl -X DELETE {HOST}/v3/publishprofiles/740a25ea-0b57-11e3-8d6f-168170973bd5
Sample Response
A successful call returns the following response:
{
true
}
88
Publish Macros Delete Publish Macro
A call from a user without permission to remove the publish macro returns the following response:
{
"status": "403",
"code": "error.FORBIDDEN",
"message": "Unauthorized to view profile"
}
89
CHAPTER 11 Approval Rules
In this chapter ... Approval rules gate actions (such as publishing a post) until certain individuals provide approval. Approval
rules are made up of three end-points:
Retrieve Approval
Rules
1. /v1/approvalflows
Retrieve Approval
2. /v1/approvalprerequisites
Rule 3. /v1/approvalprocedures
Create Approval Rule
Update Approval
Rule Sample Workflow
Delete Approval Rule
Retrieve Approval Approval rules define the name and priority of the rule. Prioritizing rules allows for multi-step approvals.
Rule Criteria For example, your rule could require that you first get approval from the Creative Team (rule 1), then get
Update Approval approval from the Legal OR from the Director of Social (rule 2).
Rule Criteria Define the criteria to trigger the rule within approval prerequisites (such as a user or social account in
Retrieve Approvers the workspace).
for a Rule Finally, approval pocedures define the approvers of the rule.
Update Approvers
for a Rule
Create a Rule
Lets start by creating a rule, including criteria (prerequisites) and approvers (procedures).
90
Approval Rules
{
"criteria": "submitter",
"operator": "equals",
"argument": "79799125
},
{
"criteria": "social account",
"operator": "equals",
"argument": 79798915"
},
{
"criteria": "social account",
"operator": "equals",
"argument": "{{social_property2}}"
}
],
"query": "(1 AND 2) OR ( 1 AND 3 )"
}'
'https://api.socialstudio.radian6.com/v1/approvalprerequisites/1d9217cf-40f4-4f8d-b465-9c4542209c20'
91
Approval Rules Retrieve Approval Rules
HTTP method
GET
Request Parameters
*ownerId* - identifies the workspace from which to retrieve the approval rules (required)
*ownerType* - identifies the object from which to retrieve the approval rules (required).
Possible values include the following:
*workspace*
*include* - idenfies optional additional information on the workflow. Possible values
include the following:
*prerequisite* - displays array value of rules within approval rule
*procedure* - returns array value of procedures
*approverCount* - returns integer value of approvers for approval rule
*criteriaCount* - returns integer value of criteria for approval rule
*page* - indicates optional number of pages to provide for results
*perpage* - indicates optional number of results to provide per page
Sample Request
GET /v1/approvalflows?ownerId=a272b824-bbf7-4a8c-bb1e-3d9695f3032a&ownerType=workspace
Sample Response
A successful call returns the following response:
{
"status": true,
"response": [
{
"id": "d460106d-794b-11e3-b8e3-168170973bd5",
"ownerId": "92ed3d44-5376-11e3-b8e3-168170973bd5",
"ownerType": "workspace",
"priority": 1,
"triggerAction": "publish",
"name": "My Approval Flow"
92
Approval Rules Retrieve Approval Rules
},
{
"id": "b64ee373-81f0-11e3-b8e3-168170973bd5",
"ownerId": "92ed3d44-5376-11e3-b8e3-168170973bd5",
"ownerType": "workspace",
"priority": 2,
"triggerAction": "publish",
"name": "My Other Approval Flow"
}
],
"meta": {
"total": 2,
"page": 1,
"perpage": 2,
"current":
"HOST/v1/approvalflows?workspace=92ed3d44-5376-11e3-b8e3-168170973bd5&page=1",
"prev": "",
"next": ""
}
}
93
Approval Rules Retrieve Approval Rules
],
"query": "1 and 2 and ( 3 or 4 )"
},
"procedure": [],
"meta": {
"criteriacount": "4"
"approvercount": "1"
}
}
],
"meta": {
"total": 1,
"page": 1,
"perpage": 1,
"current":
"HOST/v1/approvalflows?include=prerequisite,procedure&workspace=92ed3d44-5376-11e3-b8e3-168170973bd5&page=1",
"prev": "",
"next": ""
}
}
Error Responses
A call including an invalid or unsupported argument key and value pair returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.bad_request",
"message": "An invalid parameter/value was supplied"
}
]
},
"meta": []
}
94
Approval Rules Retrieve Approval Rule
HTTP method
GET
Request Parameters
95
Approval Rules Retrieve Approval Rule
Sample Request
GET
/v1/approvalflows?ownerId=a272b824-bbf7-4a8c-bb1e-3d9695f3032a&include=prerequisite,procedure,approvercount,criteriacount&hydrate=argument
Sample Response
A successful call returns the following response:
{
"status": true,
"response": {
"id": "d460106d-794b-11e3-b8e3-168170973bd5",
"ownerId": "92ed3d44-5376-11e3-b8e3-168170973bd5",
"ownerType": "workspace",
"priority": 171,
"triggerAction": "publish",
"name": "My Approval Flow"
}
}
96
Approval Rules Retrieve Approval Rule
"argument": "1a4ebec4-7b11-4d0a-aad3-4fc859ba8e28"
},
{
"criteria": "social account",
"operator": "equals",
"argument": "d5594362-829d-49c6-b317-6675b9a280f8"
}
],
"query": "( 1 and 2 ) or 3"
},
"procedure": {
"items": [
{
"criteria": "user",
"operator": "equals",
"argument": 6721,
"action": "approve"
},
{
"criteria": "user",
"operator": "equals",
"argument": 6721,
"action": "approve"
}
],
"query": "1 or 2"
},
"meta": {
"criteriacount": "4"
"approvercount": "1"
}
},
"meta": []
}
A successful call with include parameters and the hydrate argument returns the following response:
{
"status": true,
"response": {
"id": "e1c69b8c-6844-43fb-9eb3-0fe30dd92cc3",
"ownerId": "7046e184-0bd1-4c88-9255-642d8a212f31",
"ownerType": "workspace",
"priority": 7,
"triggerAction": "publish",
"name": "testworkflowapi",
"prerequisite": {
"items": [
{
"criteria": "submitter",
"operator": "equals",
"argument": {
"id": 6721,
"email": "pboddu@example.com",
"username": "pboddu@example.com",
97
Approval Rules Retrieve Approval Rule
"title": "PraveenBoddu",
"display_name": "PraveenBoddu",
"timezone": "GMT",
"enabled": true,
"updated": "2014-02-26T20:14:47+0000",
"organization_id": 10545
}
},
{
"criteria": "social account",
"operator": "equals",
"argument": null
},
{
"criteria": "social account",
"operator": "equals",
"argument": null
}
],
"query": "( 1 and 2 ) or 3"
},
"procedure": {
"items": [
{
"criteria": "user",
"operator": "equals",
"argument": {
"id": 6721,
"email": "pboddu@example.com",
"username": "pboddu@example.com",
"title": "PraveenBoddu",
"display_name": "PraveenBoddu",
"timezone": "GMT",
"enabled": true,
"updated": "2014-02-26T20:14:47+0000",
"organization_id": 10545
},
"action": "approve"
},
{
"criteria": "user",
"operator": "equals",
"argument": {
"id": 6721,
"email": "pboddu@example.com",
"username": "pboddu@example.com",
"title": "PraveenBoddu",
"display_name": "PraveenBoddu",
"timezone": "GMT",
"enabled": true,
"updated": "2014-02-26T20:14:47+0000",
"organization_id": 10545
},
"action": "approve"
98
Approval Rules Retrieve Approval Rule
}
],
"query": "1 or 2"
}
},
"meta": []
}
The information provided with the hydrate argument varies depending on the included entities.
Error Responses
An unsuccessful call will return one of the following error responses:
A call including an invalid or unsupported argument key and value pair returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.bad_request",
"message": "An invalid parameter/value was supplied"
}
]
},
"meta": []
}
99
Approval Rules Create Approval Rule
}
]
},
"meta": []
}
Ensure that you include the proper authentication with your call.
HTTP method
POST
Request Parameters
None
Query Parameters
100
Approval Rules Create Approval Rule
Sample Request
POST /v1/approvalflows HTTP/1.1
Host: HOST
Content-Type: application/x-www-form-urlencoded
trigger=publish&workspace=92ed3d44-5376-11e3-b8e3-168170973bd5&priority=9&name=My+Approval+Flow
Sample Response
A successful call returns the following response:
{
"status": true,
"response": {
"id": "d460106d-794b-11e3-b8e3-168170973bd5"
},
"meta": []
}
Error Responses
A call including an invalid or unsupported argument key and value pair returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.bad_request",
"message": "An invalid parameter/value was supplied"
}
]
},
"meta": []
}
101
Approval Rules Create Approval Rule
"errors": [
{
"code": "error.conflict",
"message": "A duplicate entry was detected when saving"
}
]
},
"meta": []
}
Missing Argument
A call not including an expected argument returns the following repsonse:
{
"status": false,
"response": {
"errors": [
{
"code": "error.bad_request",
"message": "An expected argument was not supplied"
}
]
},
"meta": []
}
Ensure that you include the proper authentication with your call.
A call attempting to view a non-existant workflow returns the following response:
{
"status": false,
"response": {
102
Approval Rules Update Approval Rule
"errors": [
{
"code": "error.forbidden",
"message": "Unathorized to view workspace"
}
]
},
"meta": []
}
Ensure that you include the proper authentication with your call.
HTTP Method
PATCH
Request Parameters
Sample Request
This sample request updates an approval rule with a priority of 2:
curl -X PATCH -d "priority=2" {HOST}/v1/approvalflows/d460106d-794b-11e3-b8e3-168170973bd5
Sample Response
A successful call returns the following response:
{
"status": true,
"response": true,
103
Approval Rules Update Approval Rule
"meta": []
}
Error Responses
An unsuccessful call will return one of the following responses:
A call including an invalid or unsupported argument key and value pair returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.bad_request",
"message": "An invalid parameter/value was supplied"
}
]
},
"meta": []
}
104
Approval Rules Delete Approval Rule
},
"meta": []
}
Ensure that you include the proper authentication with your call.
A call attempting to view a non-existant workflow returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.forbidden",
"message": "Unathorized to view workspace"
}
]
},
"meta": []
}
Ensure that you include the proper authentication with your call.
HTTP method
DELETE
Request Parameters
Sample Request
This sample request updates an approval rule with a priority of 2:
DELETE {HOST}/v1/approvalflows/d460106d-794b-11e3-b8e3-168170973bd5
105
Approval Rules Delete Approval Rule
Sample Response
A successful call returns the following response:
{
"status": true,
"response": true,
"meta": []
}
Error Responses
An unsuccessful call will return one of the following responses:
A call including an invalid or unsupported argument key and value pair returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.bad_request",
"message": "An invalid parameter/value was supplied"
}
]
},
"meta": []
}
106
Approval Rules Retrieve Approval Rule Criteria
"response": {
"errors": [
{
"code": "error.forbidden",
"message": "Unathorized to remove"
}
]
},
"meta": []
}
Ensure that you include the proper authentication with your call.
HTTP method
GET
Request Parameters
Query Parameters
*hydrate=argument - indicates that the call should return related entity information instead
of string or integer IDs
Sample Request
GET {HOST}/v1/approvalprerequisites/46e66860-25fe-11e3-b1a1-168170973bd5
GET {HOST}/v1/approvalprerequisites/46e66860-25fe-11e3-b1a1-168170973bd5&hydrate=argument
107
Approval Rules Retrieve Approval Rule Criteria
Sample Response
A successful call returns the following response:
{
"status": true,
"response": {
"items": [
{
"criteria": "submitter",
"operator": "equals",
"argument": 123123
},
{
"criteria": "social account",
"operator": "equals",
"argument": 83967
},
{
"criteria": "social account",
"operator": "equals",
"argument": 84975
}
],
"query": "(1 AND 2) OR ( 1 AND 3 )"
},
"meta": []
}
A successful call including the hydrate argument returns the following response:
{
"status": true,
"response": {
"items": [
{
"criteria": "submitter",
"operator": "equals",
"argument": {
"id": 7664,
"email": "qzhen@example.com",
"title": "Qzhen_10100",
"avatar_url": null,
"timezone": "GMT",
"enabled": true,
"updated": "2014-02-04T15:50:42+0000",
"organization_id": 10100,
"roles": 1
}
},
{
"criteria": "social account",
"operator": "in",
"argument": [
{
108
Approval Rules Retrieve Approval Rule Criteria
"name": "Exercise_Your_Voting_Right",
"id": "541a6b23-21ff-4c2c-9ed0-ca81da98d71d",
"network": "Facebook",
"asset": "519296421491495",
"socialaccount": 94093,
"tokenStatus": 1,
"metadata": {
"pageLogo":
"https://fbcdn-profile-a.akamaihd.net/static-ak/rsrc.php/v2/yg/r/LjGkeBM0ISt.png",
"provider": "FACEBOOK",
"userName": "/Exercise_Your_Voting_Right/519296421491495"
}
},
{
"name": "Example Page",
"id": "3a65a221-c16e-479b-8430-57b46fcb21f2",
"network": "Facebook",
"asset": "407001072724791",
"socialaccount": 94268,
"tokenStatus": 1,
"metadata": {
"pageLogo":
"https://fbcdn-profile-a.akamaihd.net/static-ak/rsrc.php/v2/yg/r/LjGkeBM0ISt.png",
"provider": "FACEBOOK",
"userName": "/Chris-Dev-Page/407001072724791"
}
}
]
},
{
"criteria": "social account",
"operator": "equals",
"argument": {
"id": "83967",
"link":
"https://stg3-api.dev.ca1.sfmc.co/socialcloud/v2/socialProperties/83967",
"updated": "2015-04-20T14:45:35Z",
"title": "Ana-192",
"topic": {
"id": "83967",
"link":
"https://stg3-api.dev.ca1.sfmc.co/socialcloud/v2/topics/83967",
"updated": "2015-02-19T17:06:49Z",
"title": "Ana-192",
"createdDate": "2015-02-19T17:06:49Z"
},
"creator": {
"id": "79798023",
"link":
"https://stg3-api.dev.ca1.sfmc.co/socialcloud/v2/users/79798023",
"updated": "2015-04-20T14:45:35Z",
"title": "Hiren Gosalia",
"email": "hgosalia@salesforce.com",
"avatarURL": null
109
Approval Rules Retrieve Approval Rule Criteria
},
"projects": [],
"registration": {
"id": "16243",
"link":
"https://stg3-api.dev.ca1.sfmc.co/socialcloud/v2/socialAccounts/16243",
"updated": null,
"title": "Mansi SFDC",
"lastRefreshedTime": null
},
"lastValidatedTime": null,
"avatar":
"https://media.licdn.com/mpr/mpr/p/7/005/086/041/07b736a.png",
"usedBySalesforce": "false",
"visibility": "private",
"uniqueName": "ana-192",
"realName": "Mansi SFDC",
"socialNetwork": {
"id": "3880369",
"name": "LinkedIn Page",
"type": 25
},
"status": 0,
"tokens": {
"tokenStatusId": 0,
"tokenStatusLastUpdate": null
}
}
}
}
],
"query": "1 AND ( 2 OR 3 )"
},
"meta": []
}
The information provided with the hydrate argument varies depending on the included entities.
A call that cannot find the indicated approval flow returns the following response:
{
"status": false,
"response": {
"errors": [
{
110
Approval Rules Update Approval Rule Criteria
"code": "error.not_found",
"message": ""
}
]
},
"meta": []
}
A call that references an unauthorized approval flow returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.forbidden",
"message": ""
}
]
},
"meta": []
}
HTTP method
PUT
Request Parameters
JSON Parameters
Each JSON payload includes two arguments:
111
Approval Rules Update Approval Rule Criteria
The *items* array includes individual items with the following values:
*criteria* - string value indicating the subject of the rule. Acceptable values include
the following:
*label* - label associated with object
*submitter* - user ID for person performing submit action
*social account* - social property ID associated with the object
*language* - language associated with the object
*country* - country associated with the object
*operator* - string value indicating whether the rule subject equals or does not equal
the provided value
*equals*
*not equals*
*argument* - string value to match against the *criteria* value. *argument* can accept
empty values for label, country, and language. *argument* cannot accept empty values for
*submitter* or *social account*.
The *query* argument includes integers, logical operators, and appropriate groupings.
*integer* - position of criteria in *items* array, beginning with 1
*logical operators* - AND or OR value indicating grouping of criteria
*grouping* - Use parantheses to group together integers and logical operators. You
cannot use AND and OR in the same grouping.
Sample Request
PUT {HOST}/v1/approvalprerequisites/46e66860-25fe-11e3-b1a1-168170973bd5
{
"items": [
{
"criteria": "submitter",
"operator": "equals",
"argument": 123123
},
{
"criteria": "social account",
"operator": "equals",
"argument": 68304
},
{
"criteria": "social account",
"operator": "equals",
"argument": 68647
}
],
"query": "(1 AND 2) OR ( 1 AND 3 )"
}
112
Approval Rules Update Approval Rule Criteria
Sample Response
A successful call returns the following response:
{
"status": true,
"response": true,
"meta": []
}
A call not authorized to modify the approval flow returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.forbidden",
"message": ""
}
]
},
"meta": []
}
113
Approval Rules Retrieve Approvers for a Rule
"meta": []
}
HTTP method
GET
Request Parameters
Query Parameters
*hydrate=argument - indicates that the call should return related entity information instead
of string or integer IDs
Sample Request
This sample request retrieves the specified approval rule:
curl GET {HOST}/v1/approvalprocedures/aab75fac-0453-11e3-8d6f-168170973bd5
Sample Response
A successful call returns the following response:
{
"status": true,
"response": {
"items": [
{
"criteria": "user",
"operator": "equals",
"argument": 123123,
114
Approval Rules Retrieve Approvers for a Rule
"action": "approve"
},
{
"criteria": "user",
"operator": "equals",
"argument": 8765,
"action": "approve"
},
{
"criteria": "user",
"operator": "equals",
"argument": 425548144218779,
"action": "approve"
}
],
"query": "(1 AND 2) OR ( 1 AND 3 )"
},
"meta": []
}
A successful call with the hydrate argument returns the following response:
{
"status": true,
"response": {
"items": [
{
"criteria": "user",
"operator": "equals",
"argument": {
"id": 6721,
"email": "pboddu@example.com",
"username": "pboddu@example.com",
"title": "PraveenBoddu",
"display_name": "PraveenBoddu",
"avatar_url": null,
"timezone": "GMT",
"enabled": true,
"updated": "2014-02-07T18:59:47+0000",
"organization_id": 10545
},
"action": "approve"
},
{
"criteria": "user",
"operator": "equals",
"argument": {
"id": 6721,
"email": "pboddu@example.com",
"username": "pboddu@example.com",
"title": "PraveenBoddu",
"display_name": "PraveenBoddu",
"avatar_url": null,
"timezone": "GMT",
"enabled": true,
115
Approval Rules Retrieve Approvers for a Rule
"updated": "2014-02-07T18:59:47+0000",
"organization_id": 10545
},
"action": "approve"
},
{
"criteria": "user",
"operator": "equals",
"argument": {
"id": 6721,
"email": "pboddu@example.com",
"username": "pboddu@example.com",
"title": "PraveenBoddu",
"display_name": "PraveenBoddu",
"avatar_url": null,
"timezone": "GMT",
"enabled": true,
"updated": "2014-02-07T18:59:47+0000",
"organization_id": 10545
},
"action": "approve"
}
],
"query": "1 and ( 2 or 3 )"
},
"meta": []
}
The information provided with the hydrate argument varies depending on the included entities.
Error Responses
A call referencing an unknown approval rule returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.not_found",
"message": ""
}
]
116
Approval Rules Update Approvers for a Rule
},
"meta": []
}
Ensure that you reference the correct ID for the approval rule.
A call referencing an approval rule without authorization returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.forbidden",
"message": ""
}
]
},
"meta": []
}
HTTP method
PUT
Request Parameters
JSON Parameters
Each JSON payload includes two arguments:
The *items* array includes individual items with the following values:
117
Approval Rules Update Approvers for a Rule
*criteria* - string value indicating this call affects a specified user. Use only the
*user* value here.
*argument* - string value to match against the *criteria* value. *argument* can accept
empty values for label, country, and language. *argument* cannot accept empty values for
*submitter* or *social account*.
*action* - indicates the action for the rule. Acceptable values include the following:
*approve*
The *query* argument includes integers, logical operators, and appropriate groupings.
*integer* - position of criteria in *items* array, beginning with 1
*logical operators* - AND or OR value indicating grouping of criteria
*grouping* - Use parantheses to group together integers and logical operators. You
cannot use AND and OR in the same grouping.
Sample Request
This sample request updates an approval rule with a priority of 2:
curl -X PUT {HOST}/v1/approvalprocedures/46e66860-25fe-11e3-b1a1-168170973bd5
{
"items": [
{
"criteria": "user",
"operator": "equals",
"argument": 123123,
"action": "approve"
},
{
"criteria": "user",
"operator": "equals",
"argument": 8765,
"action": "approve"
},
{
"criteria": "user",
"operator": "equals",
"argument": 425548144218779,
"action": "approve"
}
],
"query": "(1 AND 2) OR ( 1 AND 3 )"
}
Sample Response
A successful call returns the following response:
{
"status": true,
118
Approval Rules Update Approvers for a Rule
"response": true,
"meta": []
}
Error Responses
A call referencing an unknown approval rule returns the following response:
{
"status": false,
"response": {
"errors": [
{
"code": "error.not_found",
"message": ""
}
]
},
"meta": []
}
119
Approval Rules Update Approvers for a Rule
"meta": []
}
120
CHAPTER 12 Social Properties
In this chapter ... The Social Properties endpoint allows you to retrieve a list of social accounts registered in your Social
Studio organization. The call returns only those social accounts available to you based on user permissions
Retrieve Properties and role.
Retrieve Property
cURL Example
curl -X GET -H "access_token: 99203c04-621c-4b43-99e4-b76e121faddc"
'https://api.socialstudio.radian6.com/v3/socialProperties?view=shared&owned'
cURL Example
curl -X GET -H "access_token: 99203c04-621c-4b43-99e4-b76e121faddc"
'https://api.socialstudio.radian6.com/v3/socialProperties/6386'
121
Social Properties Retrieve Properties
Retrieve Properties
This method retrieves social properties the user can access. This object contains information about a managed account topic profile and
associated external user account.
/v3/socialProperties
HTTP Method
GET
Request Parameters
122
Social Properties Retrieve Properties
Sample Request
GET /v3/socialProperties?types=4
Sample Response
{
"data": [
{
"id": "121218",
"displayName": "Jane's test software",
"pageUrl": "https://facebook.com/pages/Janes-test-softwar/128544450650919",
"networkTypeId": 4,
"avatarUrl":
"https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xaf1/v/t1.0-1/c151.34.422.422/s50x50/552488_128545593954160_2159838340_n.jpg?oh=cb08f9353545f1bb437f96022466a235&oe=563DA948&__gda__=1448168411_3a661fa573372b8fc3b31058feeb6c8c",
"slug": "pages/Janes-test-software/128544450650919",
"valid": true
},
{
"id": "111819",
"displayName": "I Heart CBC NB",
"pageUrl": "https://facebook.com/pages/I-Love-CBC-NB/376189652448432",
"networkTypeId": 4,
"avatarUrl":
"https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xfa1/v/t1.0-2/p50x50/305074_380514875349292_382752874_n.jpg?oh=02eb66e27be49c4d3a99576b4997493b&oe=5651FCB9&__gda__=1447361104_cbbb529d940f10185f2877dd306967de",
"slug": "pages/I-Love-CBC-NB/376189652448432",
"valid": true
}
],
"meta": {
"totalCount": 2
}
}
123
Social Properties Retrieve Property
Retrieve Property
This method retrieves a single social property from those available for the user to access. This object contains information about a
managed account topic profile and associated external user account. The socialPropertyId value equals the managed account topic
profile ID.
/v3/socialProperties/{id}
HTTP Method
GET
Request Parameters
*id* - integer value indicating the ID for the social property to retrieve
Sample Request
GET /v3/socialProperties/121218
Sample Response
{
"data": [
{
"id": "121218",
"displayName": "Jane's test software",
"pageUrl": "https://facebook.com/pages/Janes-test-softwar/128544450650919",
"networkTypeId": 4,
"avatarUrl":
"https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xaf1/v/t1.0-1/c151.34.422.422/s50x50/552488_128545593954160_2159838340_n.jpg?oh=cb08f9353545f1bb437f96022466a235&oe=563DA948&__gda__=1448168411_3a661fa573372b8fc3b31058feeb6c8c",
"slug": "pages/Janes-test-software/128544450650919",
"valid": true
},
],
"meta": {
"totalCount": 1
124
Social Properties Retrieve Property
}
}
125
CHAPTER 13 Create Topic Profile and Retrieving Posts with
Keyword Groups
In this chapter ...
Create Topic Profile
Retrieve Topic Profiles
Retrieve Topic Profile Use the topic profile to define the social data that interests you based on a set of parameters consisting
of keywords, sources, languages, regions and media types. For example, you could look for a series of
Create Topic Profile
English keywords in Twitter posts originating in the United Kingdom.
Update Topic Profile
First, define the topic profile using the following route:
Delete Topic Profile
Update Keyword POST /v3/topics
Groups in a Topic
Profile
Delete Keyword cURL Example
Groups in a Topic
Profile curl -X POST -H 'access_token: your_access_token" -H "Content-Type:
Update Source Filters application/json" -d '{
in a Topic Profile "title" : "test12345",
"languages" : [ "1" ],
Activate a Topic
"mediaTypes" : [ {"id" : "5" }, { "id" : "1" }, { "id" : "10" } ]
Profile
}' https://api.socialstudio.radian6.com/v3/topics
cURL Example
curl -X POST -H "access_token: your_access_token" -H "Content-Type:
application/json" -d '{
"title" : "API Test",
"type" : 2,
"active" : true,
"contains" : [[{"tokenType" : 1, "value" : "Coca Cola", "meta" :
126
Create Topic Profile and Retrieving Posts with Keyword
Groups
"2" }]]
}' https://api.socialstudio.radian6.com/v3/keywordGroups
cURL Example
curl -X PUT -H "access_token: your_access_token" -H "Content-Type:
application/json" -d '[
{
"id" : "405492"
}]'
https://api.socialstudio.radian6.com/v3/topics/273382/keywordGroups
Retrieving Posts
Once you create the previous calls, you can retireve matching posts:
GET /v3/posts?topics={id}
cURL Example
curl -X GET -H "access_token: your_access_token" -H "Content-Type:
application/json"
https://api.socialstudio.radian6.com/v3/posts?topics=273382
Each client can use a limited amount of active topic profiles. Any call that causes the client to exceed
the limit returns a 400 error.
127
Create Topic Profile and Retrieving Posts with Keyword Retrieve Topic Profiles
Groups
HTTP Method
GET
Request Parameters
None
Query Parameters
Sample Call
GET /v3/topics?q="Scott"&includeQuickSearch=false
128
Create Topic Profile and Retrieving Posts with Keyword Retrieve Topic Profiles
Groups
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "4",
"title": "Scott Test 3",
"creator": {
"id": "3",
"link": "https://stg2-dmz3.dev.ca1.example.co/socialcloud/v2/users/3",
"updated": null,
"title": "scott@example.com (clientId = 1)"
},
"visibility": "private",
"status": 1,
"emv": 0,
"languages": [],
"mediaTypes": [],
"regions": [],
"keywordGroups": [],
"billingCode": "",
"includeSourceFilters": [],
"excludeSourceFilters": [],
"includeAllSourceFilters": [],
"createdDate": "2009-10-09T19:27:58Z"
},
],
"meta" : {
"totalCount" : 52
}
}
129
Create Topic Profile and Retrieving Posts with Keyword Retrieve Topic Profile
Groups
HTTP Method
GET
Request Parameters
Sample Call
GET /v3/topics/4
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "4",
"title": "Scott Test 3",
"creator": {
"id": "3",
"link": "https://stg2-dmz3.dev.ca1.example.co/socialcloud/v2/users/3",
"updated": null,
"title": "scott@example.com (clientId = 1)"
},
"visibility": "private",
130
Create Topic Profile and Retrieving Posts with Keyword Create Topic Profile
Groups
"status": 1,
"emv": 0,
"languages": [],
"mediaTypes": [],
"regions": [],
"keywordGroups": [],
"billingCode": "",
"includeSourceFilters": [],
"excludeSourceFilters": [],
"includeAllSourceFilters": [],
"createdDate": "2009-10-09T19:27:58Z"
},
],
"meta" : {
"totalCount" : 52
}
}
131
Create Topic Profile and Retrieving Posts with Keyword Create Topic Profile
Groups
HTTP Method
POST
Request Parameters
None
JSON Parameters
*title* - string value indicating name for new topic profile (required)
*languages* - array of integer values indicating languages associated with new topic profile
(required, set with value of ALL to associate with all available values)
*mediaTypes* - array of integer values indicating media types associated with new topic
profile (required, set with value of ALL to associate with all available values)
*regions* - array of integer values indicating regions associated with new topic profile
(required, set with value of ALL to associate with all available values)
*status* - integer value indicating status of topic profile (create with value of 4 for
DRAFT, otherwise leave blank)
Sample Request
POST /v3/topics
{
"title": "test topic profile",
"languages": [
"1"
],
"mediaTypes": [
{
"id": "5"
},
{
"id": "1"
},
{
"id": "10"
}
]
"regions": [
"all"
]
}
132
Create Topic Profile and Retrieving Posts with Keyword Update Topic Profile
Groups
Sample Response
A successful call returns a 201 Success code with a Location response header including the URL for the new topic profile resource.
A call including a malformed JSON payload or invalid IDs (such as unauthorized mediatypes) returns a 400 code. Ensure your JSON
payload contains valid values.
A call by a user with insufficient permissions returns a 403 code. Ensure your user can make this call within your organization.
An internal server error returns a 500 code. Try your code at a later time.
HTTP Method
PUT
Request Parameters
None
JSON Parameters
*title* - string value indicating name for new topic profile (required)
*languages* - array of integer values indicating languages associated with new topic profile
(required, set with value of ALL to associate with all available values)
*mediaTypes* - array of integer values indicating media types associated with new topic
profile (required, set with value of ALL to associate with all available values)
*regions* - array of integer values indicating regions associated with new topic profile
(required, set with value of ALL to associate with all available values)
*status* - integer value indicating status of topic profile (create with value of 4 for
DRAFT, otherwise leave blank)
Sample Request
curl -X PUT -H "access_token: f0f59c64-a82d-4a76-8781-078952df8785" -H "Content-Type:
application/json" -d '{
"title": "API Test TP",
"languages": [
133
Create Topic Profile and Retrieving Posts with Keyword Delete Topic Profile
Groups
"1"
],
"mediaTypes": [
{
"id": "5"
},
{
"id": "1"
},
{
"id": "10"
},
{
"id": "12"
}
]
}' 'https://{host}/v3/topics/1228'
Sample Response
A successful call returns a 200 Success code.
A call including a malformed JSON payload or invalid IDs (such as unauthorized mediatypes) returns a 400 code. Ensure your JSON
payload contains valid values.
A call by a user with insufficient permissions returns a 403 code. Ensure your user can make this call within your organization.
An internal server error returns a 500 code. Try your code at a later time.
HTTP Method
DELETE
Request Parameters
134
Create Topic Profile and Retrieving Posts with Keyword Update Keyword Groups in a Topic Profile
Groups
Sample Request
DELETE /v3/topics/123459
Sample Response
A successful call returns a 204 No Content code.
A call including an invalid ID value returns a 404 code. Ensure your call contains valid values.
An internal server error returns a 500 code. Try your code at a later time.
HTTP Method
PUT
Request Parameters
JSON Parameters
*keywordGroupId* - integer value indicating the keyword group (can include array of these
values)
Sample Request
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json"-H
"access_token: your_access_token" -d "[
{ \"id\" : \"408299\" }
]" "https://{host}/v3/topics/304237/keywordGroups"
135
Create Topic Profile and Retrieving Posts with Keyword Delete Keyword Groups in a Topic Profile
Groups
Sample Response
A successful call returns a 200 code.
A call from a user with insufficient permissions to perform the update (either on topic profile or keyword groups)returns a 403 call.
Contact your administrator for the proper permissions.
A call including an invalid topic profile ID or keyword group ID returns a 404 error. Ensure you include the correct values in your call.
An internal server error during your call returns a 500 error. Try your call again at a later time.
HTTP Method
DELETE
Request Parameters
Sample Request
DELETE /v3/topics/123459/keywordGroups/54321
Sample Response
A successful call returns a 204 No Content code.
A call including an invalid ID value returns a 404 code. Ensure your call contains valid values.
An internal server error returns a 500 code. Try your code at a later time.
136
Create Topic Profile and Retrieving Posts with Keyword Activate a Topic Profile
Groups
HTTP method
PUT
Request Parameters
JSON Parameters
*sourceFilterId* - The identifier for the source filter to be associated with the topic
profile
*type* - Source filter type
*0* - Include
*1* - Exclude
*2* - Include all
Sample Requests
Sample Response
HTTP Method
POST
137
Create Topic Profile and Retrieving Posts with Keyword Activate a Topic Profile
Groups
Request Parameters
Query Parameters
Sample Request
POST /v3/topics/12345?action=activate&billingCode=6789
Sample Response
A successful call returns a 204 No Content code.
A call including an invalid ID value returns a 404 code. Ensure your call contains valid values.
An internal server error returns a 500 code. Try your code at a later time.
138
CHAPTER 14 Keyword Groups
In this chapter ...
Retrieve Keyword
Groups
Create Keyword
Groups
Update Keyword
Groups
139
Keyword Groups Retrieve Keyword Groups
HTTP Method
GET
Request Parameters
Sample Request
curl -X GET -H "Accept: application/json"-H "access_token: your_access_token"
"https://{host}/v3/keywordGroups/408299"
Sample Response
A successful call returns the following response:
{
"data" : [
{
"title" : "Beverages",
"type" : 2,
"active" : true,
"contains" : [
[
{
"tokenType": 1,
"value": "soda",
"meta": "2"
},
{
"tokenType": 2
},
{
"tokenType": 0,
"value": "orange"
}
140
Keyword Groups Retrieve Keyword Groups
],
[
{
"tokenType": 1,
"value": "coffee",
"meta": "3"
},
{
"tokenType": 3
},
{
"tokenType": 0,
"value": "tea"
}
]
],
"excludes": [
{
"tokenType": 0,
"value": "lemonade"
}
],
"andContains": [
{
"tokenType": 0,
"value": "cranberry"
},
{
"tokenType": 0,
"value": "water"
}
]
}
],
"meta" : {
"totalCount" : 1
}
}
141
Keyword Groups Create Keyword Groups
allowed)
*tokenType* - integer value indicating types of keyword tokens:
*0* - KEYWORD_OR_PHRASE (requires tokenType and value information)
*value* - string value indicating keyword or phrase to include in search
*excludes* - array of values indicating other keywords to exclude from results (no operators
allowed, cannot exceed the maximum number set at the client level)
*tokenType* - integer value indicating types of keyword tokens:
*0* - KEYWORD_OR_PHRASE (requires tokenType and value information)
*value* - string value indicating keyword or phrase to include in search
HTTP Method
POST
Request Parameters
None
JSON Parameters
Each JSON payload includes the following arguments:
142
Keyword Groups Create Keyword Groups
Your keywords cannot accept predefined stop works, including the following values:
a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z,1,2,3,4,5,6,7,8,9,0,!,@,#,$,^,*,(,),am,an,as,at,be,by,do,go,he,if,in,is,it,me,my,no,of,on,or,so,to,up,us,we,and,the,for,not,she,was,test
Your keywords cannot accept any invalid characters, including the following values:
^"<>|*\n
The overall number of keywords and phrases for the topic profile cannot exceed the maximum number set at the client level. Contact
your administrator to determine these levels.
Sample Request
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"-H
"access_token: your_access_token" -d "{
\"title\" : \"Presidential Test\",
\"type\" : 2,
\"active\" : true,
\"contains\" : [
[
{
\"tokenType\" : 1,
\"value\" : \"President\",
\"meta\" : \"2\"
}
]
]
}" "https://{host}/v3/keywordGroups"
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "408299"
}
],
"meta":
{
"totalCount": 1
143
Keyword Groups Update Keyword Groups
}
}
A call with a malformed JSON document returns a 400 error. Ensure you correctly formatted your JSON information.
An internal server error during your call returns a 500 error. Try your call again at a later time.
HTTP Method
PUT
Request Parameters
JSON Parameters
Each JSON payload includes the following arguments:
144
Keyword Groups Update Keyword Groups
allowed)
*tokenType* - integer value indicating types of keyword tokens:
*0* - KEYWORD_OR_PHRASE (requires tokenType and value information)
*value* - string value indicating keyword or phrase to include in search
*excludes* - array of values indicating other keywords to exclude from results (no operators
allowed, cannot exceed the maximum number set at the client level)
*tokenType* - integer value indicating types of keyword tokens:
*0* - KEYWORD_OR_PHRASE (requires tokenType and value information)
*value* - string value indicating keyword or phrase to include in search
Your keywords cannot accept predefined stop works, including the following values:
a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z,1,2,3,4,5,6,7,8,9,0,!,@,#,$,^,*,(,),am,an,as,at,be,by,do,go,he,if,in,is,it,me,my,no,of,on,or,so,to,up,us,we,and,the,for,not,she,was,test
Your keywords cannot accept any invalid characters, including the following values:
^"<>|*\n
The overall number of keywords and phrases for the topic profile cannot exceed the maximum number set at the client level. Contact
your administrator to determine these levels.
Sample Request
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json"-H
"access_token: your_access_token" -d "{
\"title\": \"Presidential Test\",
\"active\": true,
\"type\": 2,
\"keywordsCount\": 0,
\"contains\": [
[
{
\"tokenType\": 1,
\"value\": \"President\",
\"meta\": \"2\"
}
]
],
\"andContains\": [],
\"excludes\": []
}" "https://{host}/v3/keywordGroups/408299"
Sample Response
A successful call returns a 200 code.
A call with a malformed JSON document returns a 400 error. Ensure you correctly formatted your JSON information.
A call from a user with insufficient permissions to perform the update returns a 403 call. Contact your administrator for the proper
permissions.
An internal server error during your call returns a 500 error. Try your call again at a later time.
145
CHAPTER 15 Sources and Source Groups
In this chapter ... Use sources to identify specific Facebook pages, Twitter accounts, blog posts, and other source types.
These source types can further refine the topic profile definition. You can also combine sources into
Retrieve Sources groups.
Retrieve Source
Create Source
Update Source
Retrieve Sources
Delete Source
GET /v3/sourceFilters/1055/sourceFilterQueries
Retrieve Source
Groups
Retrieve Source cURL Example
Group
Create Source Group
curl -X GET -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e"
Update Source
Group -H "Content-Type:
Delete Source Group application/json"'https://api.socialstudio.radian6.com/v3/sourceFilters/1055/sourceFilterQueries'
146
Sources and Source Groups Retrieve Sources
Retrieve Sources
This method returns all source filter queries associated with a social filter.
/v3/sourceFilters/{sourceFilterId}/sourceFilterQueries
HTTP Method
GET
Request Parameters
*sourceFilterId* - integer value indicating the source filter from which to retrieve a
social filter query (required)
Query Parameters
Sample Request
GET /v3/sourceFilters/1/sourceFilterQueries
Sample Response
{
"data": [
{
"id": "1",
"title": "Source Filter Query Title",
"uri": "my.source.filter.query.org"
}
],
"meta": {
147
Sources and Source Groups Retrieve Source
"totalCount": 1
}
}
Retrieve Source
This method returns a specified source filter query associated with a social filter.
/v3/sourceFilters/{sourceFilterId}/sourceFilterQueries/{sourceFilterQueryId}
HTTP Method
GET
Request Parameters
*sourceFilterId* - integer value indicating the source filter from which to retrieve a
social filter query (required)
*sourceFilterQueryId* - integer value indicating the source filter query to retrieve
(required)
Query Parameters
Sample Request
GET /v3/sourceFilters/1/sourceFilterQueries/123
148
Sources and Source Groups Create Source
Sample Response
{
"data": [
{
"id": "123",
"title": "Source Filter Query Title",
"uri": "my.source.filter.query.org"
}],
"meta": {
"totalCount": 1
}
}
Create Source
This method creates a source filter query within an account. You can add this source filter query to the source filter to create conditions
for use within the filter.
/v3/sourceFilters/{sourceFilterId}/sourceFilterQuery
HTTP Method
POST
Request Parameters
*sourceFilterId* - integer value indicating the source filter from which to retrieve a
social filter query (required)
JSON Parameters
149
Sources and Source Groups Update Source
Sample Request
POST /v3/sourceFilters/1/sourceFilterQuery
{
"title": "Source Filter Title",
"uri": "A description of what this source filter contains."
}
Sample Response
A successful call returns a 201 Success response. A Location response header contains the URL to the new source filter query resource.
A malformed JSON payload returns a 400 Bad Request response. Ensure your payload matches the sample shown in this example.
A internal error during creation returns a 500 Internal Server Error. Try your create call again at a later time.
Update Source
This method updates a source filter query within an account.
/v3/sourceFilters/{sourceFilterId}/sourceFilterQueries/{sourceFilterQueryId}
HTTP Method
PUT
Request Parameters
*sourceFilterId* - integer value indicating the source filter from which to retrieve a
social filter query (required)
*sourceFilterQueryId* - integer value indicating the source filter query to retrieve
(required)
JSON Parameters
150
Sources and Source Groups Delete Source
Sample Request
PUT /v3/sourceFilters/1
{
"title": "Source Filter Title",
"uri": "A description of what this source filter contains."
}
Sample Response
A successful call returns a 204 No Content response, indicating the call successfully updated the source filter.
A malformed JSON payload returns a 400 Bad Request response. Ensure your payload matches the sample shown in this example.
A internal error during creation returns a 500 Internal Server Error. Try your create call again at a later time.
Delete Source
This method deletes the source filter query specified by the ID. This action removes the souce query filter from any associated source
filter.
/v3/sourceFilters/{sourceFilterId}/sourceFilterQueries/{sourceFilterQueryId}
HTTP Method
DELETE
Request Parameters
*sourceFilterId* - integer value indicating the source filter from which to retrieve a
social filter query (required)
*sourceFilterQueryId* - integer value indicating the source filter query to retrieve
(required)
Sample Request
DELETE /v3/sourceFilters/1/socialFilterQueries/123
Sample Response
A successful call returns a No Content 204 code, indicating the call succeded and no content exists.
151
Sources and Source Groups Retrieve Source Groups
HTTP Method
GET
Request Parameters
Sample Request
GET /v3/sourceFilters?status=2
Sample Response
{
data: [
{
152
Sources and Source Groups Retrieve Source Group
id: 1,
title: Trent - Yahoo Answers SF,
description: null,
status: 2,
createdDate: 20091222T17:22:08Z,
topicCount: 0,
public: false,
creator: {
id: 58,
link: https://api.radian6.com/socialcloud/v2/users/58,
updated: null,
title: Trent - Staging - GMail - CLID = 1
}
},
],
meta: {
totalCount: 706
}
}
HTTP Method
GET
Request Parameters
153
Sources and Source Groups Retrieve Source Group
Sample Request
GET /v3/sourceFilters/1
Sample Response
{
data: [
{
id: 1,
title: Trent - Yahoo Answers SF,
description: null,
status: 2,
createdDate: 20091222T17:22:08Z,
topicCount: 0,
public: false,
creator: {
id: 58,
link: https://api.radian6.com/socialcloud/v2/users/58,
updated: null,
title: Trent - Staging - GMail - CLID = 1
}
},
],
meta: {
totalCount: 1
}
}
154
Sources and Source Groups Create Source Group
HTTP Method
POST
Request Parameters
None
JSON Parameters
Sample Request
POST /v3/sourceFilters/
{
"title": "source group title",
"description": "A description of what this source group contains.",
"public": false
}
Sample Response
A successful call returns a 201 Success response. A Location response header contains the URL to the new source group resource.
A malformed JSON payload returns a 400 Bad Request response. Ensure your payload matches the sample shown in this example.
A internal error during creation returns a 500 Internal Server Error. Try your create call again at a later time.
155
Sources and Source Groups Update Source Group
HTTP Method
PUT
Request Parameters
*sourceFilterID* - The ID for the specific source group you wish to update
JSON Parameters
Sample Request
PUT /v3/sourceFilters/1
{
"title": "source group Title",
"description": "A description of what this source group contains.",
"public": false
}
Sample Response
A successful call returns a 204 No Content response, indicating the call successfully updated the source group.
A malformed JSON payload returns a 400 Bad Request response. Ensure your payload matches the sample shown in this example.
A internal error during creation returns a 500 Internal Server Error. Try your create call again at a later time.
156
Sources and Source Groups Delete Source Group
HTTP Method
DELETE
Request Parameters
Sample Request
DELETE /v3/sourceFilters/1
Sample Response
A successful call returns a No Content 204 code, indicating the call succeeded and no content exists.
An internal error occurring during the call returns a 500 error.
157
CHAPTER 16 Languages
In this chapter ...
Retrieve Languages
Retrieve Language
158
Languages Retrieve Languages
Retrieve Languages
This method retrieves information about all languages available when managing your topic profile.
/v3/languages
HTTP Method
GET
Request Parameters
*limit* - integer value indicating number of results to return (defaults to 1000). This
method does not return any deleted comments.
*offset* - integer value indicating result to start with (defaults to 0)
Sample Request
GET /v3/languages
cURL Example
curl -X GET -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e"
'https://api.socialstudio.radian6.com/v3/languages'
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "1",
"title": "English",
"code": "en"
},
{
"id": "2",
"title": "French",
"code": "fr"
},
{
159
Languages Retrieve Language
"id": "3",
"title": "Spanish",
"code": "es"
},
...
],
"meta": {
"totalCount": 28
}
}
Retrieve Language
This method retreives information about all languages available within an account.
/v3/languages/{id}
HTTP Method
GET
Request Parameters
Sample Request
GET /v3/languages/1
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "1",
160
Languages Retrieve Language
"title": "English",
"code": "en"
},
],
"meta": {
"totalCount": 1
}
}
161
CHAPTER 17 Regions
In this chapter ...
Retrieve Regions
Retrieve Region
162
Regions Retrieve Regions
Retrieve Regions
This method retrieves information about all regions available when managing your topic profile.
/v3/regions
HTTP Method
GET
Request Parameters
Sample Call
GET /v3/regions
cURL Example
curl -X GET -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e" -H "Content-Type:
application/json" 'https://api.socialstudio.radian6.com/v3/regions'
Sample Response
{
"data": [
{
"id": "46",
"title": "China",
"regionTLD": ".cn",
"isoCountryCode": "CN"
},
{
"id": "78",
"title": "French Southern Territories",
"regionTLD": ".tf",
"isoCountryCode": "TF"
},
{
163
Regions Retrieve Region
"id": "158",
"title": "New Caledonia",
"regionTLD": ".nc",
"isoCountryCode": "NC"
},
...
],
"meta": {
"totalCount": 249
}
}
Retrieve Region
This method returns a specific region associated with an account.
/v3/regions/{regionId}
HTTP Method
GET
Request Parameters
Sample Call
GET /v3/regions/46
Sample Response
{
"data": [
{
164
Regions Retrieve Region
"id": "46",
"title": "China",
"regionTLD": ".cn",
"isoCountryCode": "CN"
}
],
"meta": {
"totalCount": 1
}
}
165
CHAPTER 18 Media Types
In this chapter ...
Retrieve Media Types
Retrieve Media Type
166
Media Types Retrieve Media Types
HTTP Method
GET
Request Parameters
None
Query Parameters
*private* - boolean value indicating a return of only private media types (defaults to
false)
*classificationIds* - string value containing comma-delimited list of media type
classification IDs. This parameter returns media types belonging to the specified
classifications. When supplying this value, call will ignore *private* parameter and return
all results associated with supplied classification IDs.
*limit* - integer value indicating number of results to return (defaults to 1000)
*offset* - integer value indicating result to start with in returned results
Sample Request
GET /v3/mediaTypes?private=true&classificationIds=1,3
cURL Example
curl -X GET -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e"
'https://api.socialstudio.radian6.com/v3/mediaTypes'
Sample Response
{
"data": [
{
"id": "1",
167
Media Types Retrieve Media Type
"title": "Blogs",
"isVisible": true,
"classificationId": "1",
"classificationType": "Broad Listening"
},
{
"id": "2",
"title": "Videos",
"isVisible": true,
"classificationId": "1",
"classificationType": "Broad Listening"
},
...
],
"meta": {
"totalCount": 12
}
}
HTTP Method
GET
Request Parameters
Sample Request
GET /v3/mediaTypes/1
168
Media Types Retrieve Media Type
Sample Response
{
"data": [
{
"id": "1",
"title": "Blogs",
"isVisible": true,
"classificationId": "1",
"classificationType": "Broad Listening"
}
],
"meta": {
"totalCount": 1
}
}
169
CHAPTER 19 Posts
In this chapter ... Use the Post endpoint to retrieve the social post content associated with a predefined topic profile. The
Social Studio API allows an export of up to 1000 posts per topic profile every 30 seconds (equaling 2.8
Retrieve Posts million posts in 24 hours).
The Social Studio API enforces some content restruction due to legal requirements:
The API removes all Twitter content and can only provide post and author IDs as well as workflow data for
each post. We remove tweet content and post dynamics you can rehydrate directly via Twitter APIs *We
truncate any broad listening topic profile content to 310 characters or 10 percent of the content, whichever
is greater.
Retrieve Posts
GET /v3/posts
cURL Example
curl -X GET -H "access_token: 513e6576-218d-4a9e-b7cc-ac4ebf45fd1e"
'https://api.socialstudio.radian6.com/v3/posts?topics=1829'
170
Posts Retrieve Posts
Retrieve Posts
This method retrieves post data from available broad listening topic profiles and social accounts.
/v3/posts
HTTP Method
GET
Request Parameters
None
Query Parameters
*topics* - string value containing comma-delimited list of topic profile IDs to include
in call (required)
*limit* - integer value indicating number of posts to return in the call (defaults to 25,
accepts values from 1 to 1000)
*sinceId* - integer value indicating ID of post to start retrieve. This parameter allows
only posts created after the identified post.
*beforeId* - integer value indicating ID of post to start retrieve. This parameter allows
only posts created before and including the identified post.
*startDate* - timestamp value indicating the the start date for the filter. This parameter
allows only those posts published to the social media channel on or after the given date,
based on the *updated* attribute for the post (defaults to 24 hours before call occurs).
*endDate* - timestamp value indicating the the end date for the filter. This parameter
allows only those posts published to the social media channel on or before the given date,
based on the *updated* attribute for the post (defaults to current time).
*mediaTypes* - string value containing comma-delimited list of media type IDs to include
in call (defaults to all applicable media types including in the specified topic profiles)
*extendedMediaTypes* - string value containing comma-delimited list of extended media type
IDs to include in call (defaults to all applicable extended media types including in the
specified topic profiles)
*includeWorkflow* - boolean value indicates whether to include workflow with the returned
posts (defaults to false)
*includeSpam* - boolean value indicating whether to include posts flagged as spam by the
Salesforce Marketing Cloud (defaults to false)
*includeAnchors* - boolean value indicating whether to include anchor tags in content. A
*true* value indicates the call returns links as HTML anchor tags within the returned post
content. A *false* value returns plain text (defaults to false).
*highlight* - boolean value indicating whether the call highlights keywords. A *true* value
indicating highlighted keywords from the topic profile configuration in the post content
171
Posts Retrieve Posts
for use when presented in a web page. A *false* value returns plain text (defaults to
false).
*keywords* - string value containing a comma-delimited list of keywords to use when returning
only posts containing those values. This parameter includes up to 50 values and ignores
duplicates.
*sortBy* - string values indicating how call sorts the response:
*publishedDate* - sort by published date in descending order
*publishedDate-ascending* - sort by published date in ascending order
*blogPostId* - sort by post object ID in descending order (default)
*blogPostId-ascending* - sort by post object ID in ascending order
*rankBM25* - sort by relevance rank based on matched keywork frequency
*keywordGroups* - string value containing comma-delimited list of filter group IDs used
to filter posts associated only with those groups. Defaults to all keyword groups provided
in topic profiles from the *topics* parameter.
*includeSourceFilterMatches* - boolean value indicating whether to include the source
groups containing URLs each post matches (defaults to false)
*regions* - string value containing comma-delimited list of region IDs (defaults to all
regions assigned to topics from the *topic parameter)
*languages* - string value containing comma-delimited list of language IDs (defaults to
all languages assigned to topics from the *topic parameter)
*assignedUser* - string value including a comma-delimited list of users IDs for users
within the same client as the calling user
*engagement* - string value containing comma-delimited list of engagement status IDs to
return
*priority* - integer value indicating priority values to use when returning posts:
*1* - low
*2* - medium
*3* - high
*classification* - string value containing comma-delimited list of classifications to
return
*eventsSince* - timestamp value used to indicate posts to return after provided value
(milliseconds after midnight on 1/1/1970). Adding this parameter includes an HTTP header
called Workflow-As-Of-Date that contains current timestamp of call. Use this value to
retrieve only workflow events applied since previous method call. This parameter considers
only workflow applied within last 30 days of call.
*unassigned* - boolean value indicating the call returns only unassigned posts
*sentiment* - string value containing comma-delimited list of sentiment IDs used to filter
posts:
*-10* - Negative
*0* - Neutral
*10* - Positive
*authorTags* - string value containing comma-delimited list of author tags used to filter
posts
Sample Call
The call below returns posts from the specified topic profile:
GET /v3/posts?topics=1234
172
Posts Retrieve Posts
The call below returns the latest 50 Twitter posts since the specified ID
GET /v3/posts?topics=1234&mediaTypes=8&limit=50&sinceId=777777
Sample Response
{
"data" : [
{
"id": "1828477438",
"title": "Tennis Star visits Malawi",
"externalId": null,
"externalLink": "http://www.youtube.com/watch?v=exampleValue",
"sourceApplication": null,
"content": "",
"summaryContent": "",
"publishedDate": "2015-07-21T10:07:58Z",
"harvestDate": "2015-07-21T11:23:23Z",
"languageId": 1,
"regionId": 249,
"postStatus": 0,
"mediaProvider": {
"id": "2",
"title": "YouTube",
"mediaTypeId": 2,
"extendedMediaType": null
},
"source": {
"id": "2229562169",
"title": "Tennis Star visits Malawi",
"externalLink": "youtube.com",
"language": "en",
"region": null,
"tags": [
{
"id": "7494",
"value": "Sample source tag"
}
],
"comments": [
{
"id": "56436",
"value": "Sample source comment",
"noteTypeId": "4"
}
]
},
"author": {
"id": "-1",
"title": "YouTube Channel",
"externalId": "-1",
"externalLegacyId": null,
"authorFullName": "YouTube Channel",
"avatar": null,
173
Posts Retrieve Posts
"authorTags": [
{
"id": "5567567",
"value": "Sample author tag"
}
],
"authorComments": [
{
"id": "556456456",
"value": "Sample author comment"
}
],
"bio": null,
"verified": false
},
"parent": null,
"sentiment": null,
"postStatusException": null,
"engagement": 4564,
"classification": 4,
"tags": [
{
"id": "5466546",
"value": "Sample tag"
}
],
"postDynamics": [
{
"fieldId": "5",
"label": "View Count",
"value": "0"
},
{
"fieldId": "1",
"label": "Comment Count",
"value": "0"
},
{
"fieldId": "2",
"label": "Unique Commenters",
"value": "0"
},
{
"fieldId": "3",
"label": "Engagement",
"value": "0"
},
{
"fieldId": "4",
"label": "Likes and Votes",
"value": "0"
},
{
"fieldId": "7",
174
Posts Retrieve Posts
*id* - integer value indicating unique identifier for post object, used to assign and
access workflow associated with post
*title* - string value containing description of post
*externalId* - integer value indicating unique ID for post assigned by original social
media channel (such as Facebook or Twitter)
*externalLink* - string value containing URL of original post
*sourceApplication* - string value for name of application that created Twitter content
*content* - string value containing text of original post, including links
*summaryContent* - string value reserved for internal use (will always return empty)
*harvestDate* - timestamp value indicating when Social Studio discovered and indexed post
*languageId* - integer value indicating supported language for post (review Languages route
for available IDs)
*regionId* - integer value indicating region associated with post (review region route for
available IDs)
*postStatus* - integer value indicating post status:
*0* - normal, active post
*1* - spam (auto-detected)
*2* - deleted or hidden post (based on user action)
*sentiment* - integer value indicating manually assigned sentiment value (requires
includeWorkflow=true)
*postStatusException* - integer value indicating manually assigned post status value
(requires includeWorkflow=true)
175
Posts Retrieve Posts
176
CHAPTER 20 Engage Macros
In this chapter ... This endpoint allows you to configure predefined metadata to automatically apply when performing a
workflow on posts in Engage and Analyze scenarios. For example, you might want to apply a macro
Retrieve Macros whenever you see a social post that mentions the brand in the following manner:
Retrieve Macro
@Brand, my laptop just crashed! Need help asap!
Create Macro
Update Macro The macro would execute the following actions:
Execute Macro *Add a post tag *Laptop*
Delete Macro *Set priority as *High*
*Send to Salesforce as a case
Retrieve
SalesforceOrgs
Retrieve
SalesforceOrg
Create Macro
First, create a macro to define workflow tasks to execute:
POST /v3/macros
cURL Example
curl -X POST -H "access_token: 82200099-7799-4023-b76d-11bb7c941bf1"
-H "Content-Type: application/json" -d '{
"name": "Urgent - Laptop Support Issue",
"description": "Urgent Laptop Issues to be addressed ASAP",
"actions": [
{
"type": "SetPriority",
"value": "3"
},
{
"type": "AddPostNote",
"value": "Laptop"
},
{
"type": "SendToSalesforceScs",
"value": "00DD00000007aAJMAY",
"parameters": [
{
"name": "case",
"value": "on"
},
177
Engage Macros
{
"name": "lead",
"value": "off"
}
]
}
]
}' 'https://api.socialstudio.radian6.com/v3/macros'
Apply Macro
Once you create a macro, you can apply it to a post:
POST /v3/macros/{id}?action=execute
cURL Example
curl -X POST -H "Content-Type: application/json" -H "access_token:
82200099-7799-4023-b76d-11bb7c941bf1" -d '{
"posts" : [1868932796],
"topics" : [8]
}'
'https://api.socialstudio.radian6.com/v3/macros/23114?action=execute'
178
Engage Macros Retrieve Macros
Retrieve Macros
This method retrieves all macros within a Social Studio organization. This macro can contain several different actions within the JSON
payload, indicating actions to perform when the macro receives an execute call. Use the Salesforce Organzation methods to retrieve
necessary Service Cloud values for this call.
/v3/macros
HTTP Method
GET
Query Parameters
Sample Request
GET /v3/macros
Sample Response
A successful call returns the following response (can be an array of macros:
"data": [
{
"id": 322,
"name": "Forward to Salesforce",
"description": "Sends post for further investigation",
"owner": {
"id": "1827",
"title": "John.Smith@domain.com",
"avatarURL": null
},
"client": 1,
"createdDate": "2014-03-26T16:04:29Z",
"modifiedDate": null,
"actions": [
{
"type": "SendToSalesforceScs",
"value": "00DR00000008ioUFGY",
179
Engage Macros Retrieve Macros
"parameters": [
{
"name": "case",
"value": "on"
},
{
"name": "lead",
"value": "on"
}
]
}
]
}
],
"meta": {
"totalCount": 1
}
}
180
Engage Macros Retrieve Macro
Retrieve Macro
This method retrieves a macro within a Social Studio organization. This macro can contain several different actions within the JSON
payload, indicating actions to perform when the macro receives an execute call. Use the Salesforce Organzation methods to retrieve
necessary Service Cloud values for this call.
Resource
/v3/macros/{id}
HTTP Method
GET
Request Parameters
Sample Request
GET /v3/macros/1234
Sample Response
A successful call returns the following response (can be an array of macros:
"data": [
{
"id": 322,
"name": "Forward to Salesforce",
"description": "Sends post for further investigation",
"owner": {
"id": "1827",
"title": "John.Smith@domain.com",
"avatarURL": null
},
"client": 1,
"createdDate": "2014-03-26T16:04:29Z",
"modifiedDate": null,
"actions": [
{
181
Engage Macros Retrieve Macro
"type": "SendToSalesforceScs",
"value": "00DR00000008ioUFGY",
"parameters": [
{
"name": "case",
"value": "on"
},
{
"name": "lead",
"value": "on"
}
]
}
]
}
],
"meta": {
"totalCount": 1
}
}
182
Engage Macros Create Macro
Create Macro
This method creates a macro within a Social Studio organization. This macro can contain several different actions within the JSON payload,
indicating actions to perform when the macro receives an execute call. Use the Salesforce Organzation methods to retrieve necessary
Service Cloud values for this call.
Resource
/v3/macros
HTTP Method
POST
Request Parameters
None
JSON Parameters
183
Engage Macros Update Macro
Sample Request
POST /v3/macros
{
"name" : "Add post tag",
"description" : "Adds a tag to a post",
"actions": [
{
"type": "AddPostTag",
"value": "Post Tag"
}
]
}
Sample Response
A successful call returns the following response:
{
"data": [
{
"id": "23719"
}
],
"meta": {
"totalCount": 1
}
}
Update Macro
This method updates a macro within a Social Studio organization. This macro can contain several different actions within the JSON
payload, indicating actions to perform when the macro receives an execute call. Use the Salesforce Organzation methods to retrieve
necessary Service Cloud values for this call.
Resource
/v3/macros/{id}
184
Engage Macros Update Macro
HTTP Method
PUT
Request Parameters
JSON Parameters
Sample Request
PUT /v3/macros/1234
{
"name": "My Macro",
"description": "Macro Description",
"actions": [
{
185
Engage Macros Execute Macro
"type": "AddPostTag",
"value": "Post Tag"
}
]
}
Sample Response
A successful call returns HTTP 200
Execute Macro
This method executes a macro within a Social Studio organization. Use the Salesforce Organzation methods to retrieve necessary Service
Cloud values for this call.
Resource
/v3/macros/{id}
HTTP Method
POST
Request Parameters
Query Parameters
JSON Parameters
*posts* - array of integer values identifying posts included in the running macro
*topics* - array of integer values identifying topics included in the running macro
186
Engage Macros Delete Macro
Sample Request
POST /v3/macros/{id}?action=execute
{
"posts": [2345],
"topics" : [8]
}
Sample Reponse
A successful call returns the following response:
{
"results": [
{
"postId": <2345>,
"action": "AddPostTag",
"result": "SUCCESS",
"error": ""
}
]
}
Delete Macro
This method deletes a macro within a Social Studio organization. Use the Salesforce Organzation methods to retrieve necessary Service
Cloud values for this call.
187
Engage Macros Retrieve SalesforceOrgs
Resource
/v3/macros/{id}
HTTP Method
DELETE
Request Parameters
Sample Request
DELETE /v3/macros/{id}
Sample Reponse
A successful call returns a No Content 204 code, indicating the call succeeded and no content exists.
A call that matches no macro ID value returns a 404 Not Found code.
Retrieve SalesforceOrgs
This method returns information on all Salesforce organizations registered within the tenant for the user executing the call.
/v3/salesforceOrganizations
HTTP Method
GET
Request Parameters
None
188
Engage Macros Retrieve SalesforceOrg
Sample Request
GET /v3/salesforceOrganizations
Sample Request
A successful call returns the following response:
{
"data": [
{
"id": "00D61000000YMhPABC",
"title": "prod.r64sf",
"isSCS": false,
"isSandbox": false,
"isPersonAccountCapable": false,
"adminEmail": "john.doe@salesforce.com",
"integrationUserId": 6110,
"tenantId": 1
}],
"meta" : {
"totalCount" : 1
}
}
*id* - string value containing the 18-character unique ID for the Salesforce organization
*link* - string value containing the URL location for the organization
*updated* - timestamp value indicating when the last organization update occured
*title* - string value indicating the name of the organization
*isSCS* - boolean value indicating whether the organization uses the Social Cloud
*isSandbox* - boolean value indicating whether the organization functions as a developer
sandbox
*isPersonAccountCapable* - boolean value indicating whether the organization can use person
accounts
*adminEmail* - string value including the email address for the organization administrator
*integrationUserId* - integer value indicating the unique ID for the organization integration
user
*tenantId* - integer value indicating the unique ID for the tenant associated with the
Salesforce organization
Retrieve SalesforceOrg
This method returns information on a specified Salesforce organization registered within the tenant for the user executing the call.
/v3/salesforceOrganizations/{id}
189
Engage Macros Retrieve SalesforceOrg
HTTP Method
GET
Request Parameters
*id* - string value containing the 18-character unique ID for the Salesforce organization
(required)
Sample Request
GET /v3/salesforceOrganizations/00DA00000000000001
Sample Request
A successful call returns the following response:
{
"id": "00DA00000000000001",
"link":
"https://stg3-api.dev.ca1.sfmc.co/socialcloud/v3/salesforceOrganizations/00DA00000000000001
",
"updated": "2015-01-01T00:00:00Z",
"title": "Organization Name",
"isSCS": true,
"isSandbox": false,
"isPersonAccountCapable": false,
"adminEmail": "orgowner@example.com",
"integrationUserId": 10010010,
"tenantId": 1
}
*id* - string value containing the 18-character unique ID for the Salesforce organization
*link* - string value containing the URL location for the organization
*updated* - timestamp value indicating when the last organization update occured
*title* - string value indicating the name of the organization
*isSCS* - boolean value indicating whether the organization connects to the Service Cloud
via Social Customer Service integration
*isSandbox* - boolean value indicating whether the organization functions as a developer
sandbox
*isPersonAccountCapable* - boolean value indicating whether the organization can use person
accounts
*adminEmail* - string value including the email address for the organization administrator
*integrationUserId* - integer value indicating the unique ID for the organization integration
190
Engage Macros Retrieve SalesforceOrg
user
*tenantId* - integer value indicating the unique ID for the Social Studio tenant associated
with the Salesforce organization
191