Calendar

View and manage your social media content calendar with scheduled posts and publishing timeline.

The Calendar endpoint provides access to your social media calendar, allowing you to retrieve scheduled posts, view publishing timelines, and manage your content schedule across all connected social networks and 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",
            "ApproveStatus": "Approved",
            "TotalCount": 1
        }
    },
    "CustomEvents" : [],
    "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 Messages API
networks	Array	Options: Facebook, Twitter, LinkedIn, Instagram, YouTube, and TikTok
postSources	Array	See Posts API
statuses	Array	See Posts 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"]}

Custom Calendar Events

Custom events allow you to add non-holiday events to the calendar, including campaign milestones, meetings, product launches, deadlines, and reminders.

Get Custom Calendar Event

Get the data for a single custom calendar event.

Example Request

curl -i "https://api.oktopost.com/v2/calendar/custom-events?id=0CE00000000000x"

Example Result

{
    "Result": true,
    "Item": {
        "ID": "0CE00000000000x",
        "Created": "2026-08-01 09:30:00",
        "Modified": "2026-08-01 09:30:00",
        "AccountID": "00100000000000x",
        "Title": "Product launch",
        "Description": "Launch the new product website.",
        "Color": "#3492bf",
        "StartDateTime": "2026-08-10 12:00:00",
        "EndDateTime": "2026-08-10 13:00:00",
        "Campaigns": [
            {
                "Id": "00200000000000x",
                "Name": "Product Launch"
            }
        ]
    }
}

Parameters

Prop	Description	Required	Default
id	The custom calendar event ID.	√	-

A 404 error is returned when the event does not exist or the authenticated user does not have access to it.

Get Custom Calendar Events

List custom calendar events that are visible to the authenticated user.

When no campaign IDs are provided, all events available to the authenticated user are returned.

Example Request

curl -i https://api.oktopost.com/v2/calendar/custom-events \
    --data-urlencode after=1785542400 \
    --data-urlencode before=1788220799 \
    --data-urlencode "campaignIds[]=00200000000000x" \
    --data-urlencode _page=0 \
    --data-urlencode _count=25 \
    --data-urlencode _order=startDateTime

Example Result

{
    "Result": true,
    "Total": 2,
    "Items": [
        {
            "ID": "0CE00000000000x",
            "Created": "2026-08-01 09:30:00",
            "Modified": "2026-08-01 09:30:00",
            "AccountID": "00100000000000x",
            "Title": "Product launch",
            "Description": "Launch the new product website.",
            "Color": "#3492bf",
            "StartDateTime": "2026-08-10 12:00:00",
            "EndDateTime": "2026-08-10 13:00:00",
            "Campaigns": [
                {
                    "Id": "00200000000000x",
                    "Name": "Product Launch"
                }
            ]
        },
        {
            "ID": "0CE00000000000y",
            "Created": "2026-08-02 11:00:00",
            "Modified": "2026-08-02 11:00:00",
            "AccountID": "00100000000000x",
            "Title": "Campaign review",
            "Description": "Review the first week of campaign performance.",
            "Color": "#9b59b6",
            "StartDateTime": "2026-08-17 10:00:00",
            "EndDateTime": "2026-08-17 11:00:00",
            "Campaigns": [
                {
                    "Id": "00200000000000x",
                    "Name": "Product Launch"
                }
            ]
        }
    ]
}

Parameters

Prop	Description	Required	Default
ids	An array of custom calendar event IDs.	-	All events
campaignIds	An array of campaign IDs. See Campaigns API.	-	All accessible campaigns
after	The beginning of the requested date range as a Unix timestamp.	-	-
before	The end of the requested date range as a Unix timestamp.	-	-
_page	The current page.	-	0
_count	The number of events returned per page. Options: `25`, `50`, or `100`.	-	25
_order	Options: created, modified, startDateTime.	-	created

Example Request by Event IDs

curl -i -G https://api.oktopost.com/v2/calendar/custom-events \
    --data-urlencode "ids[]=0CE00000000000x" \
    --data-urlencode "ids[]=0CE00000000000y"

Add Custom Calendar Event

Create a new custom calendar event.

When endDate is not provided, a single-day event is created.

Parameters

Prop	Description	Required	Default
title	The event title. Maximum 80 characters.	√	-
description	The event description. Maximum 2,000 characters, excluding HTML tags.	-	Empty
startDate	The event start date and time as a Unix timestamp.	√	-
endDate	The event end date and time as a Unix timestamp.	-	-
campaignIds	An array of campaign IDs associated with the event. See Campaigns API.	-	Empty

Example Request

curl -i https://api.oktopost.com/v2/calendar/custom-events -X POST \
    -d title="Product launch" \
    -d description="Launch the new product website." \
    -d startDate=1786352400 \
    -d endDate=1786356000 \
    -d "campaignIds[]=00200000000000x"

Example Result

{
    "Result": true,
    "Item": {
        "ID": "0CE00000000000x",
        "Created": "2026-08-01 09:30:00",
        "Modified": "2026-08-01 09:30:00",
        "AccountID": "00100000000000x",
        "Title": "Product launch",
        "Description": "Launch the new product website.",
        "Color": "#3492bf",
        "StartDateTime": "2026-08-10 12:00:00",
        "EndDateTime": "2026-08-10 13:00:00",
        "Campaigns": [
            {
                "Id": "00200000000000x",
                "Name": "Product Launch"
            }
        ]
    }
}

Edit Custom Calendar Event

Update an existing custom calendar event.

Only the id parameter is required. Properties that are not included in the request retain their existing values.

Parameters

Prop	Description	Required	Default
id	The custom calendar event ID.	√	-
title	The event title. Maximum 80 characters.	-	Current value
description	The event description. Maximum 2,000 characters, excluding HTML tags.	-	Current value
startDate	The event start date and time as a Unix timestamp.	-	Current value
endDate	The event end date and time as a Unix timestamp.	-	Current value
campaignIds	An array of campaign IDs associated with the event. See Campaigns API.	-	Current value

Example Request

curl -i https://api.oktopost.com/v2/calendar/custom-events -X PUT \
    -d id="0CE00000000000x" \
    -d title="Updated product launch" \
    -d endDate=1786356000 \
    -d "campaignIds[]=00200000000000x"

Example Result

{
    "Result": true,
    "Item": {
        "ID": "0CE00000000000x",
        "Created": "2026-08-01 09:30:00",
        "Modified": "2026-08-02 14:20:00",
        "AccountID": "00100000000000x",
        "Title": "Updated product launch",
        "Description": "Launch the new product website.",
        "Color": "#3492bf",
        "StartDateTime": "2026-08-10 12:00:00",
        "EndDateTime": "2026-08-10 13:00:00",
        "Campaigns": [
            {
                "Id": "00200000000000x",
                "Name": "Product Launch"
            }
        ]
    }
}

Delete Custom Calendar Event

Delete a custom calendar event.

Parameters

Prop	Description	Required	Default
id	The custom calendar event ID.	√	-

Example Request

curl -i https://api.oktopost.com/v2/calendar/custom-events -X DELETE \
    -d id="0CE00000000000x"

Example Result

{
    "Result": true
}

A 404 error is returned when the event does not exist.

A 403 error is returned when the authenticated user does not have permission to delete the event.

On this page