Posts

A social media post is content that has been scheduled or published to a specific social profile on a specific date and time. Posts are based on Messages, which are reusable content templates that can be scheduled multiple times across different profiles and dates. Use these endpoints to create posts from messages, schedule them for publication, retrieve post details and analytics, and manage your posting queue.

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 Messages API
campaignId	-	See Campaigns 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
targetingPresetId	-	Optional. A targeting preset ID to apply LinkedIn audience targeting. Only supported for LinkedIn Company Page credentials. See Targeting Presets.
workflowId	-	Optional. Submit the post into a content-approval workflow. When provided, the post status is forced to `draft` regardless of the `status` parameter. See Workflows.
firstComment	-	Optional. Nested object for a LinkedIn first comment. See First Comment.

Update Post

Posts can only be updated or deleted before they're published. Once a post has been sent to a social network, it cannot be modified or removed through the API.

To move a post to a different campaign, use the dedicated Change Campaign endpoint. The update endpoint does not support changing campaignId.

To clear audience targeting from a post, pass an empty targetingPresetId value. The workflowId parameter is only supported on post creation — if sent on update it is ignored.

To attach, update, or remove a LinkedIn first comment, pass the nested firstComment object. See First Comment.

All parameters available on post creation can be updated as-well.

Example Request

curl -i https://api.oktopost.com/v2/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/v2/post/004000000000000 -X DELETE

Example Response

{  
    "Result":true
}

First Comment

A first comment is an optional LinkedIn comment scheduled to publish after its parent post succeeds. Create, update, and remove first comments through the Create Post and Update Post endpoints by passing a nested firstComment object. Get Post and List Posts include a FirstComment object only when a first comment exists.

First comments are only supported for LinkedIn posts.

First comments can only be created or modified before the post is published. Once a post has been sent to a social network, the first comment cannot be changed through the API.

Content is required: non-empty text and/or an image media ID.

Mentioning is currently not supported via this API.

Request Fields

Pass nested form fields using firstComment[...] encoding.

Field	Default	Description
text	-	Comment text. Maximum 3000 characters.
media	-	A single pre-uploaded image media ID. Images only. See Media API.

On update, omitted fields keep their existing values. To remove the first comment entirely, send an empty value (firstComment=) or null (firstComment=null). Updating only startDateTime on a post syncs FirstComment.ScheduledAt to match.

Example Requests

Create a post with a first comment:

curl -i https://api.oktopost.com/v2/post -X POST \
    -d messageId=005000000000000 \
    -d credentialIds=003-001000000000000-12345678 \
    -d startDateTime=1401908598 \
    -d status=draft \
    -d firstComment[text]=Created+through+Post+API

Update first comment text (other fields are preserved):

curl -i https://api.oktopost.com/v2/post/004000000000000 -X POST \
    -d firstComment[text]=Updated+through+Post+API

Attach a pre-uploaded image:

curl -i https://api.oktopost.com/v2/post/004000000000000 -X POST \
    -d firstComment[text]=With+media \
    -d firstComment[media]=026000000000000

Remove a first comment:

curl -i https://api.oktopost.com/v2/post/004000000000000 -X POST \
    -d firstComment=

Or clear with an explicit null:

curl -i https://api.oktopost.com/v2/post/004000000000000 -X POST \
    -d firstComment=null

Response Fields

Create, update, get, and list post responses include Post.FirstComment (or Items[].FirstComment on list) only when a first comment exists. When none is attached, the FirstComment key is omitted.

Field	Description
Id	First comment ID
Network	Social network for the comment (LinkedIn)
Status	Publishing status of the first comment
ScheduledAt	Scheduled time, kept in sync with the post `StartDateTime`
Text	Comment text
CampaignId	Campaign ID associated with the comment
Media	Array of attached media objects. Empty when none

Example Response

{
    "Result": true,
    "Post": {
        "Id": "004000000000000",
        "Network": "LinkedIn",
        "Status": "draft",
        "FirstComment": {
            "Id": "0fc000000000000",
            "Network": "LinkedIn",
            "Status": "pending",
            "ScheduledAt": 1401908598,
            "Text": "Created through Post API",
            "CampaignId": "002000000000000",
            "Media": []
        }
    }
}

When no first comment is attached, FirstComment is omitted from the post object:

{
    "Result": true,
    "Post": {
        "Id": "004000000000000",
        "Network": "LinkedIn",
        "Status": "draft"
    }
}

Change Post Campaign

Moves a post to a different campaign. This is a separate operation from updating a post — it involves reassigning the post's campaign association, updating related analytics, and recalculating stats.

Posts with a RUNNING status (already published/live) cannot be moved to a different campaign.

If the post is part of a content-approval workflow, only the assigned approver for the post's current workflow step may perform this action.

Example Request

curl -i https://api.oktopost.com/v2/post/004000000000000/change-campaign -X POST \
    -d campaignId=002000000000001

Parameters

Param	Default	Description
campaignId	-	Required. The target Campaign ID to move the post to. See Campaigns API

Example Response

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

Error Responses

Status	Condition
400	Post is in a workflow and the caller is not the current approver
400	Post status is RUNNING

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

On this page