• Version: 2
  • Host: api.spredfast.com/v2
  • Protocols: https
  • Accepts: application/json
  • Responds With: application/json, text/plain

Welcome to the Khoros Marketing Conversations API. Using this API you can access many of the features of the Khoros Marketing platform including publishing and reporting.

Prerequisites

In order to make an API call to the platform, you must have the following:

• A valid login for the platform (used to retrieve an access token, described below)
• An assigned client id for your application
• That client id enabled for your company in conversations If you are reading this documentation you already have your login! Let's proceed with the next two steps.

Authentication and Authorization

Khoros Marketing uses the OAuth standard for API authorization. OAuth specifies the manner in which a bearer token may be obtained that will authorize your API calls. OAuth tokens are managed from the same authentication system as your web logins. All company security policies including SAML SSO integration are supported and enforced.

Client Id

A client id uniquely identifies your application. There is a whitelist in place to control which applications have access to your company in Conversations. This allows you to control when an application is activated for your company.

To retrieve your client id, please have your company admin-contact support and request a new or pre-existing client id. Please provide a description of your application. You may also request this application be enabled for your company if you are the company administrator.

Support will respond with a client id and a client secret, both of which are needed to obtain an access token.

Browser Redirection Flow

If you are building a web application where your users will interact with a UI to authenticate against Khoros Marketing, you are advised to implement the OAuth browser redirection flow. There are many resources available on the web on how to implement this flow, but the basic process is shown below:

You will redirect the user to login.spredfast.com with the following URL:

https://login.spredfast.com/v3/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=https%3A%2F%2FYOUR_URL&state=none

Replace YOUR CLIENT ID with the id of your API client and YOUR URL with the URL of your web application the user should return two once an OAuth Grant has been obtained.

When the user returns to your website there will be a URL parameter called "code" set. This is an authorization code that you must use to obtain an access token. Make a POST call to the following endpoint to obtain your access token:

curl https://login.spredfast.com/v3/oauth/token \
	-H "Accept: application/json" \
	--data 'client_id=YOUR_CLIENT_ID' \
	--data 'client_secret=YOUR_CLIENT_SECRET' \
	--data 'redirect_uri=https://YOUR_URL' \
	--data 'code=CODE_RETURNED'

Once again substitute YOUR_CLIENT_ID for your client id. You must also provide your client secret in YOUR_CLIENT_SECRET and the code you received in CODE_RETURNED.

You will receive a JSON response that contains your access token in a response like this:

{
   "data":{
      "sfEntityType":"Token",
      "accessToken":"XXX",
      "expiryTime":1519770939876
   },
   "status":{
      "succeeded":true
   }
}

Tokens are issued with a 2 year lifetime. Save this token in a secure place. It’s a bearer token and is all that is needed to make API calls on your behalf.

Alternative Login Methods

Alternative login methods are described in the Getting Started With The Conversations API article.

DEVELOPER NOTES

While developing against the Khoros Marketing API you will be using your own Khoros Marketing API App (client_id/secret pair).

Access Token Expiration

Access tokens are valid for 24 months. You may refresh these tokens at any time by repeating the authorization flow.

API Path Construction

Conversations APIs have several required parameters for all API calls. All Conversations APIs have the following URL path scheme: https://api.spreadfast.com/v2/conversations

API Overview

Khoros Marketing Conversations offers APIs to manage content and plans, publish content, and retrieve analytics reports.

Publishing

Publishing requires you to select an initiative and an account set. To retrieve the list of initiatives use the /conversations/initiative call. To list the accounts available with that initiative, use the /conversations/initiative/{initiativeId}/accountset call.

Once you have these parameters you may publish content. For status updates (text) and images you publish with a single call. For video publishing, you must first upload the video into the Conversations Content Center.

Status updated may be published with the /conversations/initiative/{initiativeId}/message call. You will send your content as a JSON POST. For example:

{
   "sfEntityType":"Message",
   "service":"TWITTER",
   "content":{
      "sfEntityType":"Status",
      "text":"Status Update"
   },
   " targetAccountIds":[
      "4"
   ]
}