Introduction
The Oktopost API provides programmatic access to read and write Oktopost data. The following docs describe the resources that make up the API. If you have any questions please contact us.
Authentication
All API requests must be authenticated using Basic HTTP Auth. Authentication is performed using an Oktopost Account Id as the username and an API Key as the password. Both values can be found on the My Profile tab in your account.
- All API requests are subjected to the permissions set available for the user requesting the data.
- If the user does not have permissions to perform the action, the API response will be 403 (permission denied).
- If the user does not have access to a certain object, the API response will be 404 (not found).
Base URL
The API's base URL depends on the data center your account is hosted on. If your account is hosted on the US data center, your base URL should be:
api.oktopost.comAnd if your account is hosted on the EU data center, your base URL should be:
eu-api.oktopost.comNote that all API access is available using HTTPS only.
Schema
All data is sent back to the client in a standard JSON format. And all timestamps are sent and received in UTC EPOCH (number of seconds since January 1st, 1970, UTC timezone).
Limiting Requests
The API has a daily rate limit of 20,000 calls per user. The limit resets every day at midnight UTC. Burst rates allow up to 60 calls per minute and 120 calls per 5-second window.
Note that exceeding the burst limit will result in a 15-minute block on additional calls.
Error Handling
The API uses conventional HTTP response codes to indicate success or failure of an API call. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing or the API key was wrong), and codes in the 5xx range indicate an error on the Oktopost side.
HTTP Status Code Summary
| Code | Description |
|---|---|
| 20x | OK - Everything worked as expected. |
| 400 | Bad Request - Often missing a required parameter. |
| 401 | Unauthorized - No valid API key provided. |
| 404 | Not Found - The requested item does not exist. |
| 429 | Too Many Requests - The requests limit has been reached. |
| 50x | Server errors - Something went wrong on our end. |
Every set of results will contain the Result parameter which indicates if the response was successful or not. In case an error was captured, an Errors parameter will be returned as-well. For example:
{
"Result":false,
"Errors":{
"API":{
"Error":"The page you are looking for was not found"
}
}
}Pagination
All API endpoints that return lists of objects share a common structure. The following parameters can be used to iterate between pages and determine the number and order of the result set.
| Param | Default | Description |
|---|---|---|
| _count | 25 | The number of items per page. Unless specified otherwise, options are: 25, 50 and 100 |
| _page | 0 | The current page |
| _order | created,0 | The order of the result set. 0 means descending and 1 means ascending |
Example Request
curl -i https://api.oktopost.com/v2/campaign?_count=100&_page=1&_order=created,0Example Result
{
"Result":true,
"Items":[...],
"Total":1024
}Accounts
This endpoint allows you to provision instances of Oktopost to your customers, in addition to managing basic account information.
This endpoint is available for partners only.
List Accounts
Example Request
curl -i https://reseller.oktopost.com/account?query=AcmeExample Result
{
"Result": true,
"Items": [
{
"Id": "001000000000001",
"Name": "Acme",
"Created": "2017-06-01 00:00:00",
"Status": "active",
"LicenseId": "017_SUB_XXXXX_V7",
"LastLogin": "2017-06-1 12:00:00",
"Timezone": "America/New_York",
"CredentialCount": 0,
"CampaignCount": 0,
"OwnerName": "John Doe",
"TotalUsers": 1,
"ActiveUsers": "1",
"ActiveBoardUsers": "0",
"ExternalID": null
}
],
"Total": 1
}Get Account
Example Request
curl -i https://reseller.oktopost.com/account/001000000000001Example Result
{
"Result": true,
"Items": [
{
"Id": "001000000000001",
"Name": "Acme",
"Created": "2017-06-01 00:00:00",
"Status": "active",
"LicenseId": "017_SUB_XXXXX_V7",
"LastLogin": "2017-06-1 12:00:00",
"Timezone": "America/New_York",
"CredentialCount": 0,
"CampaignCount": 0,
"OwnerName": "John Doe",
"TotalUsers": 1,
"ActiveUsers": "1",
"ActiveBoardUsers": "0",
"ExternalID": null
}
],
"Total": 1
} Create Account
Example Request
curl -i https://reseller.oktopost.com/account -X POST \
-d firstName="John"
-d lastName="Doe"
-d company="Acme Inc"
-d email="john.doe@acme.com"
-d password="123456"
-d licenseId="017_SUB_XXXX_V7"
-d eid="EXTERNAL_ID"The eid represents your internal system identifier. If left empty, this field will simply be ignored. If used, you will not be able to use it again for account creation but, you will be able to search, get and update accounts using it instead of the standard Oktopost account id.
Example Result
{
"Result": true,
"data": {
"NewAccountId": "001000000000001",
"NewAccountName": "Acme",
"LicenseId": "017_SUB_XXXX_V7",
"OwnerFirstName": "John",
"OwnerLastName": "Doe",
"OwnerEmail": "john.doe@acme.com",
"OwnerUserId": "00A000000000001",
"OwnerApiKey": "2c51539e18e1f54ef0520b8529688ca757ac56dc01cd39.XXXXXXX"
}
}Update Account
Example Request
curl -i https://reseller.oktopost.com/account/001000000000001 -X POST \
-d status="active|inactive"
-d company="Acme"
-d licenseId="017_SUB_XXXX_V7" Example Result
{
"Result": true
}Account Metrics
This endpoint contains basic account usage metrics including the number of user logins and number posts that were scheduled or posted through the platform.
This endpoint is available for partners only.
Get Account Metrics
Input
| Param | Type | Description |
|---|---|---|
| id | String | Account Id. Accepts both Oktopost and external reference Id. |
| since | Integer | Optional. Accepts 1 to 90 days. The default is 1. |
Example Request
curl -i https://reseller.oktopost.com/account-metrics/00100000000000x?since=7Example Result
{
"Result": true,
"AdvocateLogins": 34,
"UserLogins": 3,
"BoardMessages": 19,
"PostsScheduled": 15,
"PostsSent": 23
}Advocates
Advocates are employees or other individuals who promote a company on social media channels. In Oktopost, advocates are system users and members of the advocacy board. The following endpoint allows you to get, list, add and delete advocates from the social advocacy board.
Get Advocate
Example Request
curl -i https://api.oktopost.com/v2/advocate/00A000000000001?boardId=brd000000000001Note that the boardId parameter is optional. If provided, the response will include Topics and LatestShares.
Example Result
{
"Result": true,
"Advocate": {
"Id": "00A000000000000",
"Created": "2012-03-25 18:48:32",
"Modified": "2018-09-26 13:27:55",
"Status": "active",
"Name": "Liad Guez",
"FirstName": "Liad",
"LastName": "Guez",
"Email": "liad@oktopost.com",
"PictureUrl": null,
"LastBoardLogin": "2018-09-12 17:18:42",
"Profiles": [
{
"Id": "003-001000000000000-10795428XXXXXXXXX",
"Created": "2015-10-26 21:02:30",
"Name": "Oktopost's Twitter",
"Status": "valid",
"Network": "Twitter",
"ImageLink": "valid",
"NetworkUsername": "oktopost"
}
],
"BoardIds": [
"brd000000000001"
],
"Topics": [
"tpc000000000001"
],
"LatestShares": [
{
"Id": "004000000000000",
"Created": "2018-09-12 18:29:42",
"CreatedBy": "00A000000000000",
"Network": "Twitter",
"CredentialId": "003-001000000000000-10795428XXXXXXXXX",
"CredentialImage": "...",
"Message": "Good Vs. Bad #SocialMedia Management Platforms: 5 Capabilities You Need to Build a Data-Driven #B2BMarketing Team",
"ImageUrl": "",
"LinkUrl": "",
"LinkTitle": "",
"Description": "",
"Picture": null,
"Type": "status-update",
"Media": null,
"StartDateTime": "2018-09-12 18:29:38",
"EndDateTime": "2019-03-13 03:59:59",
"Status": "complete",
"Source": "Board",
"TargetGeo": ""
}
]
}
}List Advocates
Example Request
curl -i https://api.oktopost.com/v2/advocateExample Result
{
"Result": true,
"Items":[
{
"Email": "saul@goodman.com",
"Id": "00A000000000001",
"LastBoardLogin": "2018-04-15 10:03:11",
"Name": "Jimmy Mcgill",
"PictureUrl": null
},
...
],
"Total": 89
}Filter Advocates by email
Example Request
curl -i https://api.oktopost.com/v2/advocate?email=saul%40goodman.comExample Result
{
"Result": true,
"Items":[
{
"Email": "saul@goodman.com",
"Id": "00A000000000001",
"LastBoardLogin": "2018-04-15 10:03:11",
"Name": "Jimmy Mcgill",
"PictureUrl": null
}
]
"Total": 1
}Invite Advocates
Example Request
curl -i https://api.oktopost.com/v2/advocate -X POST \
-d firstName="Jimmy" \
-d lastName="Mcgill" \
-d email="saul@goodman.com" \
-d boardId="brd000000000001"Example Result
{
"Result": true
}Delete Advocate
Example Request
curl -i https://api.oktopost.com/v2/advocate/00A000000000001?boardId=brd000000000001 -X DELETEExample Result
{
"Result": true
}Board Message
Board messages are the message assets that advocates can share from the employee advocacy board. You can use this endpoint to add and remove messages from the board.
Add Board Message
Parameters
| Param | Description |
|---|---|
| boardId | The board Id. |
| messageId | The message Id. |
| startDate | Optional. Format: YYYY-MM-DD hh:mm:ss (UTC). The message publish date on the board. The default is now. |
| expireDate | Optional. Format: YYYY-MM-DD hh:mm:ss (UTC). The messages' expiration date. The default is based on the boards' settings. |
| important | Optional. 0 or 1. Important messages are sent to advocates in a notification as soon as they're published on the board. |
| topicIds | Optional. A comma-separated list of topic Ids. |
Example Request
curl -i https://api.oktopost.com/v2/board-message -X POST \
-d boardId=brd000000000001 \
-d messageId=002000000000001 \
-d startDate="2020-11-01 12:00:00" \
-d expireDate="2021-03-01 12:00:00" \
-d important=1 \
-d topicIds=tpc000000000001,tpc000000000002Example Result
{
"Result": true
}Remove Board Message
Example Request
curl -i https://api.oktopost.com/v2/board-message?boardId=brd000000000001&messageId=002000000000001 -X DELETEBoard Topics
Board topics allow advocates to choose which messages they want to share thematically. Oktopost users can assign topics to messages on the board, while advocates can view and filter messages by topic. You can use this endpoint to list, create, update, and delete topics.
List Topics
- q (Optional) Search for topics by name.
- boardId (Optional) Limit the results by board.
Example Request
curl -i https://api.oktopost.com/v2/board-topicExample Result
{
"Result": true,
"Items": [
{
"Id": "tpc000000000001",
"Name": "Blog",
"BoardId": "brd000000000001",
"Used": "0",
"Subscribers": "0",
"LastUsedDate": "2020-11-01 07:57:07"
},
{
"Id": "tpc000000000002",
"Name": "Canada",
"BoardId": "brd000000000001",
"Used": "0",
"Subscribers": "0",
"LastUsedDate": "2020-11-03 02:56:52"
},
{
"Id": "tpc000000000003",
"Name": "Summer",
"BoardId": "brd000000000002",
"Used": "0",
"Subscribers": "0",
"LastUsedDate": "2020-11-07 07:10:44"
},
{
"Id": "tpc000000000004",
"Name": "Information",
"BoardId": "brd000000000002",
"Used": "2",
"Subscribers": "2",
"LastUsedDate": "2020-10-01 23:47:31"
}
],
"Total": 4
}Add Topic
Note that when you create a new topic, advocates on the board will see a notification to subscribe to it the next time they log in.
Example Request
curl -i https://api.oktopost.com/v2/board-topic -X POST \
-d boardId=brd000000000001 \
-d name="Topic Name"Example Result
{
"Result": true,
"Topic":
{
"Id": "tpc000000000004",
"Name": "Information",
"BoardId": "brd000000000002",
"Used": "7",
"Subscribers": "7",
"LastUsedDate": "2020-10-01 23:47:31"
}
}Update Topic
Example Request
curl -i https://api.oktopost.com/v2/board-topic/tpc000000000001 -X POST \
-d name="Topic Name"Example Result
{
"Result": true,
"Topic":
{
"Id": "tpc000000000004",
"Name": "Disinformation",
"BoardId": "brd000000000002",
"Used": "7",
"Subscribers": "7",
"LastUsedDate": "2020-10-01 23:47:31"
}
}Delete Topic
Example Request
curl -i https://api.oktopost.com/v2/board-topic/tpc000000000001 -X DELETEBoards
The Employee Advocacy Board is a platform where advocates can share posts on their social media channels. Each board contains information on users who signed up as advocates and messages that were shared with them. This endpoint allows retrieving social advocacy boards from Oktopost and their configurations.
Get Board
Example Request
curl -i https://api.oktopost.com/v2/board/brd000000000001Example Result
{
"Result": true,
"Board": {
"Config": {
"Color": "#27373f",
"DefaultExpiration": "in_6_months",
"IconId": "",
"IsAllowSuggestionsEnabled": false,
"IsLeaderboardEnabled": true,
"LogoId": "",
"LogoPosition": "center",
"NotificationsDay": null,
"NotificationsEnabled": true,
"NotificationsTimeUTC": "10",
"PostAddress": "",
"SignUpDomains": false,
"SignUpEnabled": false,
"Slug": "",
"Terms": ""
},
"Created": "2016-10-30 11:23:34",
"Id": "brd000000000001",
"Name": "My Board",
"Status": "active",
"UsersCount": 0
}
}List Boards
Example Request
curl -i https://api.oktopost.com/v2/boardExample Result
{
"Result":true,
"Items":[
{
"Config": {
"Color": "#27373f",
"DefaultExpiration": "in_6_months",
"IconId": "",
"IsAllowSuggestionsEnabled": false,
"IsLeaderboardEnabled": true,
"LogoId": "",
"LogoPosition": "center",
"NotificationsDay": null,
"NotificationsEnabled": true,
"NotificationsTimeUTC": "10",
"PostAddress": "",
"SignUpDomains": false,
"SignUpEnabled": false,
"Slug": "",
"Terms": ""
},
"Created": "2016-10-30 11:23:34",
"Id": "brd000000000001",
"Name": "My Board",
"Status": "active",
"UsersCount": 0
},
...
],
"Total":2
}BI Exports
With Oktopost, you can quickly export reports and dashboards from your account and share them with your colleagues in user-friendly formats or send them to external reporting systems. You can use this endpoint to view exported files from your account.
List Exports
Will return the exports list.
Parameters
| Param | Default | Description |
|---|---|---|
| _page | 0 | Current page |
| _order | status,1 | Options: type, status, dest, last and freq. 0 means descending and 1 means ascending |
| status | - | Options: active, inactive |
Example Request
https://api.oktopost.com/v2/bi-exportExample Response
{
"Result": true,
"Exports": [
{
"Id": "032XXXXXXXXXXXX",
"DestinationType": "email",
"Destination": {
"Email": "john.doe@acme.com",
"FirstName": "John",
"LastName": "Doe"
},
"Type": "Posts",
"Frequency": "Every day at 10:00 AM",
"TimeRange": "Last 30 Days",
"Status": "active"
}
],
"Total": 30
}Example Destinations
// azure
{
"AccountName": "Acme",
"Container": "AcmeContainer"
},
// email
{
"Email": "john.doe@acme.com",
"FirstName": "John",
"LastName": "Doe"
},
// FTP
{
"Host": "acme.com",
"Port" :21,
"Timeout" :10,
"Directory": "path/to/destination",
"Username": "",
"Password": ""
},
// SFTP
{
"Host": "acme.com",
"Port" :21,
"Timeout" :10,
"Directory": "path/to/destination",
"Username": "",
"Password": ""
},
// S3_bucket
{
"BucketName": "AcmeBucket",
"Path": "path/to/destination"
}Get Export
Will return the metadata for a single export and a temp link to download the last file.
Example Request
https://api.oktopost.com/v2/bi-export/032XXXXXXXXXXXXExample Response
{
"Result": true,
"Export": {
"Id": "032XXXXXXXXXXXX",
"DestinationType": "Email",
"Destination": {
"Email": "john.doe@acme.com",
"FirstName": "John",
"LastName": "Doe"
},
"Type": "Posts",
"Frequency": "Every day at 10 AM",
"TimeRange": "Last 30 Days",
"Status": "inactive",
"LastRunDate": "2020-07-27 08:31:45",
"LastRunFile": "https://com-oktopost-bi-export.s3.amazonaws.com/001XXXXXXXXXXXX/..."
}
}Calendar
A campaign is an organized collection of posts dedicated to a specific marketing activity or topic. Every post scheduled via the platform is assigned to a specific campaign in the system. The following endpoint can be used to read, create, update and delete campaigns.
Get Calendar
Example Request
curl -i https://api.oktopost.com/v2/calendar -X POST
-d fromDate=2018-02-01 \
-d toDate=2018-02-20Example Result
{
"Campaigns": {
"002000000000001": {
"Color": "#3492bf",
"Id": "002000000000001",
"Name": "2018-02 General Campaign",
"Status": "complete"
}
},
"Credentials": {
"003-001000000000001-1234": {
"BoardOnly": 0,
"DisplayName": "OktoTest1",
"ExpiresOn": "3999-12-31 23:59:59",
"Id": "003-001000000000001-1234",
"ImageLink": "https://s3.amazonaws.com/dev-com-oktopost-app-credential-pictures/Facebook-1234.png",
"IsHidden": 0,
"Name": "OktoTest (Page)",
"Network": "Facebook",
"NetworkAccountId": "1234",
"NetworkUsername": "1234",
"ParentCredentialId": "003-001000000000001-100001878919601",
"Status": "valid"
}
},
"Media": [],
"Messages": {
"005000000000001": {
"CampaignId": "002000000000001",
"Clicks": 0,
"Converts": 0,
"Description": "Oktopost is a social media management platform designed to publish social messages, engage with social sales and support employee social advocacy",
"Id": "005000000000001",
"ImageUrl": "https://s3.amazonaws.com/dev-com-oktopost-app-message-pictures/0010000000000015a8acb3e6e9d47.59722266/imac-from-side.jpg",
"IsBoardMessage": 0,
"LinkTitle": "Social Media Management for B2B Marketing - Oktopost",
"LinkUrl": "https://www.oktopost.com/",
"MediaIds": [],
"Message": "hello https://www.oktopost.com/",
"MessageLength": 31,
"Network": "Facebook",
"Status": "default",
"Subject": "",
"Type": "link-attachment",
"Url": ""
}
},
"Posts": {
"004000000000001": {
"CampaignId": "002000000000001",
"Clicks": 0,
"ContentSource": "User",
"Converts": 0,
"CredentialIds": [
"003-001000000000001-1234"
],
"Id": "004000000000001",
"MessageId": "005000000000001",
"Network": "Facebook",
"Source": "UI",
"StartDateTime": "2018-02-19 08:03:00",
"Status": "complete",
"ApproveStatus": "Approved",
"TotalCount": 1
}
},
"Result": true
}Parameters
| Param | Description |
|---|---|
| fromDate | Required. Format: YYYY-MM-DD |
| toDate | Required. Format: YYYY-MM-DD |
| filters | Optional. JSON Object. See structure below |
Filters
The following parameters can be used to build the filters object in your request.
| Param | Type | Description |
|---|---|---|
| campaigns | Array | See Campaigns API |
| credentials | Array | See Profiles API |
| messages | Array | See Message API |
| networks | Array | Options: Facebook, Twitter, LinkedIn, Instagram, and Youtube |
| postSources | Array | See Post API |
| statuses | Array | See Post API |
| users | Array | See Users API |
Example request with filters
curl -i https://api.oktopost.com/v2/calendar -X POST
-d fromDate=2018-02-01 \
-d toDate=2018-02-20 \
-d filters={"campaigns": ["002000000000001"]}Campaigns
The following endpoint can be used to read, create, update and delete Oktopost campaigns.
Get Campaign
Get a single campaign by Id.
Parameters
| Param | Default | Description |
|---|---|---|
| withTags | 0 | Includes the campaign tags in the response. |
Example Request
curl -i https://api.oktopost.com/v2/campaign/002000000000000?withTags=1Example Result
{
"Result":true,
"Campaign": {
"Id":"002000000000000",
"Created":"2015-09-24 22:11:36",
"Modified":"2015-09-24 22:11:40",
"Name":"Oktopost Rocks",
"Status":"active",
"AccountId":"001000000000000",
"CreatedBy":"00A000000000000",
"ModifiedBy":"00A000000000000",
"Url":"",
"Color":"#de8736",
"ShortUrl":"",
"StartDate":"0000-00-00 00:00:00",
"EndDate":"0000-00-00 00:00:00",
"LastConversionDate":"0000-00-00 00:00:00",
"LastCommentFound":"0000-00-00 00:00:00",
"SendSummary":"",
"Clicks":0,
"ChildClicks":0,
"BoardClicks":0,
"Converts":0,
"ChildConverts":0,
"BoardConverts":0,
"Comments":0,
"NewComments":0,
"Likes":0,
"TotalMessages":0,
"TotalPosts":0,
"TotalPendingPosts":0,
"TotalDraftPosts":0,
"SFDCCampaignId":"701b0000000NOhlAAG",
"SFDCCampaignName":"Oktopost: Hello",
"SFDCCampaignOption":"account-campaign-only",
"Utm":"",
"Tags":
[
"pr",
"smms"
]
}
}List Campaigns
Get all campaigns.
Parameters
| Param | Default | Description |
|---|---|---|
| q | - | Filters by search term. |
| status | - | Filters by the campaigns' status. Options: active, complete, paused, or archived. |
| withTags | 0 | Includes the campaign tags in the response. |
Example Request
curl -i https://api.oktopost.com/v2/campaignExample Result
{
"Result":true,
"Items":[
{
"Id":"002000000000000",
"Name":"Hello World",
"TotalPosts":0,
"TotalPendingPosts":0,
"TotalDraftPosts":0,
"Clicks":0,
"Converts":0,
"Created":"2015-09-24 22:11:36",
"Status":"active",
"Comments":0,
"PostsSent":0
},
...
],
"Total":193
}Create Campaign
Parameters
| Param | Description |
|---|---|
| name | The campaign name. |
| url | Optional. The campaign URL. It allows users to insert a URL more quickly when creating posts. |
| tagIds | Optional. A comma separated list of Tag Ids. Campaign tags apply to all messages in the campaign unless the user changes them. |
Example Request
curl -i https://api.oktopost.com/v2/campaign -X POST \
-d name="Oktopost Rocks" \
-d url="https://www.oktopost.com" \
-d tagIds=0AF000000000001,0AF000000000002Example Result
{
"Result":true,
"Campaign":{...}
}Update Campaign
When updating a campaign, all parameters become optional, and you have another option to set the campaign status as described below.
| Status | Description |
|---|---|
| active | The campaign is active and visible to users. |
| paused | The campaign is visible to users, but scheduled posts in this campaign won't go out. |
| archived | The campaign is archived and all scheduled posts are deleted. |
Example Request
curl -i https://api.oktopost.com/v2/campaign/002hdrn7bv1iogb -X POST \
-d name="Oktopost Rocks Again" \
-d url="https://www.oktopost.com/tour/social-media-publishing" \
-d status="active" \
-d tagIds=0AF000000000001,0AF000000000002Example Result
{
"Result": true,
"Campaign": {...}
}Delete Campaign
Example Request
curl -i https://api.oktopost.com/v2/campaign/00243ZdmqL9gwkM -X DELETEClicks
Every link shared through the platform is shortened by the okt.to link shortener. Each click record represents a user who clicked on an okt.to link. A click record contains information about the post, campaign, user browser, user device, and user location. The following endpoint can be used to retrieve clicks and conversions data from your account.
Example Request
curl -i https://api.oktopost.com/v2/clickParameters
The following parameters can be used to filter data. We strongly recommend using filters to get the desired results.
| Param | Default | Description |
|---|---|---|
| _order | created | Options: created, campaignName and credentialName |
| _count | 25 | Options: 25, 50, 100 and 200 |
| _page | 0 | Current page |
| convertsOnly | 0 | Get only clicks that resulted in a conversion. See Conversion Tracking |
| messageId | - | See Messages API |
| leadId | - | See Leads API |
| campaignId | - | See Campaigns API |
| visitorId | - | Id assigned per unique visitor |
| before | - | Date time string. E.g. 2019-06-30T00:00:00 |
| after | - | Date time string. E.g. 2019-06-30T00:00:00 |
Example Result
{
"Result":true,
"Items":[
{
"Id":"009000000000000",
"Created":"2015-11-19 17:24:29",
"CampaignId":"002000000000000",
"MessageId":"005000000000000",
"PostId":"004000000000000",
"PostlogId":"007000000000000",
"LeadId":"",
"ConversionTagId":null,
"CredentialId":"003-001000000000000-xxxxxx-xxx",
"CampaignName":"2015-11 General Campaign",
"CredentialName":"John Doe's Twitter",
"Message":"Oktopost Rocks! http:\/\/www.oktopost.com\/",
"LinkUrl":"",
"LinkTitle":"",
"ImageUrl":"",
"Picture":0,
"RemoteUrl":"",
"ConvertedDate":"0000-00-00 00:00:00",
"Network":"Twitter",
"UserAgent":"Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_10_4) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/46.0.2490.71 Safari\/537.36",
"GeoCountry":"",
"GeoCity":"",
"GeoOrganization":"",
"GeoLongitude":0,
"GeoLatitude":0
}
],
"Total":91709
}CNAMEs
A CNAME is a type of entry within the Domain Name System (DNS) that specifies where someone can find your website. Oktopost uses custom CNAME records to track social clicks. A CNAME is set up as part of the integration setup. With this endpoint, it's possible to list, add, update or delete CNAME Records.
List CNAME Records
Example Request
curl -i https://api.oktopost.com/v2/cnameExample Result
{
"Result":true,
"Items":[
{
"Id":"0CN000000000000",
"Created":"2017-05-17 15:00:00",
"Modified":"2017-05-17 15:00:00",
"AccountId": "001000000000001",
"Name":"ok.oktopost.com"
}
],
"Total":1
}Add CNAME Record
Note that all CNAMES must resolve to okt.to.
Example Request
curl -i https://api.oktopost.com/v2/cname -X POST \
-d cname="ok.oktopost.com"Example Result
{
"Result":true,
"Cname": {
"Id":"0CN000000000000",
"Created":"2017-05-17 15:00:00",
"Modified":"2017-05-17 15:00:00",
"AccountId": "001000000000001",
"Name":"ok.oktopost.com"
}
}Update CNAME Record
Example Request
curl -i https://api.oktopost.com/v2/cname/0CN000000000000 -X POST \
-d cname="ok.oktopost.com"Example Result
{
"Result":true,
"Cname": {
"Id":"0CN000000000000",
"Name":"ok.oktopost.com"
}
}Delete CNAME Record
This endpoint will not delete the CNAME record from the DNS but only from Oktopost.
Example Request
curl -i https://api.oktopost.com/v2/cname/0CN000000000000 -X DELETEExample Result
{
"Result":true
}Conversions
A conversion is any action a user takes that has value for your business, from filling out a web form to downloading a white paper. This JavaScript endpoint allows you to send conversion events to Oktopost directly from the users' browser without using external tracking codes.
Endpoint
https://okt.to/c/{ACCOUNT_ID}/globalParameters
- tag (Required) The conversion type's name.
- value (Optional) The monetary value of the conversion.
- firstName (Optional)
- lastName (Optional)
- email (Optional)
- company (Optional)
- country (Optional)
- state (Optional)
- city (Optional)
Note that if you send a conversion event to Oktopost without personal information, it will create an anonymous conversion.
JavaScript Example
This example sends a named conversion event to Oktopost.
var myLead = {
tag: 'Example',
value: 100.00,
firstName: 'John',
lastName: 'Doe',
email: 'john@ibm.com',
company: 'IBM',
country: 'US',
state: 'NY',
city: 'New York',
zip: '123456',
ts: Date.now() // For cache busting
};
var baseURL = 'https://okt.to/c/{ACCOUNT_ID}/global'; // replace {ACCOUNT_ID} with your account ID.
var img = new Image;
img.src = baseURL + '?' + $.param(myLead); // Loads the conversion pixel with the lead data in the query parameters.Conversion Tags
A conversion tag is the user's definition of conversion. It is used to track someone who clicks on a shared link, then goes to your website and completes an action that's defined as a conversion. The following endpoint can be used to list conversion types set up in the account.
Example Request
curl -i https://api.oktopost.com/v2/conversion-tagExample Result
{
"Result": true,
"Items": [
{
"Id": "029000000000000",
"Tag": "Contact Us",
"Value": "0.00",
"Status": "active",
"Conversions": 0
}
],
"Total": 1
}Followers
This endpoint can be used to retrieve the number of followers or new followers every connected social profile or page has at any point in time.
Example Request
curl -i https://api.oktopost.com/v2/followers/003-001000000000001-xxx?fromDate=2019-01-01&toDate=2019-01-01Parameters
| Param | Default | Description |
|---|---|---|
| id | - | See Social Profiles API. |
| fromDate | -30 days | YYYY-MM-DD |
| toDate | now | YYYY-MM-DD |
Example Response
{
"Data":
[
{
"Followers": 651,
"FollowersAdded": 0,
"HistoryDate": "2019-01-01 00:00:00"
},
...
],
"Result": true
}Integrations
Oktopost's integrations provide a way to directly connect social engagement data with a CRM or marketing automation platform. The following endpoint allows to list, get and remove existing integrations.
List Connected Integrations
Parameters
| Param | Default | Description |
|---|---|---|
| _page | 0 | Current page |
| _count | 25 | Options: 25, 50 and 100 |
| type | - | Options: cd, ga, pardot, netresults, mautic and facebook |
Example Request
curl -i https://api.oktopost.com/v2/integration?type=facebookExample Result
{
"Result": true,
"Items": [
{
"Id": "014000000000001",
"Created": "2016-12-18 12:47:58",
"Modified": "2017-05-21 11:02:55",
"Status": "valid",
"State": "active",
"AccountId": "001000000000001",
"Type": "facebook",
"Version": 1,
"CnameId": null,
"SettingsData": { ... }
}
],
"Total": 1
}Get Integration
Example Request
curl -i https://api.oktopost.com/v2/integration/014000000000001?withAssets=1Input
- withAssets (Optional) The response will include the Assets associated with this integration
Example Result
{
"Result": true,
"Integration": {
"Id": "014000000000001",
"Created": "2016-12-18 12:47:58",
"Modified": "2017-05-21 11:02:55",
"Status": "valid",
"State": "active",
"AccountId": "001000000000001",
"Type": "facebook",
"Version": 1,
"CnameId": null,
"SettingsData": { ... },
"Assets": {
"Credentials":
[
{
"Id": "003-001000000000001-123456",
"Name": "John Smith's LinkedIn",
"DisplayName": "John Smith",
"Status": "valid",
"Network": "LinkedIn"
}
],
"Boards": [...]
}
}
}Connect Integration
This endpoint is available for partners only.
Input
- type The integration type.
- cnameId The CNAME used by this integration.
Example Request
Note that additional parameters may apply, according to the integration type.
curl -i https://api.oktopost.com/v2/integration -X POST \
-d cnameId="0CN000000000000"
-d type="cd"Update Integration
Input
- state (Optional) enabled or disabled
- cnameId (Optional)
Example Request
Note that additional parameters may apply, according to the integration type.
curl -i https://api.oktopost.com/v2/integration/014000000000001 -X POST \
-d state="disabled" Delete Integration
Example Request
curl -i https://api.oktopost.com/v2/integration/014000000000001 -X DELETELeads
Leads are individuals that interact with your social content. Oktopost collects and stores leads' publicly available information. This endpoint can be used to list, get and delete leads.
List Leads
Example Request
curl -i https://api.oktopost.com/v2/leadInput
| Param | Default | Description |
|---|---|---|
| search | - | Optional |
| _page | 0 | Optional |
| _count | 25 | Optional |
Example Result
{
"Result": true,
"Items": [
{
"Id": "0ld000000000001",
"ParentId": null,
"AccountId": "00100000000001",
"Type": "person",
"Email": "john@example.com",
"Name": "John Doe",
"FirstName": "John",
"LastName": "Doe",
"Photo": null,
"Phone": null,
"IsTracked": true
}
]
}Get Lead
Example Request
curl -i https://api.oktopost.com/v2/lead/0ld000000000001Example Result
{
"Result": true,
"Lead": {
"Id": "0ld000000000001",
"ParentId": null,
"AccountId": "00100000000001",
"Type": "person",
"Email": "john@example.com",
"Name": "John Doe",
"FirstName": "John",
"LastName": "Doe",
"Photo": null,
"Phone": null,
"IsTracked": true
}
}Delete Lead
Example Request
curl -i https://api.oktopost.com/v2/lead/0ld000000000001 -X DELETELead Activity
Lead activities are social interactions (reactions, shares, clicks, comments, mentions, etc.) that the platform was able to associate with a specific person. This endpoint can be used to list and delete lead activities.
List Lead Activities
Lead activities are social interactions that Oktopost was able to associate with a specific person. For a complete list of all the social activities see this article.
Example Request
curl -i https://api.oktopost.com/v2/lead-activityInput
- leadId (optional) Get all the activities for a particular lead.
Example Result
{
"Result": true,
"Items": [
{
"Id": "act000000000001",
"ActivityDate": "2020-01-10 08:30:00",
"AccountId": "001000000000001",
"LeadId": "0ld000000000001",
"Type": "click",
"Network": "Twitter",
"ProfileId": "003-001000000000001-123456",
"Data": {}
},
{
"Id": "act000000000001",
"ActivityDate": "2020-01-10 08:30:00",
"AccountId": "001000000000001",
"LeadId": "0ld000000000002",
"Type": "comment",
"Network": "LinkedIn",
"ProfileId": "003-001000000000001-123456",
"Data": {}
}
],
"Total": 1
}Delete Lead Activity
Example Request
curl -i https://api.oktopost.com/v2/lead-activity/act000000000001?leadId=0ld000000000001 -X DELETELinks
Links are hyperlinks to web pages that were shared in social media posts published via the platform. Every shared link is shortened by the okt.to link shortener. With this endpoint, it's possible to list, update or get links by hash.
Get Link by Hash
Returns public information about links.
Example Request
curl -i https://api.oktopost.com/v2/link/pEhsLiExample Result
The LongUrl represents the URL entered by the user while the FinalUrl represents the final destination of the redirect.
{
"Link": {
"Created": "2019-02-25 07:50:35",
"Hash": "pEhsLi",
"LongUrl": "https://www.oktopost.com",
"FinalUrl": "https://www.oktopost.com?utm_campaign=2019-02+General+Campaign&utm_content=Oktopost-twitter&utm_source=twitter&utm_medium=social",
"Params": {
"utm_campaign": "2019-02 General Campaign",
"utm_content": "Oktopost-twitter",
"utm_medium": "social",
"utm_source": "twitter"
},
"ShortUrl": "https://okt.to/pEhsLi"
},
"Result": true
}List Links
Example Request
curl -i https://api.oktopost.com/v2/linkInput
| Param | Description |
|---|---|
| hash | Optional |
| credentialIds | Optional. Comma separated credential Ids |
| ids | Optional. Comma separated link ids, max 100 |
Example Result
All items are sorted by creation date.
{
"Result":true,
"Items":[
{
"Id":"008000000000000",
"Created":"2015-10-20 00:24:02",
"Modified":"2015-11-03 18:20:35",
"AccountId":"001000000000000",
"CampaignId":"002000000000000",
"MessageId":"005000000000000",
"PostId":"004000000000000",
"PostlogId":"007000000000000",
"Hash":"2y8p21",
"LongUrl":"http:\/\/www.oktopost.com",
"ShortUrl":"http:\/\/okt.to\/2y8p21",
"Clicks":112,
"Converts":4,
"CredentialId":"003-001000000000000-12345678"
}
],
"Total":1
}Update Links
Example Request
curl -i https://api.oktopost.com/v2/link/008000000000000 -X POST \
-d longUrl="https://www.oktopost.com/blog"Example Result
{
"Result":true,
"Items":[
{
"Id":"008000000000000",
"Created":"2015-10-20 00:24:02",
"Modified":"2015-11-03 18:20:35",
"AccountId":"001000000000000",
"CampaignId":"002000000000000",
"MessageId":"005000000000000",
"PostId":"004000000000000",
"PostlogId":"007000000000000",
"Hash":"2y8p21",
"LongUrl":"http:\/\/www.oktopost.com\/blog",
"ShortUrl":"http:\/\/okt.to\/2y8p21",
"Clicks":112,
"Converts":4,
"CredentialId":"003-001000000000000-12345678"
}
],
"Total":1
}Me
With this endpoint, you can retrieve information about the token you're using to query the API.
Example Request
curl -i https://api.oktopost.com/v2/meExample Result
{
"Result": true,
"User": {
"Id": "00A000000000000",
"Name": "John Smith",
"Email": "john@example.com",
"LastLogin": "2020-10-27 08:27:30"
},
"Account": {
"Id": "001000000000001",
"Name": "Acme"
}
}Media
Media contain all images and videos that have been shared from the platform and currently stored in the Media Library. The following endpoint allows you to get, list, create and delete media assets.
Get Media
Get single media object by Id.
Example Request
curl -i https://api.oktopost.com/v2/media/026000000000000Example Result
{
"Result": true,
"Media": {
"Id":"026000000000000",
"Created":"2015-07-22 10:44:21",
"Modified":"2015-07-22 10:44:21",
"AccountId":"001000000000000",
"Status":"valid",
"CreatedBy":"00A000000000000",
"ModifiedBy":"00A000000000000",
"Type":"ImageUrl",
"Size":0,
"Resource":"http:\/\/ww1.prweb.com\/prfiles\/2013\/08\/30\/11077903\/India%20Water%20Pumps%20Market.JPG",
"Name":"http:\/\/ww1.prweb.com\/prfiles\/2013\/08\/30\/11077903\/India%20Water%2",
"Description":""
}
}List Media
List account media assets.
Example Request
curl -i https://api.oktopost.com/v2/mediaExample Result
{
"Result":true,
"Items":[
{
"Id": "026000000000000",
"AccountId": "001000000000000",
"Status": "valid",
"Created": "2019-09-22 14:58:12",
"Modified": "2019-09-22 14:58:12",
"CreatedBy": "00A000000000000",
"ModifiedBy": "00A000000000000",
"Type": "Image",
"Size": "147068",
"Resource": "https://s3.amazonaws.com/com-oktopost-app-message-pictures/e4cda957-c14d-4914-ae60-86a4043ae055/Londonteamoutofoffice.jpeg",
"Name": "London team out of office.jpeg",
"Description": "",
"MimeType": "image/jpeg",
"VideoId": null,
"VideoPreview": null
},
...
],
"Total":696
}Parameters
| Param | Description |
|---|---|
| q | The file name that you want to search for. |
| type | Image, Video or ImageUrl |
Create Media
Create a new media asset. Resource must consist of a valid image URL that can be publicly accessed. On success, this endpoint will return a similar response to the GET endpoint.
Example Request
curl -i https://api.oktopost.com/v2/media -X POST \
-d resource="https://www.oktopost.com/assets/img/oktopost-og.png"Delete Media
Delete asset from media library.
Example Request
curl -i https://api.oktopost.com/v2/media/026000000000000 -X DELETEUpload
The following endpoint can be used to read and create media upload requests.
Get Upload
Get a single upload by ID.
Example Request
curl -i https://api.oktopost.com/v2/upload/0up000000000001Example Result
{
"Result": true,
"Upload": {
"Id": "0up000000000001",
"Created": "2020-06-25 06:49:51",
"Modified": "2020-06-25 06:51:20",
"CreatedBy": "00A000000000001",
"Status": "complete",
"Name": "MyVideo.mp4",
"MimeType": "video/mp4",
"TotalSize": 17839845,
"Downloaded": 17839845,
"Source": "https://example_download...",
"LastError": null,
"Attempts": 0,
"MediaId": "026000000000001"
}
}List Upload
List account uploads.
Example Request
curl -i https://api.oktopost.com/v2/uploadExample Result
{
"Result":true,
"Items":[
{
"Id": "0up000000000001",
"Created": "2020-06-25 06:49:51",
"Modified": "2020-06-25 06:51:20",
"CreatedBy": "00A000000000001",
"Status": "complete",
"Name": "MyVideo.mp4",
"MimeType": "video/mp4",
"TotalSize": 17839845,
"Downloaded": 17839845,
"Source": "https://example_download...",
"LastError": null,
"Attempts": 0,
"MediaId": "026000000000001"
},
...
],
"Total":696
}Parameters
| Param | Default | Description |
|---|---|---|
| status | - | Status of the upload, one of pending, failed, complete. |
| source | - | Url-encoded upload source url |
| _page | 0 | The current page |
| _count | 20 | The number of results per page |
Create Upload
Example Request
curl -i https://api.oktopost.com/v2/upload -X POST \
-d source="https://example_download..." \
-d mimeType="video/mp4" \
-d name="MyFile.mp4"Input
| Fields | Description |
|---|---|
| source | A public URL to your file. It must support HEAD and GET requests with a Range header for chunked downloads. |
| name | Optional. The file name. |
| mimeType | Optional. The mime type of the uploaded file, the supported types include: video/mp4, image/gif, image/png, image/jpg and image/jpeg. |
The maximum allowed file size for uploads is 8 GiB, with a 32 GiB upload limit within a sliding 24-hour window.
Note that this endpoint only validates file size and mime type and does not check your file against the social network's specifications.
Example Result
{
"Result": true,
"Upload": {
"Id": "0up000000000001",
"Created": "2020-06-25 06:49:51",
"Modified": "2020-06-25 06:51:20",
"CreatedBy": "00A000000000001",
"Status": "complete",
"Name": "MyVideo.mp4",
"MimeType": "video/mp4",7
"TotalSize": 17839845,
"Downloaded": 17839845,
"Source": "https://example_download...",
"LastError": null,
"Attempts": 0,
"MediaId": "026000000000001"
}
}Note that if the mimeType or name fields are not sent and can not be determined from the source, the request will fail.
Chunked Uploads
If your file weighs more than 10 MiB, Oktopost will try to download it in chunks. If one of the chunked requests fails, the system will retry to download it up to 5 times before failing the entire request.
To check if your request has been processed, you can use the Get Upload endpoint above. While the upload is in progress, the Status field will be set to pending, and the MediaId will be set to null.
{
"Result": true,
"Upload": {
"Id": "0up000000000001",
"Created": "2020-06-25 06:49:51",
"Modified": "2020-06-25 06:51:20",
"CreatedBy": "00A000000000001",
"Status": "pending",
"Name": "MyVideo.mp4",
"MimeType": "video/mp4",
"TotalSize": 17839845,
"Downloaded": 10000000,
"Source": "https://example_download...",
"LastError": null,
"Attempts": 0,
"MediaId": null
}
}Once the upload is complete, the Status field will be set to complete, and you'll be able to use the MediaId to reference the Media endpoint.
{
"Result": true,
"Upload": {
"Id": "0up000000000001",
"Created": "2020-06-25 06:49:51",
"Modified": "2020-06-25 06:51:20",
"CreatedBy": "00A000000000001",
"Status": "complete",
"Name": "MyVideo.mp4",
"MimeType": "video/mp4",7
"TotalSize": 17839845,
"Downloaded": 17839845,
"Source": "https://example_download...",
"LastError": null,
"Attempts": 0,
"MediaId": "026000000000001"
}
}If the upload fails, the Status field will be set to failed and the LastError field will contain the error message.
{
"Result": true,
"Upload": {
"Id": "0up000000000001",
"Created": "2020-06-25 06:49:51",
"Modified": "2020-06-25 06:51:20",
"CreatedBy": "00A000000000001",
"Status": "failed",
"Name": "MyVideo.mp4",
"MimeType": "video/mp4",
"TotalSize": 17839845,
"Downloaded": 5000000,
"Source": "https://example_download...",
"LastError": "Could not download file, error 500",
"Attempts": 5,
"MediaId": null
}
}Validate Video Upload
Example Request
curl -i https://api.oktopost.com/v2/video-validate/026000000000000Example Result
{
"Result": true,
"Validations": {
"Facebook": {
"isValid": true,
"errors": []
},
"LinkedIn": {
"isValid": true,
"errors": []
},
"Twitter": {
"isValid": true,
"errors": []
},
"Instagram": {
"isValid": true,
"errors": []
},
"Youtube": {
"isValid": true,
"errors": []
}
}
}Messages
A message is the content of a post, which includes text and a link or image attachment. On the platform, each message can be published multiple times in separate posts. The following endpoint allows you to read, create, update and delete messages from the account.
Get Message
Get data for a single message by Id.
Parameters
| Param | Default | Description |
|---|---|---|
| withTags | 0 | Includes the message tags in the response. |
Example Request
curl -i https://api.oktopost.com/v2/message/005000000000000?withTags=1Example Result
{
"Result":true,
"Message":{
"Id":"005000000000000",
"Created":"2015-09-17 15:04:57",
"Modified":"2015-09-17 15:04:57",
"Status":"default",
"AccountId":"001000000000000",
"CreatedBy":"00A000000000000",
"ModifiedBy":"00A000000000000",
"CampaignId":"002000000000000",
"Network":"Twitter",
"Subject":"",
"Message":"Using Animated GIFs on Twitter http:\/\/www.oktopost.com\/blog\/using-animated-gifs-twitter\/",
"Md5":"4aeb3671d71f96f3b9bc3b056f41d6ab",
"ImageUrl":"",
"Description":"",
"LinkTitle":"",
"LinkUrl":"",
"Url":"",
"Clicks":1,
"ChildClicks":0,
"BoardClicks":0,
"Converts":1,
"ChildConverts":0,
"BoardConverts":0,
"ChildrenCount":0,
"Picture":"1",
"IsBoardMessage":0,
"Media":[
{
"Id":"026000000000000",
"Created":"2015-09-17 15:04:56",
"Modified":"2015-09-17 15:04:57",
"AccountId":"001000000000000",
"Status":"valid",
"CreatedBy":"00A000000000000",
"ModifiedBy":"00A000000000000",
"Type":"Image",
"Size":190625,
"Resource":"https:\/\/s3.amazonaws.com\/com-oktopost-app-message-pictures\/afbeb62d-64fe-4bcd-aea7-1fa1bf42e88a\/TwitGif_L.gif",
"Name":"TwitGif_L.gif",
"Description":""
}
],
"Tags":
[
"pr",
"smms"
]
}
}List Messages
List all messages in a single campaign.
Parameters
| Param | Default | Description |
|---|---|---|
| campaignId | - | Mandatory field if not provided ids. The Oktopost campaign Id. |
| withTags | 0 | Includes the message tags in the response. |
| network | - | Filters by the social network: Twitter, LinkedIn, Facebook, Instagram, YouTube, WeChat, or Xing. |
| ids | - | Mandatory field if not provided campaignId. Coma separated list of Oktopost message ids, max 100. |
Example Result
{
"Result":true,
"Items":[
{
"Id":"005000000000000",
"Created":"2015-09-17 15:04:57",
"Modified":"2015-09-17 15:04:57",
"Status":"default",
"AccountId":"001000000000000",
"CreatedBy":"00A000000000000",
"ModifiedBy":"00A000000000000",
"CampaignId":"002000000000000",
"Network":"Twitter",
"Subject":"",
"Message":"Using Animated GIFs on Twitter http:\/\/www.oktopost.com\/blog\/using-animated-gifs-twitter\/",
"Md5":"4aeb3671d71f96f3b9bc3b056f41d6ab",
"ImageUrl":"",
"Description":"",
"LinkTitle":"",
"LinkUrl":"",
"Url":"",
"Clicks":1,
"ChildClicks":0,
"BoardClicks":0,
"Converts":1,
"ChildConverts":0,
"BoardConverts":0,
"ChildrenCount":0,
"Picture":"1",
"IsBoardMessage":0
}
],
"Total":1
}Example Request
curl -i https://api.oktopost.com/v2/message?campaignId=002000000000000Create Message
Create a new message asset. Each message can have either a link attachment or a media assets attached. Media assets can be created using the Media endpoint.
Parameters
| Param | Description |
|---|---|
| network | The social network: Facebook, Twitter, LinkedIn, Youtube, or Instagram. |
| campaignId | The campaign Id for the message. |
| message | The messages' content. |
| linkUrl | Optional. See Link Attachment Fields below. |
| linkTitle | Optional. See Link Attachment Fields below. |
| description | Optional. See Link Attachment Fields below. |
| imageUrl | Optional. See Link Attachment Fields below. |
| tagIds | Optional. A list of comma separated tag Ids. If empty, the message will inherit tags from the campaign. |
| media | Optional. The media attachment Id. |
| title | Optional. The title for YouTube videos. |
Example Requests
Create a message with a link attachment.
curl -i https://api.oktopost.com/v2/message -X POST \
-d network=Facebook \
-d campaignId=002000000000000 \
-d linkUrl="https://www.oktopost.com" \
-d linkTitle="Social Media Management for B2B" \
-d description="Oktopost is a social media management software designed to publish social messages, converse with prospects and generate leads" \
-d imageUrl="https://www.oktopost.com/assets/img/oktopost-og.png" \
-d message="Oktopost Rocks" \
-d tagIds=0AF000000000001,0AF000000000002Create a message with a media attachment.
curl -i https://api.oktopost.com/v2/message -X POST \
-d network=Facebook \
-d campaignId=00250yY80DW7Fz3 \
-d message="Oktopost Rocks" \
-d media=026e5kltqedafpeCreate a message for YouTube.
curl -i https://api.oktopost.com/v2/message -X POST \
-d network=Youtube \
-d campaignId=00250yY80DW7Fz3 \
-d message="YouTube video description" \
-d media="026e5kltqedafpe" \
-d title="YouTube video title"Link Attachments
To create or update link attachments the following 4 fields are mandatory.
| Field | Description |
|---|---|
| LinkUrl | Link attachment Url |
| ImageUrl | Link attachment image Url |
| LinkTitle | Link attachment title |
| Description | Link attachment description |
Media Limits
The following limits are for the amount of Media assets that can be attached for a single message.
| Network | Limit |
|---|---|
| 4 | |
| 18 | |
| 10 | |
| 9 |
Update Message
Update a single message by Id.
Example Request
curl -i https://api.oktopost.com/v2/message/005000000000000 -X POST \
-d message="Hello World"
-d linkUrl="https://www.oktopost.com" \
-d linkTitle="Social Media Management for B2B" \
-d description="Oktopost is a social media management software designed to publish social messages, converse with prospects and generate leads" \
-d imageUrl="https://www.oktopost.com/assets/img/oktopost-og.png" \On success, both create and update actions will return a similar response to the GET endpoint.
Delete Message
Example Request
curl -i https://api.oktopost.com/v2/message/005000000000000 -X DELETEPosts
A social media post is a Message that was scheduled or sent on a specific date, to a specific social profile. The following endpoint allows you to list, create, update and delete posts from your account.
Please note that Update and Delete options are only available for posts that have not yet been sent.
Get Post
Example Request
curl -i https://api.oktopost.com/v2/post/004000000000000Example Result
{
"Result":true,
"Post":{
"Id":"004000000000000",
"Created":"2015-12-07 23:47:30",
"Modified":"2015-12-08 12:55:11",
"Status":"inqueue",
"AccountId":"001000000000000",
"CreatedBy":"00A000000000000",
"ModifiedBy":"00A000000000000",
"Source":"API",
"ContentSource":"User",
"Queued":1,
"CampaignId":"002000000000000",
"MessageId":"005000000000000",
"MessageChildId":"",
"MessageStatus":"default",
"Network":"Twitter",
"StartDateTime":"2015-12-08 00:00:00",
"Groups":"",
"GroupsCount":0,
"TotalCount":1,
"TargetGeo":"",
"UpdateStatus":1,
"Flag":"discussion",
"Clicks":0,
"Converts":0,
"Comments":0,
"NewComments":0,
"Likes":0,
"Utm":"",
"Credentials":"003-001000000000000-12345678"
}
}Get Post Stats
To get updated stats per social post, add stats=1 to the query parameters, like so:
curl -i https://api.oktopost.com/v2/post/004000000000000?stats=1This will result in:
{
"Result":true,
"Post":{
"Id":"004000000000000",
"Created":"2015-12-07 23:47:30",
"Modified":"2015-12-08 12:55:11",
"Status":"inqueue",
"AccountId":"001000000000000",
"CreatedBy":"00A000000000000",
"ModifiedBy":"00A000000000000",
"Source":"API",
"ContentSource":"User",
"Queued":1,
"CampaignId":"002000000000000",
"MessageId":"005000000000000",
"MessageChildId":"",
"MessageStatus":"default",
"Network":"Twitter",
"StartDateTime":"2015-12-08 00:00:00",
"Groups":"",
"GroupsCount":0,
"TotalCount":1,
"TargetGeo":"",
"UpdateStatus":1,
"Flag":"discussion",
"Clicks":0,
"Converts":0,
"Comments":0,
"NewComments":0,
"Likes":0,
"Utm":"",
"Credentials":"003-001000000000000-12345678"
},
"Stats": {
"LinkClicks": 0,
"Conversions": 0,
"Comments": 0,
"Likes": 0,
"Shares": 0,
"ImpressionsAdded": 69
}
}List Posts
Example Request
curl -i https://api.oktopost.com/v2/post?campaignId=002000000000000Parameters
The following parameters can be used to filter requests. We strongly recommend using filtering and ordering to get the desired results.
| Param | Default | Description |
|---|---|---|
| _page | 0 | The current page |
| _count | 25 | The number of results per page. Options: 25, 50, 100 |
| _order | created | Options: created, modified, startDateTime |
| messageId | - | See Message API |
| campaignId | - | See Campaign API |
| status | - | Post status, see post statuses below |
| createdBy | - | The Id of the Oktopost User who created the post |
| source | - | The channel the post created from, see sources below |
| before | - | Exclusive. End of range for the current _order field. E.g. 2017-07-01 00:00:00 |
| after | - | Inclusive. Start of range for the current _order field. E.g. 2017-07-01 00:00:00 |
Example Result
{
"Result":true,
"Items":[
{
"Id":"004000000000000",
"Created":"2015-12-07 23:47:30",
"Modified":"2015-12-08 12:55:11",
"Status":"inqueue",
"AccountId":"001000000000000",
"CreatedBy":"00A000000000000",
"ModifiedBy":"00A000000000000",
"Source":"API",
"ContentSource":"User",
"Queued":1,
"CampaignId":"002000000000000",
"MessageId":"005000000000000",
"MessageChildId":"",
"MessageStatus":"default",
"Network":"Twitter",
"StartDateTime":"2015-12-08 00:00:00",
"Groups":"",
"GroupsCount":0,
"TotalCount":1,
"TargetGeo":"",
"UpdateStatus":1,
"Flag":"discussion",
"Clicks":0,
"Converts":0,
"Comments":0,
"NewComments":0,
"Likes":0,
"Utm":"",
"Credentials":"003-001000000000000-12345678"
},
...
],
"Total":22509
}Create Post
Example Request
curl -i https://api.oktopost.com/v2/post -X POST \
-d messageId=005000000000000 \
-d credentialIds=003-001000000000000-12345678 \
-d startDateTime=1401908598Parameters
| Param | Default | Description |
|---|---|---|
| messageId | - | Required. The message Id |
| credentialIds | - | Required. Comma separated values of social profile Ids |
| startDateTime | +1 minute | Unix timestamp. Scheduled time for the post to go out |
| status | pending | Options: pending, inqueue, draft, inqueue-draft |
Update Post
All parameters available on post creation can be updated as-well.
Example Request
curl -i https://api.oktopost.com/v1/post/004000000000000 -X POST \
-d startDateTime=1435767841 \
-d messageId=005000000000000On success, both create and update actions will return a similar response to the GET endpoint.
Delete Post
Example Request
curl -i https://api.oktopost.com/v1/post/004000000000000 -X DELETEExample Response
{
"Result":true
}Properties
Sources
Post sources represent the channel used to create each post. Sources are used in Oktopost to analyze performance by channel.
| Source | Description |
|---|---|
| UI | Posts created using the Oktopost application |
| API | Posts created using the API |
| Autoposter | Posts created using the Autoposter |
| Bookmarklet | Posts created using the bookmarklet or browser extension |
| Board | Posts created using the Social Advocacy Board |
| Embedded | Posts created from the embedded API |
Statuses
The following statuses represent the different states of each post. They can be used for filtering results or for creating and updating posts.
| Status | Description |
|---|---|
| pending | Scheduled post |
| inqueue | Queued post |
| inqueue-draft | Draft post in queue |
| draft | Draft post |
| complete | Sent post |
| incomplete | Sent with errors |
| error | Has errors |
Post Analytics
Post analytics provides data on the reach, impressions, engagements and conversions generated by a specific social media post. The following endpoint allows retrieving the most updated Post's and Social Post's analytics by Ids.
Example Request
https://api.oktopost.com/v2/analytics/004000000000001Example Result
{
"Result": true,
"Stats": {
"LinkClicks": 6,
"Conversions": 1,
"Comments": 0,
"Likes": 2,
"Shares": 1,
"ImpressionsAdded": 69
}
}Note that in case a metric is not available for the social network or profile the stat value will return -1 instead of 0.
Social Authorization
Social authorization is a process of connecting personal social profiles, company pages and groups to the platform in order to publish and manage their content. The following endpoint allows you to provide an authorization process to your clients from outside the platform.
How it Works
Getting The Redirect URL
Example Request
curl -i https://api.oktopost.com/v2/social-authorizationInput
| Field | Description |
|---|---|
| network | The social network you want to connect: Twitter, Facebook, Youtube, LinkedIn or Instagram |
| url | The URL to redirect the user back to after authentication |
| type | Type of entity to you want to add: group, profile (default) or page |
Verifying The Result
Once a user has completed the social authentication process, they will be redirected to the URL stated in the first request. The URL will be appended with a single query parameter called okt which you will need to use in the following request in order to verify the result of the authentication process.
Note that this endpoint will produce different responses according to the entity type stated in the first request.
Example Request
curl -i https://api.oktopost.com/v2/social-authorization/591c6053d81978.11578446867279657339b29ad2799b11ca4ff883Example Result
Single profile
This result means that the profile is connected to Oktopost and is ready for use.
{
"Result": true,
"Credential": {
"Id": "003-001000000000000-10795428XXXXXXXXX",
"Created": "2000-12-31 23:59:59",
"Name": "John Doe's Twitter",
"Status": "valid",
"Network": "Twitter",
"ImageLink": "",
"NetworkUsername": "johndoe"
}
}Groups and pages
This result will list all the available groups or pages that the user can add to Oktopost. Note that a user may manage pages that he does not wish Oktopost to have access to. It is your responsibility to present the user with a choice of pages to select from.
{
"Result": true,
"token": "591c6053d81978.11578446867279657339b29ad2799b11ca4ff883",
"data": [
{
"Id": "10795428XXXXXXXXX",
"Name": "Acme Inc",
"Network": "Facebook",
"ImageLink": "",
"NetworkUsername": "123456",
"IsConnected": true
}
]
}Adding Groups and Pages
Once the user has selected the groups or pages they want to add, you will need to submit the list of comma separated Ids, based on the Id field from the previous response, back to Oktopost along with the token provided to you with the previous response.
Example Request
curl -i https://api.oktopost.com/v2/social-authorization/591c6053d81978.1157844686727965733a45fd2799b1?ids=123456,2343257 -X PUTSocial Posts
Social Posts are Posts that have already been sent to social media channels from the platform. The following endpoint can be used to get and list social posts as well as their most updated stats.
List by Post Id
Example Request
curl -i https://api.oktopost.com/v2/postlog?postId=004000000000001Example Result
{
"Result": true,
"Postlogs": [
{
"Id": "007000000000001",
"PostId": "004000000000001",
"CampaignId": "002000000000001",
"MessageId": "005000000000001",
"CredentialId": "003-001000000000001-12345678",
"LinkId": "008000000000001", // deprecated
"LinkIds": [...],
"Created": "2017-05-02 10:29:04",
"Modified": "2017-05-07 02:58:18",
"Status": "success",
"Network": "Twitter",
"RemoteId": "xxxx",
"RemoteUrl": "http://twitter.com/Oktopost/status/xxxx",
"Error": ""
}
]
}Get Single Social Post
Example Request
curl -i https://api.oktopost.com/v2/postlog/007000000000001Example Result
{
"Result": true,
"Postlog": {
"Id": "007000000000001",
"PostId": "004000000000001",
"CampaignId": "002000000000001",
"MessageId": "005000000000001",
"CredentialId": "003-001000000000001-12345678",
"LinkId": "008000000000001", // deprecated
"LinkIds": [...],
"Created": "2017-05-02 10:29:04",
"Modified": "2017-05-07 02:58:18",
"Status": "success",
"Network": "Twitter",
"RemoteId": "xxxx",
"RemoteUrl": "http://twitter.com/Oktopost/status/xxxx",
"Error": ""
}
}Get Social Post Stats
To get updated stats per social post, add stats=1 to the query parameters, like so:
curl -i https://api.oktopost.com/v2/postlog/007000000000001?stats=1This will result in:
{
"Result": true,
"Postlog": {
"Id": "007000000000001",
"PostId": "004000000000001",
"CampaignId": "002000000000001",
"MessageId": "005000000000001",
"CredentialId": "003-001000000000001-12345678",
"LinkId": "008000000000001", // deprecated
"LinkIds": [...],
"Created": "2017-05-02 10:29:04",
"Modified": "2017-05-07 02:58:18",
"Status": "success",
"Network": "Twitter",
"RemoteId": "xxxx",
"RemoteUrl": "http://twitter.com/Oktopost/status/xxxx",
"Error": ""
},
"Stats": {
"LinkClicks": 4,
"Conversions": 1,
"Comments": 1,
"Likes": 1,
"Shares": 0,
"ImpressionsAdded": 69,
"MediaClicksAdded": 0,
"DetailExpandsAdded": 0,
"UserFollowsAdded": 0
}
}Social Profiles
Social profiles are personal profiles, company pages, and groups that were connected to Oktopost. The following endpoint can be used to get, list and remove social profiles from the platform.
Get Social Profile
Get a single social profile by Id.
Example Request
curl -i https://api.oktopost.com/v2/credential/003-001000000000000-10795428XXXXXXXXXExample Result
{
"Result":true,
"Credential":{
"Id":"003-001000000000000-10795428XXXXXXXXX",
"Created":"2015-10-26 21:02:30",
"Name":"Oktopost's Twitter",
"DisplayName":"Oktopost",
"Status":"valid",
"Network":"Twitter",
"ImageLink":"valid",
"NetworkUsername":"oktopost",
"NativePostsEnabled":0
}
}List Social Profiles
Example Request
curl -i https://api.oktopost.com/v2/credential?network=Twitter?includeInvalid=0Parameters
Results can be filtered by network. Acceptable values are: LinkedIn, Twitter, Youtube, Instagram and Facebook.
| Param | Default | Description |
|---|---|---|
| network | - | Optional. Acceptable values are: LinkedIn, Twitter, Youtube, Instagram and Facebook. |
| includeInvalid | 0 | Optional. If set to 1, the response will include invalid credentials. |
Example Result
{
"Result":true,
"Items":[{
"Id":"003-001000000000000-10795428XXXXXXXXX",
"Created":"2015-10-26 21:02:30",
"Name":"Oktopost's Twitter",
"DisplayName":"Oktopost",
"Status":"valid",
"Network":"Twitter",
"ImageLink":"valid",
"NetworkUsername":"oktopost",
"NativePostsEnabled":0
},
...
],
"Total":21
}Update a Social Profile
Update a single social profile by Id.
Example Request
curl -i https://api.oktopost.com/v2/credential/003-001000000000000-10795428XXXXXXXXX -X PUT \
-d displayName="Oktopost Twitter" \
-d nativePostsEnabled=1Example Response
{
"Result": true,
"Credential": {...}
}Delete a Social Profile
Note that deleting a profile will delete all scheduled posts using it.
Example Request
curl -i https://api.oktopost.com/v2/credential/003-001000000000000-10795428XXXXXXXXX -X DELETEStreams
Streams are live feeds that display and engage with the content from connected social profiles. With this endpoint you can view, add, edit and remove streams from a users' account.
List Streams
Order by position or created
Example Request
curl -i https://api.oktopost.com/v2/stream \
-d position=420Example Response
{
"Result": true,
"Items":
[
{
"Id": "00F00000000000",
"Created": "2020-11-19 08:22:01",
"Name": "#b2b",
"Network": "Twitter",
"Type": "tw.keyword",
"StreamTabId": "01800000000000",
"CredentialId": "003-001000000000000-10795428XXXXXXXXX",
"Position": 2
},
{
"Id": "00F00000000001",
"Created": "2020-11-09 18:00:01",
"Name": "#btc",
"Network": "Twitter",
"Type": "tw.keyword",
"StreamTabId": "01800000000000",
"CredentialId": "003-001000000000000-10795428XXXXXXXXX",
"Position": 3
}
]
}Add Stream
Parameters
| Param | Description |
|---|---|
| network | Facebook, Twitter, LinkedIn, or Instagram. |
| credentialId | The social profile Id. |
| type | The stream type, see acceptable values below. |
| keyword | The search term. |
Twitter Streams
| Type | Description |
|---|---|
| mention | Metions of a connected Twitter handle. |
| retweet | Tweets that users retweeted. |
| feed | Tweets by a connected Twitter handle. |
| keyword | A feed that searches Twitter for keywords. |
| list | A feed with all the tweets by handles on a Twitter List. |
| favorite | Tweets that users liked. |
| home | The home feed of a connected Twitter handle. |
| user | A feed with tweets by any Twitter handle. |
Instagram Streams
| Type | Description |
|---|---|
| page | Posts from a connected Instagram page. |
| page.tags | Posts containing a specific hashtag. |
Facebook Streams
| Type | Description |
|---|---|
| ownpage | Posts from a connected Facebook page. |
| tag | Posts that mention a connected Facebook page. |
LinkedIn Streams
| Type | Description |
|---|---|
| page | Posts from a connected LinkedIn page. |
Example Request
Create a stream with mentions of a connected Twitter handle.
curl -i https://api.oktopost.com/v2/stream -X POST \
-d streamTabId=01800000000000 \
-d network=Twitter \
-d credentialId=003-001000000000000-10795428XXXXXXXXX \
-d type=mention \
-d position=-2Create a stream that searches Twitter for specific terms or keywords. See search options.
curl -i https://api.oktopost.com/v2/stream -X POST \
-d streamTabId=01800000000000 \
-d network=Twitter \
-d credentialId=003-001000000000000-10795428XXXXXXXXX \
-d type=keyword \
-d keyword="#haiku" \
-d position=2Example Result
{
"Result": true,
"Stream":
{
"Id": "00F00000000000",
"Created": "2020-11-19 08:22:01",
"Name": "last",
"Network": "Twitter",
"Type": "tw.keyword",
"StreamTabId": "01800000000000",
"CredentialId": "003-001000000000000-10795428XXXXXXXXX",
"Position": 2
}
}Remove Stream
curl -i https://api.oktopost.com/v2/stream/00F000000000001 -X DELETEExample Result
{
"Result": true
}Update Stream Position
curl -i https://api.oktopost.com/v2/stream/01800000000000 -X POST \
-d position=420Example Result
{
"Result": true,
"Stream":
{
"Id": "00F00000000000",
"Created": "2020-11-19 08:22:01",
"Name": "last",
"Network": "Twitter",
"Type": "tw.keyword",
"StreamTabId": "01800000000000",
"CredentialId": "003-001000000000000-10795428XXXXXXXXX",
"Position": 2
}
}Stream Tabs
Streams are organized using tabs. With this endpoint you can list, create, delete and update stream tabs.
List Stream Tabs
Example Request
curl -i https://api.oktopost.com/v2/stream-tabExample Result
{
"Result": true,
"Items": [
{
"Id": "018000000000000",
"Name": "Twitter Stream",
"Status": "active",
"Created": "2020-11-18 15:00:06"
}
],
"Total": 1
}Get Stream Tab
Example Request
curl -i https://api.oktopost.com/v2/stream-tab/018000000000000Example Result
{
"Result": true,
"StreamTab": {
"Id": "018000000000000",
"Name": "Twitter Stream",
"Status": "active",
"Created": "2020-11-18 15:00:06"
}
}Add Stream Tab
Example Request
curl -i https://api.oktopost.com/v2/stream-tab -X POST \
-d name="Twitter Engagement"Example Result
{
"Result": true,
"StreamTab": {
"Id": "018000000000000",
"Name": "Twitter Engagement",
"Status": "active",
"Created": "2020-11-15 13:23:34"
}
}Edit Stream Tab
Example Request
curl -i https://api.oktopost.com/v2/stream-tab/018000000000000 -X POST \
-d name="Twitter Disengagement"Example Result
{
"Result": true,
"StreamTab": {
"Id": "018000000000000",
"Name": "Twitter Disengagement",
"Status": "active",
"Created": "2020-11-15 13:23:34"
}
}Remove Stream Tab
Example Request
curl -i https://api.oktopost.com/v2/stream-tab/018000000000000 -X DELETEStories
Stories are articles or media assets that you share with advocates on the board. Each story can have multiple messages for different networks with the same media asset available to share.
Get Story
Get the data for a single story.
Example Request
curl -i https://api.oktopost.com/v2/story/0AS00000000000xExample Result
{
"Result": true,
"Item":
{
"ID": "0AS00000000000x",
"Created": "2022-12-13 17:22:52",
"Modified": "2022-12-13 17:47:44",
"AccountId": "0017ym7zlYsOsO7",
"CreatedBy": "00A00000000000x",
"ModifiedBy": "00A00000000000x",
"BoardId": "brd00000000000x",
"CampaignId": "002rfqmpadczzge",
"PublishDate": "2022-12-19 14:00:00",
"ExpirationDate": "2023-06-14 02:59:59",
"IsFeatured": false,
"Title": "🎅🏼 Christmas Rhymes about Oktopost",
"Description": "A few Christmas rhymes to share around the holiday season :)",
"ImageUrl": null,
"LinkTitle": null,
"LinkUrl": null,
"LinkDescription": null,
"LinkContent": null,
"Type": "text",
"Status": "draft",
"ShareCount": 0,
"AltTexts": null,
"VideoTitle": null,
"VideoPreview": null,
"VideoSubtitle": null,
"PreviewFrame": null,
"WorkflowId": null,
"Messages":
[
{
"Id": "00500000000000x",
"Network": "LinkedIn",
"Message": "'Twas the night before Christmas, and all through the land 🎅\nB2B marketers were bustling, with campaigns in hand\nThey used @Oktopost, the social media platform of choice\nTo share their content and give their brand a voice\n\nWith features like scheduling and analytics galore 🗓\nOktopost made it easy to connect and explore\nTheir platform helped marketers reach their goals\nAnd spread holiday cheer to B2B folk and trolls 🎄\n\nSo as we sit by the fire and sip our cocoa ☕\nWe thank Oktopost for making our work easier to show\nMerry Christmas to all, and to all a good night\nFrom Oktopost, the best B2B social media platform in sight! 🤗",
"Type": "text",
"Mentions":
[
{
"Id": "urn:li:organization:123456",
"Text": "Oktopost"
}
],
"LinkTitle": "",
"LinkUrl": "",
"Description": "",
"ImageUrl": "",
"VideoPreview": "",
"VideoTitle": "",
"VideoSubtitle": "",
"Media": []
}
],
"Media":[],
"Topics":
[
"Oktopost Content"
],
"Tags":
[
"Thought Leadership",
"Christmas"
]
}
}
Get Stories
List stories in a board.
Example Request
curl -i https://api.oktopost.com/v2/story?boardId=brd00000000000xExample Result
{
"Result": true,
"Total": 83,
"Items":
[
{
"ID": "0AS00000000000x",
"Created": "2022-12-13 17:22:52",
"Modified": "2022-12-13 17:47:44",
"AccountId": "0017ym7zlYsOsO7",
"CreatedBy": "00A00000000000x",
"ModifiedBy": "00A00000000000x",
"BoardId": "brd00000000000x",
"CampaignId": "00200000000000x",
"PublishDate": "2022-12-19 14:00:00",
"ExpirationDate": "2023-06-14 02:59:59",
"IsFeatured": false,
"Title": "🎅🏼 Christmas Rhymes about Oktopost",
"Description": "A few Christmas rhymes to share around the holiday season :)",
"ImageUrl": null,
"LinkTitle": null,
"LinkUrl": null,
"LinkDescription": null,
"LinkContent": null,
"Type": "text",
"Status": "draft",
"ShareCount": 0,
"AltTexts": null,
"VideoTitle": null,
"VideoPreview": null,
"VideoSubtitle": null,
"PreviewFrame": null,
"WorkflowId": null,
"Messages":
[
{
"Id": "00500000000000x",
"Network": "LinkedIn",
"Message": "'Twas the night before Christmas, and all through the land 🎅\nB2B marketers were bustling, with campaigns in hand\nThey used @Oktopost, the social media platform of choice\nTo share their content and give their brand a voice\n\nWith features like scheduling and analytics galore 🗓\nOktopost made it easy to connect and explore\nTheir platform helped marketers reach their goals\nAnd spread holiday cheer to B2B folk and trolls 🎄\n\nSo as we sit by the fire and sip our cocoa ☕\nWe thank Oktopost for making our work easier to show\nMerry Christmas to all, and to all a good night\nFrom Oktopost, the best B2B social media platform in sight! 🤗",
"Type": "text",
"Mentions":
[
{
"Id": "urn:li:organization:123456",
"Text": "Oktopost"
}
],
"LinkTitle": "",
"LinkUrl": "",
"Description": "",
"ImageUrl": "",
"VideoPreview": "",
"VideoTitle": "",
"VideoSubtitle": "",
"Media": []
}
],
"Media":[],
"Topics":
[
"Oktopost Content"
],
"Tags":
[
"Thought Leadership",
"Christmas"
]
},
...
]
}Add Story
Create a new Story in the board.
Parameters
| Prop | Description | Required | Default |
|---|---|---|---|
| boardId | The Board Id | - | The oldest active board. |
| title | The story title | √ | - |
| description | The story description | √ | - |
| campaignId | The Campaign Id | √ | - |
| mediaIds | Comma separated Media | - | - |
| link | The link associated with the story | - | - |
| messageIds | Comma separated Message Ids | - | - |
| topicIds | The topic ids related to this story | - | - |
| tagIds | The Tag ids related to this story | - | - |
| publishDatetime | Unix timestamp | - | Now |
| expirationDatetime | Unix timestamp | - | Based on the board’s default expiration date. |
| isDraft | Save the story as Draft | - | False |
| isFeatured | Mark the story as Featured | - | False |
| workflowId | Send the story to approval | - | - |
Example Request
curl -i https://api.oktopost.com/v2/story -X POST \
-d boardId="brd00000000000x" \
-d title="🎅🏼 Christmas Rhymes about Oktopost" \
-d description="A few Christmas rhymes to share around the holiday season :)" \
-d campaignId="00200000000000x" \
-d mediaIds="02600000000000x" \
-d link="https://www.oktopost.com" \
-d messageIds="005000000000001,005000000000002" \
-d topicIds="tpc000000000001,tpc000000000002" \
-d tagIds="0AF000000000001,0AF000000000002" \Edit Story
Example Request
curl -i https://api.oktopost.com/v2/story/0AS00000000000x -X POST \
-d boardId="brd00000000000x" \
-d title="🎅🏼 Christmas Rhymes about Oktopost" \
-d description="A few Christmas rhymes to share around the holiday season :)" \
-d campaignId="00200000000000x" \
-d mediaIds="02600000000000x" \
-d link="https://www.oktopost.com" \
-d messageIds="005000000000002" \
-d topicIds="tpc000000000002" \
-d tagIds="0AF000000000002" \Delete Story
Example Request
curl -i https://api.oktopost.com/v2/story/0AS00000000000x -X DELETETags
In Oktopost, you can assign tags to campaigns and messages that you can later analyze in Social BI. With this endpoint you can list, create, update and delete tags.
List Tags
Input
- _order (Optional) Accepted values: tag, created, lastUsed
- _page (Optional)
- _count (Optional)
Example Request
curl -i https://api.oktopost.com/v2/tagExample Result
{
"Result": true,
"Items": [
{
"Id": "0AF000000000001",
"Created": "2020-11-03 08:35:30",
"Tag": "Hello",
"LastUsedDate": "2020-11-03 08:48:34"
},
{
"Id": "0AF000000000002",
"Created": "2020-11-03 08:35:30",
"Tag": "World",
"LastUsedDate": "2020-11-03 08:52:31"
}
],
"Total": 2
}Get Tag
Example Request
curl -i https://api.oktopost.com/v2/tag/0AF000000000001Example Result
{
"Result": true,
"Tag":{
"Id": "0AF000000000001",
"Created": "2020-11-03 08:35:30",
"Tag": "Hello",
"LastUsedDate": "2020-11-03 08:48:34"
}
}Add Tag
Example Request
curl -i https://api.oktopost.com/v2/tag -X POST \
-d tag="Tag Name"Example Result
{
"Result": true,
"Tag":{
"Id": "0AF000000000001",
"Created": "2020-11-03 08:35:30",
"Tag": "Tag Name",
"LastUsedDate": "2020-11-03 08:48:34"
}
}Update Tag
Example Request
curl -i https://api.oktopost.com/v2/tag/0AF000000000001 -X POST \
-d tag="My Tag"Example Result
{
"Result": true,
"Tag":{
"Id": "0AF000000000001",
"Created": "2020-11-03 08:35:30",
"Tag": "Tag Name",
"LastUsedDate": "2020-11-03 08:48:34"
}
}Delete Tag
Example Request
curl -i https://api.oktopost.com/v2/tag/0AF000000000001 -X DELETETeams
The following endpoint can be used to read, create, update and delete teams.
Get Team
Get a single team by Id.
Example Request
curl -i https://api.oktopost.com/v2/team/025000000000000Example Result
{
"Result": true,
"Team":{
"Id":"025000000000000",
"Created":"2019-09-24 22:11:36",
"Modified":"2019-09-24 22:11:40",
"Name":"US East"
}
}List Teams
Example Request
curl -i https://api.oktopost.com/v2/teamExample Result
{
"Result":true,
"Items":[
{
"Id":"025000000000000",
"Created":"2019-09-24 22:11:36",
"Modified":"2019-09-24 22:11:40",
"Name":"US East"
},
...
],
"Total":193
}Create Team
Example Request
curl -i https://api.oktopost.com/v2/team -X POST \
-d name="US West" Example Result
{
"Result":true,
"Team":{
"Id":"025000000000000",
"Created":"2020-04-24 12:11:36",
"Modified":"2020-04-24 12:11:40",
"Name":"US West"
}
}Update Team
Example Request
curl -i https://api.oktopost.com/v2/team/025000000000000 -X POST \
-d name="US South" Example Result
{
"Result":true,
"Team":{
"Id":"025000000000000",
"Created":"2020-04-24 12:11:36",
"Modified":"2020-04-24 12:12:59",
"Name":"US South"
}
}Delete Team
Example Request
curl -i https://api.oktopost.com/v2/team/025000000000000 -X DELETEExample Result
{
"Result":true
}Team Entities
The following endpoint can be used to add and remove entities from teams. Currently team bound entities are: Campaign, User, Advocacy Board and Workflows.
List Teams
Get all teams for a single team-bound entity. This endpoint is limited to 1000 elements and no pagination is available.
Example Request
curl -i https://api.oktopost.com/v2/team/025000000000000Example Result
{
"Result": true,
"Items": [
{
"Id":"025000000000000",
"Created":"2019-09-24 22:11:36",
"Modified":"2019-09-24 22:11:40",
"Name":"US East"
},
...
]
}Add Teams to an Entity
Example Request
curl -i https://api.oktopost.com/v2/team-entity/002000000000000 -X POST \
-d teamIds=025000000000000,025000000000001Example Result
{
"Result":true
}Remove Teams from an Entity
Example Request
curl -i https://api.oktopost.com/v2/team/025000000000000 -X DELETE \
-d teamIds=025000000000000,025000000000001 Example Result
{
"Result":true
}Token Login
Token Login is the type of web authentication that provides users with a uniquely-generated encrypted token that is used to log in to the platform without entering a username and password. The following endpoint allows you to provide a Single Sign-on option for users by generating a one-time access token.
How it Works
Obtaining the Login Token
To obtain the token, you must make an authenticated request to the endpoint below and include your application's privateKey.
Example Request
curl -i https://api.oktopost.com/v2/auth-token?privateKey=[KEY]Example Result
{
"Result":true,
"Token":"574dac5e6bcb31.23085498b3fc1c5d3398cca07bb31e5729d3a32f"
}Note that the privateKey is available only for authorized applications. If you wish to use this endpoint, please contact us.
Final Redirect
Once the token has been obtained, the user has to be redirected to the following URL:
Example Redirect
https://app.oktopost.com/auth/token/id/[TOKEN]By default, the user will be redirected to the Oktopost dashboard. If you wish to redirect the user to any other page within the platform you can add a _redirect parameter to the URL with the desired path, as such:
Example Redirect With Followup URL
https://app.oktopost.com/auth/token/id/[TOKEN]?_redirect=/calendarUsers
Users are individuals who have login access to the social media management platform or social advocacy board. The following endpoint allows to get, list, create, update and delete users.
Get User
Example Request
curl -i https://api.oktopost.com/v2/user/00A000000000000Example Result
{
"Result":true,
"User":{
"Id":"00A000000000000",
"Created":"2014-12-21 10:27:25",
"Modified":"2015-08-04 09:37:49",
"Status":"active",
"Name":"Oktopost",
"FirstName":"Okto",
"LastName":"Post",
"Email":"info@oktopost.com",
"LastLogin":"2015-07-23 09:13:17",
"LastBoardLogin":"2015-07-29 14:48:18",
"HasBrowserExtension":1,
"LinkedInId":"",
"LinkedInName":"",
"LinkedInImageUrl":"",
"TwitterId":"",
"TwitterName":"",
"TwitterImageUrl":"",
"FacebookId":"",
"FacebookName":"",
"FacebookImageUrl":"",
"Timezone":"America/New_York"
}
}List Users
Example Request
curl -i https://api.oktopost.com/v2/userExample Result
{
"Result":true,
"Items":[
{
"Id":"00A000000000000",
"Name":"Oktopost",
"Email":"info@oktopost.com",
"LastLogin":"2015-07-23 09:13:17",
"Role":"admin",
"Timezone":"America/New_York"
},
...
],
"Total":10
}Create User
Example Request
curl -i https://api.oktopost.com/v2/user -X POST \
-d firstName="Okto"
-d lastName="Post"
-d email="info@oktopost.com"
-d password="123456"
-d role="admin"
-d timezone="America/New_York"Roles
The following roles can be applied when creating a new user.
| Role | Description |
|---|---|
| admin | Can manage all functions |
| publisher | Can manage all functions besides account administration |
| contributor | Has the same privileges as publisher besides approving posts |
| read | Read only |
Update User
Example Request
curl -i https://api.oktopost.com/v2/user/00A000000000000 -X POST \
-d firstName="Oktopost"
-d lastName="Rocks"
-d email="info@oktopost.com"
-d password="123456"
-d timezone="America/New_York"Both create and update actions will return a similar response to the GET endpoint.
Delete User
Example Request
curl -i https://api.oktopost.com/v2/user/00A000000000000 -X DELETEUser Notifications
Oktopost sends out email alerts when certain events happen in a user account according to each user's notification settings. This endpoint will list and update the authenticated user's email notification settings.
List Notifications
This endpoint will list the authenticated user's email notification settings.
Example Request
curl -i https://api.oktopost.com/v2/notificationExample Result
{
"Result": true,
"Items": {
"EmailDaily": false,
"EmailWeekly": true,
"EmailCampaignComplete": false,
"EmailOnNewAssignment": true,
"EmailOnNoteAdded": true,
"EmailOnNoteMention": true,
"EmailOnStatusChange": true,
"SendDailyEmailReport": true
}
}Update Notifications
Example Request
curl -i https://api.oktopost.com/v2/notification -X POST \
-d EmailDaily=1 \
-d EmailWeekly=1 \
-d EmailCampaignComplete=1 \
-d EmailOnNewAssignment=0 \
-d EmailOnNoteAdded=0 \
-d EmailOnNoteMention=1 \
-d EmailOnStatusChange=0 \
-d SendDailyEmailReport=1Note that it is possible to send one or more settings in a single update request.
Webhooks
Webhooks allows to set up integrations that subscribe to events happening in the account. With this endpoint, it's possible to list, get, add, update or delete webhooks.
List Webhooks
Parameters
| Param | Default | Description |
|---|---|---|
| _order | name | Options are: name, description, lastExecutionDate, isEnabled, created, modified |
| _page | 0 | Current page |
| _count | 20 | Options: 20, 25, 50 and 100 |
| event | - | See Supported Event Types below |
| name | - | Search by name |
Supported Event Types
The following event types can be used to list, create and update webhooks.
| Param | Description |
|---|---|
| newAdvocacyMessage | Triggers when a new message is added to the board |
| newAdvocacyStory | Triggers when a new story is added to the board |
| newAdvocacyTopic | Triggers when a new topic is added to the board |
| newConversion | Triggers when a social conversion is captured |
| postSent | Triggers when a post is sent to social media |
| newNoteOnConversation | Triggers when a new note is added to a conversation |
| newConversation | Triggers when a new conversation is available in your inbox |
| conversationUpdated | Triggers when a new comment or reply are available on existing conversation |
| newAssignment | Triggers when a conversation is assigned to a new user |
| conversationStatusUpdated | Triggers when a conversation status is updated |
| newLead | Triggers when a new lead is captured |
| newLeadActivity | Triggers when a new social activity is detected |
| newCampaign | Triggers when a new campaign is created |
| postCreated | Triggers when a user creates a new post |
| postModified | Triggers when a user updates a scheduled post |
| postDeleted | Triggers when a user deletes a scheduled post |
| newApprovalItem | Triggers when a posts and messages are sent to approval |
| approvalItemApproved | Triggers when a posts and messages are approved |
| approvalItemRejected | Triggers when a posts and messages are rejected |
Example Request
curl -i https://api.oktopost.com/v2/webhookExample Result
{
"Result": true,
"Items": [
{
"Id": "0WA000000000001",
"Name": "My Webhook",
"Description": "Send new assignment to Slack",
"Event": "newAssignment",
"Url": "https://slack.com/",
"LastExecutionDate": "-",
"IsEnabled": 1,
"Created": "2017-05-23 14:07:18",
"Modified": "2017-05-23 14:07:18"
}
],
"Total": 1
}Get Webhook
Example Request
curl -i https://api.oktopost.com/v2/webhook/0WA000000000001Example Result
{
"Result": true,
"Webhook": {
"Id": "0WA000000000001",
"Name": "My Webhook",
"Description": "Send new assignment to Slack",
"Event": "newAssignment",
"Url": "https://slack.com/",
"LastExecutionDate": "-",
"IsEnabled": 1,
"Created": "2017-05-23 14:07:18",
"Modified": "2017-05-23 14:07:18"
}
}Add Webhook
Example Request
curl -i https://api.oktopost.com/v2/webhook -X POST \
-d event="newAssignment" \
-d name="My Test" \
-d description="Send assignment to custom URL" \
-d url="http://example.com" \
-d isEnabled=1Example Result
{
"Result": true,
"Webhook": {
"Id": "0WA000000000001",
"Name": "My Test",
"Description": "Send assignment to custom URL",
"Event": "newAssignment",
"Url": "https://example.com/",
"LastExecutionDate": "-",
"IsEnabled": 1,
"Secret": "...",
"Created": "2017-05-23 14:07:18",
"Modified": "2017-05-23 14:07:18"
}
}Update Webhook
Example Request
curl -i https://api.oktopost.com/v2/webhook/0WA000000000001 -X POST \
-d event="newAssignment" \
-d name="My Test" \
-d description="Send new assignment to custom URL" \
-d url="http://example.com" \
-d isEnabled=1Example Result
{
"Result": true,
"Webhook": {
"Id": "0WA000000000001",
"Name": "My Test",
"Description": "Send new assignment to custom URL",
"Event": "newAssignment",
"Url": "https://example.com/",
"LastExecutionDate": "-",
"IsEnabled": 1,
"Created": "2017-05-23 14:07:18",
"Modified": "2017-05-23 14:07:18"
}
}Delete Webhook
Example Request
curl -i https://api.oktopost.com/v2/webhook/0WA000000000001 -X DELETEWebhooks Log
The Webhook Log stores events from Oktopost's Webhooks. The following endpoint can be used to list all recent events by a webhook Id.
Example Request
curl -i https://api.oktopost.com/v2/webhook-log/0WA000000000001Example Result
{
"Result": true,
"Items": [
{
"Id": "0WC000000000001",
"WebhookPayloadId": "0WB000000000001",
"Created": "2017-05-23 14:07:18",
"ResponseCode": 200,
"ExecutionTime": 0.034530,
"Payload": {}
}
],
"Total": 1
}Workflow
With Oktopost, you can easily set up one or multi-step approval processes, called workflows. This endpoint allows you to get the workflows available in your account.
Get Workflow
Get a single workflow by ID.
Input
- withSteps (Optional) Set to 1 to include the workflow's steps in the response.
Example Request
curl -i https://api.oktopost.com/v2/workflow/cwf000000000000?withSteps=1Example Result
{
"Result": true,
"Id": "cwf000000000000",
"Created": "2020-09-03 11:10:27",
"Name": "My Workflow",
"Status": "active",
"Steps": [
{
"Id": "cws000000000000",
"Created": "2020-09-03 11:10:27",
"WorkflowId": "cwf000000000000",
"Name": "Marketing",
"MustBeApprovedByEveryone": false,
"Approvers": [
{
"Id": "00A000000000000",
"Created": "2020-09-03 11:10:27",
"Name": "Main User",
"Email": "user@oktopost.com"
}
]
},
{
"Id": "cws000000000000",
"Created": "2020-09-03 11:11:37",
"WorkflowId": "cwf000000000000",
"Name": "Manager Confirmation",
"MustBeApprovedByEveryone": false,
"Approvers": []
}
]
}List Workflows
List all workflows in your account. Note that pagination for this endpoint is disabled.
Input
- withSteps (Optional) Set to 1 to include the workflow's steps in the response.
Example Request
curl -i https://api.oktopost.com/v2/workflow?withSteps=1Example Result
{
"Result": true,
"Items": [
{
"Id": "cwf000000000000",
"Created": "2020-09-03 11:10:27",
"Name": "My Workflow",
"Status": "active",
"Steps": [
{
"Id": "cws000000000000",
"Created": "2020-09-03 11:10:27",
"WorkflowId": "cwf000000000000",
"Name": "Marketing",
"MustBeApprovedByEveryone": false,
"Approvers": [
{
"Id": "00A000000000000",
"Created": "2020-09-03 11:10:27",
"Name": "Main User",
"Email": "user@oktopost.com"
}
]
},
{
"Id": "cws000000000001",
"Created": "2020-09-03 11:11:37",
"WorkflowId": "cwf000000000000",
"Name": "Manager Confirmation",
"MustBeApprovedByEveryone": false,
"Approvers": []
}
]
}
]
}Workflow Item
Workflow items are Posts and Messages that were sent for approval. With this endpoint, you can view all the items pending approval, send new items to approve, and remove items from the workflow.
List Items
List messages and posts in your workflows.
Parameters
| Param | Default | Description |
|---|---|---|
| page | 0 | The current page |
| count | 20 | The number of results per page. From 1 to 1000 maximum. |
| stepId | - | Optional. Return the items in this step only |
| workflowId | - | Optional. Return the items in this workflow only |
| withHistory | 0 | Optional. If set to 1, return the history information for each item. |
| withAuthors | 0 | Optional. If set to 1, an additional object under the key Authors is returned. This object will contain all of the users present in the CreatedBy field of each item. |
| withSteps | 0 | Otional. If set to 1, all of the steps for the requested items are added to the response under Steps. |
Example Request
curl -i https://api.oktopost.com/v2/workflow-itemExample Result
{
"Result": true,
"Total": 1,
"Items": [
{
"Id": "cwi000000000000",
"CreatedBy": "00A000000000001",
"Status": "pending",
"StepId": "cws000000000000",
"WorkflowId": "cwf000000000000",
"MessageId": "005000000000000"
}
],
"Authors": {
"00A000000000001": {
"Id": "00A000000000001",
"Created": "2020-09-03 11:10:27",
"Name": "Other User",
"Email": "other.user@oktopost.com"
}
},
"Steps": {
"cws000000000000": {
"Id": "cws000000000000",
"Created": "2020-09-03 11:28:48",
"WorkflowId": "cwf000000000000",
"Name": "Step 1",
"MustBeApprovedByEveryone": false,
"Approvers": [
{
"Id": "00A000000000000",
"Created": "2020-09-03 11:28:48",
"Name": "Main User",
"Email": "user@oktopost.com"
}
]
}
}
}Sending items to approval
Use this endpoint to send a message or post to approval. The entityId parameter can be either a Message or Post ID.
Example Request
curl -i http://api.oktopost.com/v2/workflow-item -X POST \
-d entityId=005000000000000 \
-d workflowId=cwf000000000000Example Result
{
"Result": true,
"Data": {
"Id": "cwi000000000000",
"CreatedBy": "00Aeh4wb9by9whl",
"Status": "pending",
"StepId": "cws000000000000",
"WorkflowId": "cwf000000000000",
"MessageId": "005000000000000"
}
}Approving and rejecting items
Use this endpoint to approve or request revisions for items that are pending approval.
Parameters
| Param | Default | Description |
|---|---|---|
| note | - | Add a text note to the approve or reject action |
| isApprove | 0 | Set to 1 to approve the item and to 0 to reject it |
| stepId | - | Optional. If set, it must be equal to the current items' step in the approval process. If you pass a different step ID, then no changes will be made. We recommend that use it to avoid potential mistakes when calling this endpoint multiple times. |
Example Request
curl -i https://api.oktopost.com/v2/workflow-item/005000000000000 -X POST \
-d note="Looks good!!!" \
-d isApprove=1 \
-d stepId=cws000000000000Example Result
{
"Result": true,
"Data": {
"Id": "cwi000000000000",
"CreatedBy": "00Aeh4wb9by9whl",
"Status": "pending",
"StepId": "cws000000000000",
"WorkflowId": "cwf000000000000",
"MessageId": "005000000000000"
}
}Removing items from the workflow
Removing posts and messages from the workflow will revert them to Drafts.
Example Request
curl -i https://api.oktopost.com/v2/workflow-item/005000000000000 -X DELETEExample Result
{
"Result": true
}Workflow Step
Every workflow in Oktopost has steps that define the users who need to approve the content and if everyone or anyone can approve before the item proceeds to the next step. Once all steps are exhausted, the item will be approved. You can use this endpoint to get information about the workflow steps and their definitions.
Get Workflow Step
Get a single workflow step by ID.
Example Request
curl -i https://api.oktopost.com/v2/workflow-step/cwskempkanbh37gExample Result
{
"Result": true,
"Id": "cws000000000000",
"Created": "2020-09-03 11:10:27",
"WorkflowId": "cwf000000000000",
"Name": "Marketing",
"MustBeApprovedByEveryone": false,
"Approvers": [
{
"Id": "00Aeh4wb9by9whl",
"Created": "2020-09-03 11:10:27",
"Name": "Oktotest Tester",
"Email": "oktotest@oktopost.com"
}
]
}List Steps
List all steps in the account or a specific workflow.
- workflowId (Optional)
Example Request
curl -i https://api.oktopost.com/v2/workflow-step?workflowId=cwf000000000000Example Result
{
"Result": true,
"Items": [
{
"Id": "cws000000000000",
"Created": "2020-09-03 11:10:27",
"WorkflowId": "cwf000000000000",
"Name": "Marketing",
"MustBeApprovedByEveryone": false,
"Approvers": [
{
"Id": "00Aeh4wb9by9whl",
"Created": "2020-09-03 11:10:27",
"Name": "Main User",
"Email": "oktotest@oktopost.com"
}
]
},
{
"Id": "cws000000000001",
"Created": "2020-09-03 11:11:37",
"WorkflowId": "cwf000000000000",
"Name": "Manager Confirmation",
"MustBeApprovedByEveryone": false,
"Approvers": []
}
]
}