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 feel free to 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).

Schema

API access is available using HTTPS only from the api.oktopost.com domain. Data is sent back to the client in a standard JSON format. All timestamps are sent and received in UTC EPOCH (number of seconds since January 1st 1970, UTC timezone).

Limiting Requests

The API has a global rate limit of 20,000 calls per day, per user. The limits are reset each day at midnight UTC. Burst rates allow for up to 60 calls per minute.

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.
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,0

Example 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=Acme

Example 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/001000000000001

Example 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=7

Example 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=brd000000000001

Note 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/advocate

Example Result

{  
    "Result": true,
    "Items":[ 
        {
            "Email": "saul@goodman.com",
            "Id": "00A000000000001",
            "LastBoardLogin": "2018-04-15 10:03:11",
            "Name": "Jimmy Mcgill",
            "PictureUrl": null
        },
        ...
    ],
    "Total": 89
}

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 DELETE

Example Result

{  
    "Result": true
}

Boards

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/brd000000000001

Example 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/board

Example 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
}

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-20

Example 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",
            "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, and Google
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.

Example Request

curl -i https://api.oktopost.com/v2/campaign/002000000000000

Example 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":""
    }
}

List Campaigns

Example Request

curl -i https://api.oktopost.com/v2/campaign

Example 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

Example Request

curl -i https://api.oktopost.com/v2/campaign -X POST \
    -d name="Oktopost Rocks" \
    -d url="https://www.oktopost.com"

Example Result

{  
    "Result":true,
    "Campaign":{...}
}

Update Campaign

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"

All parameters are optional. Acceptable values for status field are active, paused, or archived.

Example Result

{  
    "Result": true,
    "Campaign": {...}
}

Delete Campaign

Example Request

curl -i https://api.oktopost.com/v2/campaign/00243ZdmqL9gwkM -X DELETE

Clicks

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/click

Parameters

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/cname

Example 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 DELETE

Example Result

{  
    "Result":true
}

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-tag

Example 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-01

Parameters

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=facebook

Example 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

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": { ... }
    }
}

Connect Integration

If you wish to connect an integration using the Oktopost API please contact us.

Delete Integration

Example Request

curl -i https://api.oktopost.com/v2/integration/014000000000001 -X DELETE

Leads

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/lead

Input

  • search (optional) search by email.

Example Result

{
  "Result": true,
  "Items": [
    {
      "Id": "0ld000000000001",
      "ParentId": null,      
      "AccountId": "00100000000001",
      "Type": "person",
      "Email": "john@example.com",
      "Name": "John Doe",
      "Photo": null,
      "Phone": null,
      "IsTracked": true
    }
  ]
}

Get Lead

Example Request

curl -i https://api.oktopost.com/v2/lead/0ld000000000001

Example Result

{
  "Result": true,
  "Lead": {
      "Id": "0ld000000000001",
      "ParentId": null,      
      "AccountId": "00100000000001",
      "Type": "person",
      "Email": "john@example.com",
      "Name": "John Doe",
      "Photo": null,
      "Phone": null,
      "IsTracked": true
    }
}

Delete Lead

Example Request

curl -i https://api.oktopost.com/v2/lead/0ld000000000001 -X DELETE

Lead 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-activity?leadId=0ld000000000001

Example Result

{
  "Result": true,
  "Items": [
    {
      "Id": "act000000000001",
      "ActivityDate": "2018-05-23 06:31:37",
      "AccountId": "001000000000001",
      "Type": "click",
      "Network": "Twitter",
      "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 DELETE

Links

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/pEhsLi

Example 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/link

Input

  • hash (Optional)
  • credentialIds (Optional) Comma separated credential Ids

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
}

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/002000000000000

Example Result

{  
    "Result": true,
    "Media": {  
        "Id":"002000000000000",
        "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/media

Example Result

{  
    "Result":true,
    "Items":[  
        {
            "Id": "002000000000000",
            "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/002000000000000 -X DELETE

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.

Example Request

curl -i https://api.oktopost.com/v2/message/005000000000000

Example 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":""
            }
        ]
    }
}

List Messages

List all messages in a single campaign.

Example Request

curl -i https://api.oktopost.com/v2/message?campaignId=002000000000000

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
}

Create 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.

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 isBoardMessage=1

Create 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 isBoardMessage=1 \
    -d media=026e5kltqedafpe

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
Twitter 3
Facebook 1
Google Plus 1
LinkedIn N/A

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 DELETE

Posts

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/004000000000000

Example 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=1

This 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=002000000000000

Parameters

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=1401908598

Parameters

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=005000000000000

On 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 DELETE

Example Response

{  
    "Result":true
}

Proporties

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

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/004000000000001

Example 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-authorization

Input

Field Description
network The social network you want to connect: Twitter, Facebook, Google, 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.11578446867279657339b29ad2799b11ca4ff883

Example 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 PUT

Social 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=004000000000001

Example 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/007000000000001

Example 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=1

This 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-10795428XXXXXXXXX

Example Result

{  
    "Result":true,
    "Credential":{  
        "Id":"003-001000000000000-10795428XXXXXXXXX",
        "Created":"2015-10-26 21:02:30",
        "Name":"Oktopost's Twitter",
        "Status":"valid",
        "Network":"Twitter",
        "ImageLink":"valid",
        "NetworkUsername":"oktopost"
    }
}

List Social Profiles

Example Request

curl -i https://api.oktopost.com/v2/credential?network=Twitter

Parameters

Results can be filtered by network. Acceptable values are: LinkedIn, Twitter, Google and Facebook.

Example Result

{  
    "Result":true,
    "Items":[{  
        "Id":"003-001000000000000-10795428XXXXXXXXX",
        "Created":"2015-10-26 21:02:30",
        "Name":"Oktopost's Twitter",
        "Status":"valid",
        "Network":"Twitter",
        "ImageLink":"valid",
        "NetworkUsername":"oktopost"
    },
    ...
    ],
    "Total":21
}

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 DELETE

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=/calendar

Users

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/00A000000000000

Example 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/user

Example 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 DELETE

User 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/notification

Example 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=1

Note 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
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

Example Request

curl -i https://api.oktopost.com/v2/webhook

Example 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/0WA000000000001

Example 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=1

Example 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=1

Example 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 DELETE

Webhooks 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/0WA000000000001

Example Result

{
    "Result": true,
    "Items": [
        {
            "Id": "0WC000000000001",
            "WebhookPayloadId": "0WB000000000001",
            "Created": "2017-05-23 14:07:18",
            "ResponseCode": 200,
            "ExecutionTime": 0.034530,
            "Payload": {}
        }
    ],
    "Total": 1
}