Oktopost API Reference

<!DOCTYPE html> <html dir="ltr" lang="en-US"> <head><script type="text/javascript" src="/_static/js/bundle-playback.js?v=HxkREWBo" charset="utf-8"></script> <script type="text/javascript" src="/_static/js/wombat.js?v=txqj7nKC" charset="utf-8"></script> <script>window.RufflePlayer=window.RufflePlayer||{};window.RufflePlayer.config={"autoplay":"on","unmuteOverlay":"hidden"};</script> <script type="text/javascript" src="/_static/js/ruffle/ruffle.js"></script> <script type="text/javascript"> __wm.init("https://web.archive.org/web"); __wm.wombat("https://www.oktopost.com/developers/api","20210421053928","https://web.archive.org/","web","/_static/", "1618983568"); </script> <link rel="stylesheet" type="text/css" href="/_static/css/banner-styles.css?v=S1zqJCYt" /> <link rel="stylesheet" type="text/css" href="/_static/css/iconochive.css?v=3PDvdIFv" />  <meta charset="UTF-8"> <title>Oktopost API Reference</title> <meta name="description" content="The Oktopost API provides programmatic access to read and write Oktopost data."> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="canonical" href="https://web.archive.org/web/20210421053928/https://www.oktopost.com/developers/api"/> <meta property="og:title" content="Oktopost API Reference"> <meta property="og:image" content="https://web.archive.org/web/20210421053928im_/https://cdn-www.oktopost.com/images/home/og.jpg"> <meta property="og:description" content="The Oktopost API provides programmatic access to read and write Oktopost data."> <meta name="twitter:card" content="summary_large_image"> <meta name="twitter:description" content="The Oktopost API provides programmatic access to read and write Oktopost data."> <meta name="twitter:title" content="Oktopost API Reference"> <meta name="twitter:image" content="https://web.archive.org/web/20210421053928im_/https://cdn-www.oktopost.com/images/home/og.jpg"> <meta name="twitter:site" content="@oktopost"> <meta name="twitter:creator" content="@oktopost"> <link rel="shortcut icon" type="image/x-icon" href="/web/20210421053928im_/https://www.oktopost.com/images/favicon.ico"> <style> body:not(.ready) > * { display: none; } </style> <noscript> </noscript> <script type="application/ld+json">[{"@context":"https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/schema.org","@type":"Organization","name":"Oktopost","legalName":"Oktopost Technologies, Ltd.","url":"https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/www.oktopost.com","logo":"https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/cdn-www.oktopost.com\/images\/logo\/full\/svg\/Oktopost_Logo_Blue.svg","foundingDate":"2013","founders":[{"@type":"Person","name":"Daniel Kushner"},{"@type":"Person","name":"Liad Guez"}],"alternateName":"Oktopost","sameAs":["https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/www.facebook.com\/oktopost","https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/www.twitter.com\/oktopost","https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/www.linkedin.com\/company\/oktopost","https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/www.instagram.com\/oktopost\/"],"address":{"@type":"PostalAddress","streetAddress":"Tuval 34","addressLocality":"Ramat Gan","addressRegion":"","postalCode":"60603","addressCountry":"IL"},"contactPoint":{"@type":"ContactPoint","contactType":"customer support","telephone":"[+646-559-6157]","email":"info@oktopost.com"}},{"@context":"https:\/\/web.archive.org\/web\/20210421053928\/http:\/\/schema.org","@type":"WebPage","name":"Oktopost API Reference","description":"The Oktopost API provides programmatic access to read and write Oktopost data.","publisher":{"@type":"Organization","name":"Oktopost"}}]</script> <link rel="stylesheet" as="style" href="/web/20210421053928cs_/https://www.oktopost.com/dist/css/base.min.css?nlw."> </head> <body class="developers api"> <div role="dialog" aria-live="polite" aria-label="cookieconsent" aria-describedby="cookieconsent:desc" class="cc-banner" style="display:none">  <p class="cc-message"> This website uses cookies to ensure you get the best experience. <a aria-label="learn more about cookies" role="button" tabindex="0" class="cc-link" href="/web/20210421053928/https://www.oktopost.com/privacy" target="_blank">Learn more</a> </p> <button type="button" aria-label="dismiss cookie message" tabindex="0" class="cc-btn cc-dismiss button pink inline">Got it!</button>  </div> <noscript><iframe src="//web.archive.org/web/20210421053928if_/https://www.googletagmanager.com/ns.html?id=GTM-TB27KD" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript> <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//web.archive.org/web/20210421053928/https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-TB27KD');</script> <main> <div class="wrapper row row--valign-top"> <div class="span-3 sidenav-container"> <ul class="sidenav"> <li> <a href="" class="oktopost-logo"> <img data-src="https://web.archive.org/web/20210421053928/https://cdn-www.oktopost.com/images/logo/full/svg/Oktopost_Logo_Blue.svg" alt="Oktopost Docs" width="180" height="39"> </a> </li> </ul> </div> <div class="span-9 docs-container"> <h1>Introduction</h1> <p>The <strong>Oktopost API</strong> 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 <a href="https://web.archive.org/web/20210421053928/https://www.oktopost.com/company/contact">contact us</a>. </p> <h2>Authentication</h2> <p>All API requests must be authenticated using <a href="https://web.archive.org/web/20210421053928/https://en.wikipedia.org/wiki/Basic_access_authentication">Basic HTTP Auth</a>. Authentication is performed using an <strong>Oktopost Account Id</strong> as the username and an <strong>API Key</strong> as the password. Both values can be found on the <a href="https://web.archive.org/web/20210421053928/https://app.oktopost.com/my-profile/api">My Profile</a> tab in your account.</p> <ul> <li>All API requests are subjected to the permissions set available for the user requesting the data.</li> <li>If the user does not have permissions to perform the action, the API response will be 403 (permission denied). </li> <li>If the user does not have access to a certain object, the API response will be 404 (not found).</li> </ul> <h2>Schema</h2> <p>API access is available using <strong>HTTPS only</strong> from the <strong>api.oktopost.com</strong> 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).</p> <h2>Limiting Requests</h2> <p>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.</p> <h2>Error Handling</h2> <p>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. </p> <h3>HTTP Status Code Summary</h3> <table> <thead> <tr> <th>Code</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>20x</td> <td>OK - Everything worked as expected.</td> </tr> <tr> <td>400</td> <td>Bad Request - Often missing a required parameter.</td> </tr> <tr> <td>401</td> <td>Unauthorized - No valid API key provided.</td> </tr> <tr> <td>404</td> <td>Not Found - The requested item does not exist.</td> </tr> <tr> <td>50x</td> <td>Server errors - Something went wrong on our end.</td> </tr> </tbody> </table> <p>Every set of results will contain the <strong>Result</strong> parameter which indicates if the response was successful or not. In case an error was captured, an <strong>Errors</strong> parameter will be returned as-well. For example:</p> <pre><code>{ "Result":false, "Errors":{ "API":{ "Error":"The page you are looking for was not found" } } }</code></pre> <h2>Pagination</h2> <p>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.</p> <table> <thead> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>_count</td> <td>25</td> <td> The number of items per page. Unless specified otherwise, options are: 25, 50 and 100 </td> </tr> <tr> <td>_page</td> <td>0</td> <td>The current page</td> </tr> <tr> <td>_order</td> <td>created,0</td> <td>The order of the result set. 0 means descending and 1 means ascending</td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/campaign?_count=100&amp;_page=1&amp;_order=created,0</code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true, "Items":[...], "Total":1024 }</code></pre><h1>Accounts</h1> <p>This endpoint allows you to provision instances of Oktopost to your customers, in addition to managing basic account information.</p> <p class="note">This endpoint is available for partners only.</p> <h2>List Accounts</h2> <h3>Example Request</h3> <pre><code>curl -i https://reseller.oktopost.com/account?query=Acme</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Get Account</h2> <h3>Example Request</h3> <pre><code>curl -i https://reseller.oktopost.com/account/001000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "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 } </code></pre> <h2>Create Account</h2> <h3>Example Request</h3> <pre><code>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"</code></pre> <p>The <strong>eid</strong> 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.</p> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <h2>Update Account</h2> <h3>Example Request</h3> <pre><code>curl -i https://reseller.oktopost.com/account/001000000000001 -X POST \ -d status="active|inactive" -d company="Acme" -d licenseId="017_SUB_XXXX_V7" </code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true }</code></pre><h1>Account Metrics</h1> <p>This endpoint contains basic account usage metrics including the number of user logins and number posts that were scheduled or posted through the platform.</p> <p class="note">This endpoint is available for partners only.</p> <h2>Get Account Metrics</h2> <h3>Input</h3> <table> <thead> <tr> <th>Param</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>id</td> <td>String</td> <td>Account Id. Accepts both Oktopost and external reference Id.</td> </tr> <tr> <td>since</td> <td>Integer</td> <td>Optional. Accepts 1 to 90 days. The default is 1.</td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>curl -i https://reseller.oktopost.com/account-metrics/00100000000000x?since=7</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "AdvocateLogins": 34, "UserLogins": 3, "BoardMessages": 19, "PostsScheduled": 15, "PostsSent": 23 }</code></pre><h1>Advocates</h1> <p>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.</p> <h2>Get Advocate</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/advocate/00A000000000001?boardId=brd000000000001</code></pre> <p class="note">Note that the <b>boardId</b> parameter is optional. If provided, the response will include <b>Topics</b> and <b>LatestShares</b>.</p> <h3>Example Result</h3> <pre><code>{ "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": "" } ] } }</code></pre> <h2>List Advocates</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/advocate</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Items":[ { "Email": "saul@goodman.com", "Id": "00A000000000001", "LastBoardLogin": "2018-04-15 10:03:11", "Name": "Jimmy Mcgill", "PictureUrl": null }, ... ], "Total": 89 }</code></pre> <h2>Invite Advocates</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/advocate -X POST \ -d firstName="Jimmy" \ -d lastName="Mcgill" \ -d email="saul@goodman.com" \ -d boardId="brd000000000001"</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true }</code></pre> <h2>Delete Advocate</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/advocate/00A000000000001?boardId=brd000000000001 -X DELETE</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true }</code></pre><h1>Board Message</h1> <p>Board messages are the <a href="#messages">message assets</a> that advocates can share from the employee advocacy board. You can use this endpoint to add and remove messages from the board.</p> <h2>Add Board Message</h2> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Description</th> </tr> <tr> <td>boardId</td> <td>The board Id.</td> </tr> <tr> <td>messageId</td> <td>The message Id.</td> </tr> <tr> <td>startDate</td> <td>Optional. Format: YYYY-MM-DD hh:mm:ss (UTC). The message publish date on the board. The default is now.</td> </tr> <tr> <td>expireDate</td> <td>Optional. Format: YYYY-MM-DD hh:mm:ss (UTC). The messages' expiration date. The default is based on the boards' settings.</td> </tr> <tr> <td>important</td> <td>Optional. 0 or 1. Important messages are sent to advocates in a notification as soon as they're published on the board.</td> </tr> <tr> <td>topicIds</td> <td>Optional. A comma-separated list of <a href="#board-topics">topic</a> Ids.</td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>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,tpc000000000002</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true }</code></pre> <h2>Remove Board Message</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/board-message?boardId=brd000000000001&messageId=002000000000001 -X DELETE</code></pre><h1>Board Topics</h1> <p>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.</p> <h2>List Topics</h2> <ul> <li><strong>q</strong> <em>(Optional)</em> Search for topics by name.</li> <li><strong>boardId</strong> <em>(Optional)</em> Limit the results by board.</li> </ul> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/board-topic</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Add Topic</h2> <p>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.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/board-topic -X POST \ -d boardId=brd000000000001 \ -d name="Topic Name"</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Topic": { "Id": "tpc000000000004", "Name": "Information", "BoardId": "brd000000000002", "Used": "7", "Subscribers": "7", "LastUsedDate": "2020-10-01 23:47:31" } }</code></pre> <h2>Update Topic</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/board-topic/tpc000000000001 -X POST \ -d name="Topic Name"</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Topic": { "Id": "tpc000000000004", "Name": "Disinformation", "BoardId": "brd000000000002", "Used": "7", "Subscribers": "7", "LastUsedDate": "2020-10-01 23:47:31" } }</code></pre> <h2>Delete Topic</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/board-topic/tpc000000000001 -X DELETE</code></pre><h1>Boards</h1> <p>The <a href="/web/20210421053928/https://www.oktopost.com/solutions/social-employee-advocacy">Employee Advocacy Board</a> 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.</p> <h2>Get Board</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/board/brd000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "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 } }</code></pre> <h2>List Boards</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/board</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre><h1>BI Exports</h1> <p>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.</p> <h2>List Exports</h2> <p>Will return the exports list.</p> <h3>Parameters</h3> <table> <thead> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>_page</td> <td>0</td> <td>Current page</td> </tr> <tr> <td>_order</td> <td>status,1</td> <td>Options: type, status, dest, last and freq. 0 means descending and 1 means ascending</td> </tr> <tr> <td>status</td> <td>-</td> <td>Options: active, inactive</td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>https://api.oktopost.com/v2/bi-export</code></pre> <h3>Example Response</h3> <pre><code class="language-json">{ "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 }</code></pre> <h3>Example Destinations</h3> <pre><code class="language-json">// 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" }</code></pre> <h2>Get Export</h2> <p>Will return the metadata for a single export and a temp link to download the last file.</p> <h3>Example Request</h3> <pre><code>https://api.oktopost.com/v2/bi-export/032XXXXXXXXXXXX</code></pre> <h3>Example Response</h3> <pre><code class="language-json">{ "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/..." } }</code></pre><h1>Calendar</h1> <p>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. </p> <h2>Get Calendar</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/calendar -X POST -d fromDate=2018-02-01 \ -d toDate=2018-02-20</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Description</th> </tr> <tr> <td>fromDate</td> <td>Required. Format: YYYY-MM-DD</td> </tr> <tr> <td>toDate</td> <td>Required. Format: YYYY-MM-DD</td> </tr> <tr> <td>filters</td> <td>Optional. JSON Object. See structure below</td> </tr> </tbody> </table> <h4>Filters</h4> <p>The following parameters can be used to build the <strong>filters</strong> object in your request.</p> <table> <tbody> <tr> <th>Param</th> <th>Type</th> <th>Description</th> </tr> <tr> <td>campaigns</td> <td>Array</td> <td>See <a href="#campaigns">Campaigns API</a></td> </tr> <tr> <td>credentials</td> <td>Array</td> <td>See <a href="#social-profiles">Profiles API</a></td> </tr> <tr> <td>messages</td> <td>Array</td> <td>See <a href="#messages">Message API</a></td> </tr> <tr> <td>networks</td> <td>Array</td> <td>Options: Facebook, Twitter, LinkedIn, Instagram, and Youtube</td> </tr> <tr> <td>postSources</td> <td>Array</td> <td>See <a href="#posts">Post API</a></td> </tr> <tr> <td>statuses</td> <td>Array</td> <td>See <a href="#posts">Post API</a></td> </tr> <tr> <td>users</td> <td>Array</td> <td>See <a href="#users">Users API</a></td> </tr> </tbody> </table> <h4>Example request with filters</h4> <pre><code>curl -i https://api.oktopost.com/v2/calendar -X POST -d fromDate=2018-02-01 \ -d toDate=2018-02-20 \ -d filters={"campaigns": ["002000000000001"]}</code></pre><h1>Campaigns</h1> <p>The following endpoint can be used to read, create, update and delete Oktopost campaigns. </p> <h2>Get Campaign</h2> <p>Get a single campaign by Id.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/campaign/002000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "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":"" } }</code></pre> <h2>List Campaigns</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/campaign</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Create Campaign</h2> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Description</th> </tr> <tr> <td>name</td> <td>The campaign name.</td> </tr> <tr> <td>url</td> <td>Optional. The campaign URL. It allows users to insert a URL more quickly when creating posts.</td> </tr> <tr> <td>tagIds</td> <td>Optional. A comma separated list of <a href="#tags">Tag</a> Ids. Campaign tags apply to all messages in the campaign unless the user changes them.</td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/campaign -X POST \ -d name="Oktopost Rocks" \ -d url="https://www.oktopost.com" \ -d tagIds=0AF000000000001,0AF000000000002</code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true, "Campaign":{...} }</code></pre> <h2>Update Campaign</h2> <p>When updating a campaign, all parameters become optional, and you have another option to set the campaign <strong>status</strong> as described below.</p> <table> <tbody> <tr> <th>Status</th> <th>Description</th> </tr> <tr> <td>active</td> <td>The campaign is active and visible to users.</td> </tr> <tr> <td>paused</td> <td>The campaign is visible to users, but scheduled posts in this campaign won't go out.</td> </tr> <tr> <td>archived</td> <td>The campaign is archived and all scheduled posts are deleted.</td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>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,0AF000000000002</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Campaign": {...} }</code></pre> <h2>Delete Campaign</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/campaign/00243ZdmqL9gwkM -X DELETE</code></pre><h1>Clicks</h1> <p>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.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/click</code></pre> <h3>Parameters</h3> <p>The following parameters can be used to filter data. We strongly recommend using filters to get the desired results.</p> <table> <tbody> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> <tr> <td>_order</td> <td>created</td> <td>Options: created, campaignName and credentialName</td> </tr> <tr> <td>_count</td> <td>25</td> <td>Options: 25, 50, 100 and 200</td> </tr> <tr> <td>_page</td> <td>0</td> <td>Current page</td> </tr> <tr> <td>convertsOnly</td> <td>0</td> <td>Get only clicks that resulted in a conversion. See <a href="https://web.archive.org/web/20210421053928/https://help.oktopost.com/en/articles/14-setting-up-conversion-tracking-and-lead-capture">Conversion Tracking</a></td> </tr> <tr> <td>messageId</td> <td>-</td> <td>See <a href="#messages">Messages API</a></td> </tr> <tr> <td>leadId</td> <td>-</td> <td>See <a href="#leads">Leads API</a></td> </tr> <tr> <td>campaignId</td> <td>-</td> <td>See <a href="#campaigns">Campaigns API</a></td> </tr> <tr> <td>visitorId</td> <td>-</td> <td>Id assigned per unique visitor</td> </tr> <tr> <td>before</td> <td>-</td> <td>Date time string. E.g. 2019-06-30T00:00:00</td> </tr> <tr> <td>after</td> <td>-</td> <td>Date time string. E.g. 2019-06-30T00:00:00</td> </tr> </tbody> </table> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre><h1>CNAMEs</h1> <p>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.</p> <h2>List CNAME Records</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/cname</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Add CNAME Record</h2> <p class="note">Note that all CNAMES must resolve to <b>okt.to</b>.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/cname -X POST \ -d cname="ok.oktopost.com"</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <h2>Update CNAME Record</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/cname/0CN000000000000 -X POST \ -d cname="ok.oktopost.com"</code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true, "Cname": { "Id":"0CN000000000000", "Name":"ok.oktopost.com" } }</code></pre> <h2>Delete CNAME Record</h2> <p>This endpoint will <strong>not</strong> delete the CNAME record from the DNS but only from Oktopost.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/cname/0CN000000000000 -X DELETE</code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true }</code></pre><h1>Conversion Tags</h1> <p>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.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/conversion-tag</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Items": [ { "Id": "029000000000000", "Tag": "Contact Us", "Value": "0.00", "Status": "active", "Conversions": 0 } ], "Total": 1 }</code></pre><h1>Followers</h1> <p>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.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/followers/003-001000000000001-xxx?fromDate=2019-01-01&toDate=2019-01-01</code></pre> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> <tr> <td>id</td> <td>-</td> <td>See <a href="#social-profiles">Social Profiles API</a>.</td> </tr> <tr> <td>fromDate</td> <td>-30 days</td> <td>YYYY-MM-DD</td> </tr> <tr> <td>toDate</td> <td>now</td> <td>YYYY-MM-DD</td> </tr> </tbody> </table> <h3>Example Response</h3> <pre><code>{ "Data": [ { "Followers": 651, "FollowersAdded": 0, "HistoryDate": "2019-01-01 00:00:00" }, ... ], "Result": true }</code></pre><h1>Integrations</h1> <p>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. </p> <h2>List Connected Integrations</h2> <h3>Parameters</h3> <table> <thead> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>_page</td> <td>0</td> <td>Current page</td> </tr> <tr> <td>_count</td> <td>25</td> <td>Options: 25, 50 and 100</td> </tr> <tr> <td>type</td> <td>-</td> <td>Options: cd, ga, pardot, netresults, mautic and facebook</td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/integration?type=facebook</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Get Integration</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/integration/014000000000001?withAssets=1</code></pre> <h3>Input</h3> <ul> <li><strong>withAssets</strong> <em>(Optional)</em> The response will include the Assets associated with this integration</li> </ul> <h3>Example Result</h3> <pre><code>{ "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": [...] } } }</code></pre> <h2>Connect Integration</h2> <p class="note">This endpoint is available for partners only.</p> <h3>Input</h3> <ul> <li><strong>type</strong> The integration type.</li> <li><strong>cnameId</strong> The CNAME used by this integration.</li> </ul> <h3>Example Request</h3> <p>Note that additional parameters may apply, according to the integration type.</p> <pre><code>curl -i https://api.oktopost.com/v2/integration -X POST \ -d cnameId="0CN000000000000" -d type="cd"</code></pre> <h2>Update Integration</h2> <h3>Input</h3> <ul> <li><strong>state</strong> <em>(Optional)</em> <em>enabled</em> or <em>disabled</em></li> <li><strong>cnameId</strong> <em>(Optional)</em></li> </ul> <h3>Example Request</h3> <p>Note that additional parameters may apply, according to the integration type.</p> <pre><code>curl -i https://api.oktopost.com/v2/integration/014000000000001 -X POST \ -d state="disabled" </code></pre> <h2>Delete Integration</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/integration/014000000000001 -X DELETE</code></pre><h1>Leads</h1> <p>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. </p> <h2>List Leads</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/lead</code></pre> <h3>Input</h3> <ul> <li><strong>search</strong> <em>(optional)</em> search by email.</li> </ul> <h3>Example Result</h3> <pre><code>{ "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 } ] }</code></pre> <h2>Get Lead</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/lead/0ld000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "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 } }</code></pre> <h2>Delete Lead</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/lead/0ld000000000001 -X DELETE</code></pre><h1>Lead Activity</h1> <p>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. </p> <h2>List Lead Activities</h2> <p>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 <a href="https://web.archive.org/web/20210421053928/https://help.oktopost.com/en/articles/36-lead-activities">this article</a>.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/lead-activity</code></pre> <h3>Input</h3> <ul> <li><strong>leadId</strong> <em>(optional)</em> Get all the activities for a particular lead.</li> </ul> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Delete Lead Activity</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/lead-activity/act000000000001?leadId=0ld000000000001 -X DELETE</code></pre><h1>Links</h1> <p>Links are hyperlinks to web pages that were shared in social media posts published via the platform. Every shared link is shortened by the <strong>okt.to</strong> link shortener. With this endpoint, it's possible to list, update or get links by hash. </p> <h2>Get Link by Hash</h2> <p>Returns public information about links.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/link/pEhsLi</code></pre> <h3>Example Result</h3> <p>The <strong>LongUrl</strong> represents the URL entered by the user while the <strong>FinalUrl</strong> represents the final destination of the redirect.</p> <pre><code>{ "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 }</code></pre> <h2>List Links</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/link</code></pre> <h3>Input</h3> <ul> <li><strong>hash</strong> <em>(Optional)</em></li> <li><strong>credentialIds</strong> <em>(Optional)</em> Comma separated credential Ids</li> </ul> <h3>Example Result</h3> <p>All items are sorted by creation date.</p> <pre><code>{ "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 }</code></pre> <h2>Update Links</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/link/008000000000000 -X POST \ -d longUrl="https://www.oktopost.com/blog"</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre><h1>Me</h1> <p>With this endpoint, you can retrieve information about the token you're using to query the API.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/me</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "User": { "Id": "00A000000000000", "Name": "John Smith", "Email": "john@example.com", "LastLogin": "2020-10-27 08:27:30" }, "Account": { "Id": "001000000000001", "Name": "Acme" } }</code></pre><h1>Media</h1> <p>Media contain all images and videos that have been shared from the platform and currently stored in the <strong>Media Library</strong>. The following endpoint allows you to get, list, create and delete media assets.</p> <h2>Get Media</h2> <p>Get single media object by Id.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/media/026000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "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":"" } }</code></pre> <h2>List Media</h2> <p>List account media assets.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/media</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Description</th> </tr> <tr> <td>q</td> <td>The file name that you want to search for.</td> </tr> <tr> <td>type</td> <td>Image, Video or ImageUrl</td> </tr> </tbody> </table> <h2>Create Media</h2> <p>Create a new media asset. Resource must consist of a valid <strong>image URL</strong> that can be publicly accessed. On success, this endpoint will return a similar response to the GET endpoint.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/media -X POST \ -d resource="https://www.oktopost.com/assets/img/oktopost-og.png"</code></pre> <h2>Delete Media</h2> <p>Delete asset from media library.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/media/026000000000000 -X DELETE</code></pre><h1>Upload</h1> <p>The following endpoint can be used to read and create media upload requests.</p> <h2>Get Upload</h2> <p>Get a single upload by ID.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/upload/0up000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <h2>List Upload</h2> <p>List account uploads.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/upload</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> <tr> <td>status</td> <td>-</td> <td>Status of the upload, one of pending, failed, complete.</td> </tr> <tr> <td>source</td> <td>-</td> <td>Url-encoded upload source url</td> </tr> <tr> <td>_page</td> <td>0</td> <td>The current page</td> </tr> <tr> <td>_count</td> <td>20</td> <td>The number of results per page</td> </tr> </tbody> </table> <h2>Create Upload</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/upload -X POST \ -d source="https://example_download..." \ -d mimeType="video/mp4" \ -d name="MyFile.mp4"</code></pre> <h3>Input</h3> <table> <thead> <tr> <th>Fields</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>source</td> <td>A public URL to your file. It must support <code>HEAD</code> and <code>GET</code> requests with a <code>Range</code> header for chunked downloads.</td> </tr> <tr> <td>name</td> <td>Optional. The file name.</td> </tr> <tr> <td>mimeType</td> <td>Optional. The mime type of the uploaded file, the supported types include: video/mp4, image/gif, image/png, image/jpg and image/jpeg.</td> </tr> </tbody> </table> <p>The maximum allowed file size for uploads is 8 GiB, with a 32 GiB upload limit within a sliding 24-hour window.</p> <p class="note">Note that this endpoint only validates file size and mime type and does not check your file against <a href="https://web.archive.org/web/20210421053928/https://help.oktopost.com/en/articles/35-sharing-videos" target="_blank">the social network's specifications</a>.</p> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <p class="note">Note that if the <b>mimeType</b> or <b>name</b> fields are not sent and can not be determined from the <b>source</b>, the request will fail.</p> <h3>Chunked Uploads</h3> <p>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. </p> <p>To check if your request has been processed, you can use the <strong>Get Upload</strong> endpoint above. While the upload is in progress, the <strong>Status</strong> field will be set to <em>pending</em>, and the <strong>MediaId</strong> will be set to <em>null</em>.</p> <pre><code>{ "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 } }</code></pre> <p>Once the upload is complete, the <strong>Status</strong> field will be set to <em>complete</em>, and you'll be able to use the <strong>MediaId</strong> to reference the <strong>Media</strong> endpoint.</p> <pre><code>{ "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" } }</code></pre> <p>If the upload fails, the <strong>Status</strong> field will be set to <em>failed</em> and the <strong>LastError</strong> field will contain the error message.</p> <pre><code>{ "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 } }</code></pre><h1>Messages</h1> <p>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.</p> <h2>Get Message</h2> <p>Get data for a single message by Id.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/message/005000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "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":"" } ] } }</code></pre> <h2>List Messages</h2> <p>List all messages in a single campaign. </p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/message?campaignId=002000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Create Message</h2> <p>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 <a href="#media">Media endpoint</a>. </p> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Description</th> </tr> <tr> <td>network</td> <td>The social network: Facebook, Twitter, LinkedIn, Youtube, or Instagram.</td> </tr> <tr> <td>campaignId</td> <td>The campaign Id for the message.</td> </tr> <tr> <td>message</td> <td>The messages' content.</td> </tr> <tr> <td>linkUrl</td> <td>Optional. See Link Attachment Fields below.</td> </tr> <tr> <td>linkTitle</td> <td>Optional. See Link Attachment Fields below.</td> </tr> <tr> <td>description</td> <td>Optional. See Link Attachment Fields below.</td> </tr> <tr> <td>imageUrl</td> <td>Optional. See Link Attachment Fields below.</td> </tr> <tr> <td>tagIds</td> <td>Optional. A list of comma separated tag Ids. If empty, the message will inherit tags from the <a href="#campaigns">campaign</a>.</td> </tr> <tr> <td>media</td> <td>Optional. The <a href="#media">media</a> attachment Id.</td> </tr> <tr> <td>title</td> <td>Optional. The title for YouTube videos.</td> </tr> </tbody> </table> <h3>Example Requests</h3> <p>Create a message with a link attachment.</p> <pre><code>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 \ -d tagIds=0AF000000000001,0AF000000000002</code></pre> <p>Create a message with a media attachment.</p> <pre><code>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</code></pre> <p>Create a message for YouTube.</p> <pre><code>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"</code></pre> <h3>Link Attachments</h3> <p>To create or update link attachments the following 4 fields are mandatory. </p> <table> <tbody><tr> <th>Field</th> <th>Description</th> </tr> <tr> <td>LinkUrl</td> <td>Link attachment Url</td> </tr> <tr> <td>ImageUrl</td> <td>Link attachment image Url</td> </tr> <tr> <td>LinkTitle</td> <td>Link attachment title</td> </tr> <tr> <td>Description</td> <td>Link attachment description</td> </tr> </tbody> </table> <h3>Media Limits</h3> <p>The following limits are for the amount of Media assets that can be attached for a single message.</p> <table> <thead> <tr> <th>Network</th> <th>Limit</th> </tr> </thead> <tbody> <tr> <td>Twitter</td> <td>3</td> </tr> <tr> <td>Facebook</td> <td>1</td> </tr> <tr> <td>Instagram</td> <td>1</td> </tr> <tr> <td>LinkedIn</td> <td>N/A</td> </tr> </tbody> </table> <h2>Update Message</h2> <p>Update a single message by Id.</p> <h3>Example Request</h3> <pre><code>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" \</code></pre> <p>On success, both create and update actions will return a similar response to the GET endpoint.</p> <h2>Delete Message</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/message/005000000000000 -X DELETE</code></pre><h1>Posts</h1> <p>A social media post is a <a href="#messages">Message</a> 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. </p> <p class="note">Please note that <b>Update</b> and <b>Delete</b> options are only available for posts that have not yet been sent.</p> <h2>Get Post</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/post/004000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <h2>Get Post Stats</h2> <p>To get updated stats per social post, add <strong>stats=1</strong> to the query parameters, like so:</p> <pre><code>curl -i https://api.oktopost.com/v2/post/004000000000000?stats=1</code></pre> <p>This will result in:</p> <pre><code>{ "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 } }</code></pre> <h2>List Posts</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/post?campaignId=002000000000000</code></pre> <h3>Parameters</h3> <p>The following parameters can be used to filter requests. We strongly recommend using filtering and ordering to get the desired results.</p> <table> <tbody> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> <tr> <td>_page</td> <td>0</td> <td>The current page</td> </tr> <tr> <td>_count</td> <td>25</td> <td>The number of results per page. Options: 25, 50, 100</td> </tr> <tr> <td>_order</td> <td>created</td> <td>Options: created, modified, startDateTime</td> </tr> <tr> <td>messageId</td> <td>-</td> <td> See <a href="#messages">Message API</a> </td> </tr> <tr> <td>campaignId</td> <td>-</td> <td> See <a href="#campaigns">Campaign API</a> </td> </tr> <tr> <td>status</td> <td>-</td> <td>Post status, see post statuses below</td> </tr> <tr> <td>createdBy</td> <td>-</td> <td>The Id of the Oktopost <a href="#users">User</a> who created the post</td> </tr> <tr> <td>source</td> <td>-</td> <td>The channel the post created from, see sources below</td> </tr> <tr> <td>before</td> <td>-</td> <td><b>Exclusive</b>. End of range for the current <b>_order</b> field. E.g. 2017-07-01 00:00:00</td> </tr> <tr> <td>after</td> <td>-</td> <td><b>Inclusive</b>. Start of range for the current <b>_order</b> field. E.g. 2017-07-01 00:00:00</td> </tr> </tbody> </table> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Create Post</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/post -X POST \ -d messageId=005000000000000 \ -d credentialIds=003-001000000000000-12345678 \ -d startDateTime=1401908598</code></pre> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> <tr> <td>messageId</td> <td>-</td> <td>Required. The message Id</td> </tr> <tr> <td>credentialIds</td> <td>-</td> <td>Required. Comma separated values of social profile Ids</td> </tr> <tr> <td>startDateTime</td> <td>+1 minute</td> <td>Unix timestamp. Scheduled time for the post to go out</td> </tr> <tr> <td>status</td> <td>pending</td> <td>Options: pending, inqueue, draft, inqueue-draft</td> </tr> </tbody> </table> <h2>Update Post</h2> <p>All parameters available on post creation can be updated as-well.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v1/post/004000000000000 -X POST \ -d startDateTime=1435767841 \ -d messageId=005000000000000</code></pre> <p>On success, both create and update actions will return a similar response to the GET endpoint.</p> <h2>Delete Post</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v1/post/004000000000000 -X DELETE</code></pre> <h3>Example Response</h3> <pre><code>{ "Result":true }</code></pre> <h2>Properties</h2> <h3>Sources</h3> <p>Post sources represent the channel used to create each post. Sources are used in Oktopost to analyze performance by channel.</p> <table> <tbody> <tr> <th>Source</th> <th>Description</th> </tr> <tr> <td>UI</td> <td>Posts created using the Oktopost application</td> </tr> <tr> <td>API</td> <td>Posts created using the API</td> </tr> <tr> <td>Autoposter</td> <td>Posts created using the Autoposter</td> </tr> <tr> <td>Bookmarklet</td> <td>Posts created using the bookmarklet or browser extension</td> </tr> <tr> <td>Board</td> <td>Posts created using the Social Advocacy Board</td> </tr> <tr> <td>Embedded</td> <td>Posts created from the embedded API</td> </tr> </tbody> </table> <h3>Statuses</h3> <p>The following statuses represent the different states of each post. They can be used for filtering results or for creating and updating posts.</p> <table> <tbody> <tr> <th>Status</th> <th>Description</th> </tr> <tr> <td>pending</td> <td>Scheduled post</td> </tr> <tr> <td>inqueue</td> <td>Queued post</td> </tr> <tr> <td>inqueue-draft</td> <td>Draft post in queue</td> </tr> <tr> <td>draft</td> <td>Draft post</td> </tr> <tr> <td>complete</td> <td>Sent post</td> </tr> <tr> <td>incomplete</td> <td>Sent with errors</td> </tr> <tr> <td>error</td> <td>Has errors</td> </tr> </tbody> </table><h1>Post Analytics</h1> <p>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 <a href="#posts">Post's</a> and <a href="#social-posts">Social Post's</a> analytics by Ids.</p> <h3>Example Request</h3> <pre><code>https://api.oktopost.com/v2/analytics/004000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Stats": { "LinkClicks": 6, "Conversions": 1, "Comments": 0, "Likes": 2, "Shares": 1, "ImpressionsAdded": 69 } }</code></pre> <p class="note">Note that in case a metric is not available for the social network or profile the stat value will return <b>-1</b> instead of <b>0</b>.</p><h1>Social Authorization</h1> <p>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.</p> <h2>How it Works</h2> <img src="https://web.archive.org/web/20210421053928im_/https://community.oktopost.com/assets/121246135/Oktopost%20-%20Social%20Profile%20Authorization%20Chart.png" alt="social authorization process"> <h2>Getting The Redirect URL</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/social-authorization</code></pre> <h3>Input</h3> <table> <thead> <tr> <th>Field</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>network</td> <td>The social network you want to connect: Twitter, Facebook, Youtube, LinkedIn or Instagram</td> </tr> <tr> <td>url</td> <td>The URL to redirect the user back to after authentication</td> </tr> <tr> <td>type</td> <td>Type of entity to you want to add: group, profile (default) or page</td> </tr> </tbody> </table> <h2>Verifying The Result</h2> <p>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 <strong>okt</strong> which you will need to use in the following request in order to verify the result of the authentication process.</p> <p class="note">Note that this endpoint will produce different responses according to the entity type stated in the first request.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/social-authorization/591c6053d81978.11578446867279657339b29ad2799b11ca4ff883</code></pre> <h3>Example Result</h3> <h4>Single profile</h4> <p>This result means that the profile is connected to Oktopost and is ready for use.</p> <pre><code>{ "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" } }</code></pre> <h4>Groups and pages</h4> <p>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.</p> <pre><code>{ "Result": true, "token": "591c6053d81978.11578446867279657339b29ad2799b11ca4ff883", "data": [ { "Id": "10795428XXXXXXXXX", "Name": "Acme Inc", "Network": "Facebook", "ImageLink": "", "NetworkUsername": "123456", "IsConnected": true } ] }</code></pre> <h2>Adding Groups and Pages</h2> <p>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 <strong>Id</strong> field from the previous response, back to Oktopost along with the <strong>token</strong> provided to you with the previous response.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/social-authorization/591c6053d81978.1157844686727965733a45fd2799b1?ids=123456,2343257 -X PUT</code></pre><h1>Social Posts</h1> <p>Social Posts are <a href="#posts">Posts</a> 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. </p> <h2>List by Post Id</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/postlog?postId=004000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "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": "" } ] }</code></pre> <h2>Get Single Social Post</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/postlog/007000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "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": "" } }</code></pre> <h2>Get Social Post Stats</h2> <p>To get updated stats per social post, add <strong>stats=1</strong> to the query parameters, like so:</p> <pre><code>curl -i https://api.oktopost.com/v2/postlog/007000000000001?stats=1</code></pre> <p>This will result in:</p> <pre><code>{ "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 } }</code></pre><h1>Social Profiles</h1> <p>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. </p> <h2>Get Social Profile</h2> <p>Get a single social profile by Id.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/credential/003-001000000000000-10795428XXXXXXXXX</code></pre> <h3>Example Result</h3> <pre><code>{ "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 } }</code></pre> <h2>List Social Profiles</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/credential?network=Twitter?includeInvalid=0</code></pre> <h3>Parameters</h3> <p>Results can be filtered by <strong>network</strong>. Acceptable values are: LinkedIn, Twitter, Youtube, Instagram and Facebook.</p> <table> <tbody> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> <tr> <td>network</td> <td>-</td> <td> Optional. Acceptable values are: LinkedIn, Twitter, Youtube, Instagram and Facebook. </td> </tr> <tr> <td>includeInvalid</td> <td>0</td> <td>Optional. If set to 1, the response will include invalid credentials.</td> </tr> </tbody> </table> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Update a Social Profile</h2> <p>Update a single social profile by Id.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/credential/003-001000000000000-10795428XXXXXXXXX -X PUT \ -d displayName="Oktopost Twitter" \ -d nativePostsEnabled=1</code></pre> <h3>Example Response</h3> <pre><code>{ "Result": true, "Credential": {...} }</code></pre> <h2>Delete a Social Profile</h2> <p class="note">Note that deleting a profile will delete all scheduled posts using it.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/credential/003-001000000000000-10795428XXXXXXXXX -X DELETE</code></pre><h1>Streams</h1> <p>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.</p> <h2>List Streams</h2> <p>Order by position or created</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/stream \ -d position=420</code></pre> <h3>Example Response</h3> <pre><code>{ "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 } ] }</code></pre> <h2>Add Stream</h2> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Description</th> </tr> <tr> <td>network</td> <td>Facebook, Twitter, LinkedIn, or Instagram.</td> </tr> <tr> <td>credentialId</td> <td>The <a href="#social-profiles">social profile</a> Id.</td> </tr> <tr> <td>type</td> <td>The stream type, see acceptable values below.</td> </tr> <tr> <td>keyword</td> <td>The search term.</td> </tr> </tbody> </table> <h3>Twitter Streams</h3> <table> <tbody> <tr> <th>Type</th> <th>Description</th> </tr> <tr> <td>mention</td> <td>Metions of a connected Twitter handle.</td> </tr> <tr> <td>retweet</td> <td>Tweets that users retweeted.</td> </tr> <tr> <td>feed</td> <td>Tweets by a connected Twitter handle.</td> </tr> <tr> <td>keyword</td> <td>A feed that searches Twitter for keywords.</td> </tr> <tr> <td>list</td> <td>A feed with all the tweets by handles on a Twitter List.</td> </tr> <tr> <td>favorite</td> <td>Tweets that users liked.</td> </tr> <tr> <td>home</td> <td>The home feed of a connected Twitter handle.</td> </tr> <tr> <td>user</td> <td>A feed with tweets by any Twitter handle.</td> </tr> </tbody> </table> <h3>Instagram Streams</h3> <table> <tbody> <tr> <th>Type</th> <th>Description</th> </tr> <tr> <td>page</td> <td>Posts from a connected Instagram page.</td> </tr> <tr> <td>page.tags</td> <td>Posts containing a specific hashtag.</td> </tr> </tbody> </table> <h3>Facebook Streams</h3> <table> <tbody> <tr> <th>Type</th> <th>Description</th> </tr> <tr> <td>ownpage</td> <td>Posts from a connected Facebook page.</td> </tr> <tr> <td>tag</td> <td>Posts that mention a connected Facebook page.</td> </tr> </tbody> </table> <h3>LinkedIn Streams</h3> <table> <tbody> <tr> <th>Type</th> <th>Description</th> </tr> <tr> <td>page</td> <td>Posts from a connected LinkedIn page.</td> </tr> </tbody> </table> <h3>Example Request</h3> <p>Create a stream with mentions of a connected Twitter handle.</p> <pre><code>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=-2</code></pre> <p>Create a stream that searches Twitter for specific terms or keywords. <a href="https://web.archive.org/web/20210421053928/https://help.oktopost.com/en/articles/48-twitter-search-stream">See search options</a>.</p> <pre><code>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=2</code></pre> <h3>Example Result</h3> <pre><code>{ "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 } }</code></pre> <h2>Remove Stream</h2> <pre><code>curl -i https://api.oktopost.com/v2/stream/00F000000000001 -X DELETE</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true }</code></pre> <h2>Update Stream Position</h2> <pre><code>curl -i https://api.oktopost.com/v2/stream/01800000000000 -X POST \ -d position=420</code></pre> <h3>Example Result</h3> <pre><code>{ "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 } }</code></pre><h1>Stream Tabs</h1> <p>Streams are organized using tabs. With this endpoint you can list, create, delete and update stream tabs.</p> <h2>List Stream Tabs</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/stream-tab</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Items": [ { "Id": "018000000000000", "Name": "Twitter Stream", "Status": "active", "Created": "2020-11-18 15:00:06" } ], "Total": 1 } ## Get Stream Tab ### Example Request </code></pre> <p>curl -i <a href="https://web.archive.org/web/20210421053928/https://api.oktopost.com/v2/stream-tab/018000000000000">https://api.oktopost.com/v2/stream-tab/018000000000000</a></p> <pre><code> ### Example Result </code></pre> <p>{ "Result": true, "StreamTab": { "Id": "018000000000000", "Name": "Twitter Stream", "Status": "active", "Created": "2020-11-18 15:00:06" } }</p> <pre><code> ## Add Stream Tab ### Example Request </code></pre> <p>curl -i <a href="https://web.archive.org/web/20210421053928/https://api.oktopost.com/v2/stream-tab">https://api.oktopost.com/v2/stream-tab</a> -X POST \ -d name="Twitter Engagement"</p> <pre><code> ### Example Result </code></pre> <p>{ "Result": true, "StreamTab": { "Id": "018000000000000", "Name": "Twitter Engagement", "Status": "active", "Created": "2020-11-15 13:23:34" } }</p> <pre><code> ## Edit Stream Tab ### Example Request </code></pre> <p>curl -i <a href="https://web.archive.org/web/20210421053928/https://api.oktopost.com/v2/stream-tab/018000000000000">https://api.oktopost.com/v2/stream-tab/018000000000000</a> -X POST \ -d name="Twitter Disengagement"</p> <pre><code> ### Example Result </code></pre> <p>{ "Result": true, "StreamTab": { "Id": "018000000000000", "Name": "Twitter Disengagement", "Status": "active", "Created": "2020-11-15 13:23:34" } }</p> <pre><code> ## Remove Stream Tab ### Example Request </code></pre> <p>curl -i <a href="https://web.archive.org/web/20210421053928/https://api.oktopost.com/v2/stream-tab/018000000000000">https://api.oktopost.com/v2/stream-tab/018000000000000</a> -X DELETE</p> <pre><code></code></pre><h1>Tags</h1> <p>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.</p> <h2>List Tags</h2> <h3>Input</h3> <ul> <li><strong>_order</strong> <em>(Optional)</em> Accepted values: tag, created, lastUsed</li> <li><strong>_page</strong> <em>(Optional)</em> </li> <li><strong>_count</strong> <em>(Optional)</em> </li> </ul> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/tag</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Get Tag</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/tag/0AF000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Tag":{ "Id": "0AF000000000001", "Created": "2020-11-03 08:35:30", "Tag": "Hello", "LastUsedDate": "2020-11-03 08:48:34" } }</code></pre> <h2>Add Tag</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/tag -X POST \ -d tag="Tag Name"</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Tag":{ "Id": "0AF000000000001", "Created": "2020-11-03 08:35:30", "Tag": "Tag Name", "LastUsedDate": "2020-11-03 08:48:34" } }</code></pre> <h2>Update Tag</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/tag/0AF000000000001 -X POST \ -d tag="My Tag"</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Tag":{ "Id": "0AF000000000001", "Created": "2020-11-03 08:35:30", "Tag": "Tag Name", "LastUsedDate": "2020-11-03 08:48:34" } }</code></pre> <h2>Delete Tag</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/tag/0AF000000000001 -X DELETE</code></pre><h1>Teams</h1> <p>The following endpoint can be used to read, create, update and delete teams.</p> <h2>Get Team</h2> <p>Get a single team by Id.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/team/025000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Team":{ "Id":"025000000000000", "Created":"2019-09-24 22:11:36", "Modified":"2019-09-24 22:11:40", "Name":"US East" } }</code></pre> <h2>List Teams</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/team</code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true, "Items":[ { "Id":"025000000000000", "Created":"2019-09-24 22:11:36", "Modified":"2019-09-24 22:11:40", "Name":"US East" }, ... ], "Total":193 }</code></pre> <h2>Create Team</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/team -X POST \ -d name="US West" </code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true, "Team":{ "Id":"025000000000000", "Created":"2020-04-24 12:11:36", "Modified":"2020-04-24 12:11:40", "Name":"US West" } }</code></pre> <h2>Update Team</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/team/025000000000000 -X POST \ -d name="US South" </code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true, "Team":{ "Id":"025000000000000", "Created":"2020-04-24 12:11:36", "Modified":"2020-04-24 12:12:59", "Name":"US South" } }</code></pre> <h2>Delete Team</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/team/025000000000000 -X DELETE</code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true }</code></pre><h1>Team Entities</h1> <p>The following endpoint can be used to add and remove entities from teams. Currently team bound entities are: Campaign, User, Advocacy Board and Workflows.</p> <h2>List Teams</h2> <p>Get all teams for a single team-bound entity. This endpoint is limited to 1000 elements and no pagination is available.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/team/025000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Items": [ { "Id":"025000000000000", "Created":"2019-09-24 22:11:36", "Modified":"2019-09-24 22:11:40", "Name":"US East" }, ... ] }</code></pre> <h2>Add Teams to an Entity</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/team-entity/002000000000000 -X POST \ -d teamIds=025000000000000,025000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true }</code></pre> <h2>Remove Teams from an Entity</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/team/025000000000000 -X DELETE \ -d teamIds=025000000000000,025000000000001 </code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true }</code></pre><h1>Token Login</h1> <p>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. </p> <h2>How it Works</h2> <img src="/web/20210421053928im_/https://www.oktopost.com/images/api/application-auth-login.png" alt="token auth process"> <h2>Obtaining the Login Token</h2> <p>To obtain the token, you must make an <a href="#authentication">authenticated request</a> to the endpoint below and include your application's <strong>privateKey</strong>.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/auth-token?privateKey=[KEY]</code></pre> <h3>Example Result</h3> <pre><code>{ "Result":true, "Token":"574dac5e6bcb31.23085498b3fc1c5d3398cca07bb31e5729d3a32f" }</code></pre> <p class="note">Note that the <b>privateKey</b> is available only for authorized applications. If you wish to use this endpoint, please contact us.</p> <h2>Final Redirect</h2> <p>Once the token has been obtained, the user has to be redirected to the following URL:</p> <h3>Example Redirect</h3> <pre><code>https://app.oktopost.com/auth/token/id/[TOKEN]</code></pre> <p>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 <strong>_redirect</strong> parameter to the URL with the desired path, as such:</p> <h3>Example Redirect With Followup URL</h3> <pre><code>https://app.oktopost.com/auth/token/id/[TOKEN]?_redirect=/calendar</code></pre><h1>Users</h1> <p>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. </p> <h2>Get User</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/user/00A000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <h2>List Users</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/user</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Create User</h2> <h3>Example Request</h3> <pre><code>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"</code></pre> <h3>Roles</h3> <p>The following roles can be applied when creating a new user.</p> <table> <tbody> <tr> <th>Role</th> <th>Description</th> </tr> <tr> <td>admin</td> <td>Can manage all functions</td> </tr> <tr> <td>publisher</td> <td>Can manage all functions besides account administration</td> </tr> <tr> <td>contributor</td> <td>Has the same privileges as publisher besides approving posts</td> </tr> <tr> <td>read</td> <td>Read only</td> </tr> </tbody> </table> <h2>Update User</h2> <h3>Example Request</h3> <pre><code>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"</code></pre> <p>Both create and update actions will return a similar response to the GET endpoint.</p> <h2>Delete User</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/user/00A000000000000 -X DELETE</code></pre><h1>User Notifications</h1> <p>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.</p> <h2>List Notifications</h2> <p>This endpoint will list the authenticated user's email notification settings.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/notification</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Items": { "EmailDaily": false, "EmailWeekly": true, "EmailCampaignComplete": false, "EmailOnNewAssignment": true, "EmailOnNoteAdded": true, "EmailOnNoteMention": true, "EmailOnStatusChange": true, "SendDailyEmailReport": true } }</code></pre> <h2>Update Notifications</h2> <h3>Example Request</h3> <pre><code>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</code></pre> <p>Note that it is possible to send one or more settings in a single update request.</p><h1>Webhooks</h1> <p>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. </p> <h2>List Webhooks</h2> <h3>Parameters</h3> <table> <thead> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>_order</td> <td>name</td> <td>Options are: name, description, lastExecutionDate, isEnabled, created, modified</td> </tr> <tr> <td>_page</td> <td>0</td> <td>Current page</td> </tr> <tr> <td>_count</td> <td>20</td> <td>Options: 20, 25, 50 and 100</td> </tr> <tr> <td>event</td> <td>-</td> <td>See <b>Supported Event Types</b> below</td> </tr> <tr> <td>name</td> <td>-</td> <td>Search by name</td> </tr> </tbody> </table> <h3>Supported Event Types</h3> <p>The following event types can be used to list, create and update webhooks.</p> <table> <thead> <tr> <th>Param</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>newAdvocacyMessage</td> <td>Triggers when a new message is added to the board</td> </tr> <tr> <td>newAdvocacyTopic</td> <td>Triggers when a new topic is added to the board</td> </tr> <tr> <td>newConversion</td> <td>Triggers when a social conversion is captured</td> </tr> <tr> <td>postSent</td> <td>Triggers when a post is sent to social media</td> </tr> <tr> <td>newNoteOnConversation</td> <td>Triggers when a new note is added to a conversation</td> </tr> <tr> <td>newConversation</td> <td>Triggers when a new conversation is available in your inbox</td> </tr> <tr> <td>conversationUpdated</td> <td>Triggers when a new comment or reply are available on existing conversation</td> </tr> <tr> <td>newAssignment</td> <td>Triggers when a conversation is assigned to a new user</td> </tr> <tr> <td>conversationStatusUpdated</td> <td>Triggers when a conversation status is updated</td> </tr> <tr> <td>newLead</td> <td>Triggers when a new lead is captured</td> </tr> <tr> <td>newLeadActivity</td> <td>Triggers when a new social activity is detected</td> </tr> <tr> <td>newCampaign</td> <td>Triggers when a new campaign is created</td> </tr> <tr> <td>postCreated</td> <td>Triggers when a user creates a new post</td> </tr> <tr> <td>postModified</td> <td>Triggers when a user updates a scheduled post</td> </tr> <tr> <td>postDeleted</td> <td>Triggers when a user deletes a scheduled post</td> </tr> <tr> <td>newApprovalItem</td> <td>Triggers when a posts and messages are sent to approval</td> </tr> <tr> <td>approvalItemApproved</td> <td>Triggers when a posts and messages are approved</td> </tr> <tr> <td>approvalItemRejected</td> <td>Triggers when a posts and messages are rejected</td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/webhook</code></pre> <h3>Example Result</h3> <pre><code>{ "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 }</code></pre> <h2>Get Webhook</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/webhook/0WA000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <h2>Add Webhook</h2> <h3>Example Request</h3> <pre><code>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</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <h2>Update Webhook</h2> <h3>Example Request</h3> <pre><code>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</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } }</code></pre> <h2>Delete Webhook</h2> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/webhook/0WA000000000001 -X DELETE</code></pre><h1>Webhooks Log</h1> <p>The Webhook Log stores events from Oktopost's Webhooks. The following endpoint can be used to list all recent events by a webhook Id. </p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/webhook-log/0WA000000000001</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Items": [ { "Id": "0WC000000000001", "WebhookPayloadId": "0WB000000000001", "Created": "2017-05-23 14:07:18", "ResponseCode": 200, "ExecutionTime": 0.034530, "Payload": {} } ], "Total": 1 }</code></pre><h1>Workflow</h1> <p>With Oktopost, you can easily set up one or multi-step approval processes, called <a href="https://web.archive.org/web/20210421053928/https://help.oktopost.com/en/articles/5-setting-up-approval-workflows" target="_blank">workflows</a>. This endpoint allows you to get the workflows available in your account.</p> <h2>Get Workflow</h2> <p>Get a single workflow by ID. </p> <h3>Input</h3> <ul> <li><strong>withSteps</strong> <em>(Optional)</em> Set to <strong>1</strong> to include the workflow's steps in the response.</li> </ul> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/workflow/cwf000000000000?withSteps=1</code></pre> <h3>Example Result</h3> <pre><code>{ "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": [] } ] }</code></pre> <h2>List Workflows</h2> <p>List all workflows in your account. Note that pagination for this endpoint is disabled.</p> <h3>Input</h3> <ul> <li><strong>withSteps</strong> <em>(Optional)</em> Set to <strong>1</strong> to include the workflow's steps in the response.</li> </ul> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/workflow?withSteps=1</code></pre> <h3>Example Result</h3> <pre><code>{ "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": [] } ] } ] }</code></pre><h1>Workflow Item</h1> <p>Workflow items are <strong>Posts</strong> and <strong>Messages</strong> 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.</p> <h2>List Items</h2> <p>List messages and posts in your workflows.</p> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> <tr> <td>page</td> <td>0</td> <td>The current page</td> </tr> <tr> <td>count</td> <td>20</td> <td>The number of results per page. From 1 to 1000 maximum.</td> </tr> <tr> <td>stepId</td> <td>-</td> <td> Optional. Return the items in this step only </td> </tr> <tr> <td>workflowId</td> <td>-</td> <td> Optional. Return the items in this workflow only </td> </tr> <tr> <td>withHistory</td> <td>0</td> <td>Optional. If set to 1, return the history information for each item.</td> </tr> <tr> <td>withAuthors</td> <td>0</td> <td> Optional. If set to 1, an additional object under the key <b>Authors</b> is returned. This object will contain all of the users present in the <b>CreatedBy</b> field of each item. </td> </tr> <tr> <td>withSteps</td> <td>0</td> <td> Otional. If set to 1, all of the steps for the requested items are added to the response under <b>Steps</b>. </td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/workflow-item</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } ] } } }</code></pre> <h2>Sending items to approval</h2> <p>Use this endpoint to send a message or post to approval. The <strong>entityId</strong> parameter can be either a <strong>Message</strong> or <strong>Post</strong> ID.</p> <h3>Example Request</h3> <pre><code>curl -i http://api.oktopost.com/v2/workflow-item -X POST \ -d entityId=005000000000000 \ -d workflowId=cwf000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Data": { "Id": "cwi000000000000", "CreatedBy": "00Aeh4wb9by9whl", "Status": "pending", "StepId": "cws000000000000", "WorkflowId": "cwf000000000000", "MessageId": "005000000000000" } }</code></pre> <h2>Approving and rejecting items</h2> <p>Use this endpoint to approve or request revisions for items that are pending approval.</p> <h3>Parameters</h3> <table> <tbody> <tr> <th>Param</th> <th>Default</th> <th>Description</th> </tr> <tr> <td>note</td> <td>-</td> <td>Add a text note to the approve or reject action</td> </tr> <tr> <td>isApprove</td> <td>0</td> <td>Set to 1 to approve the item and to 0 to reject it</td> </tr> <tr> <td>stepId</td> <td>-</td> <td> 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. </td> </tr> </tbody> </table> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/workflow-item/005000000000000 -X POST \ -d note="Looks good!!!" \ -d isApprove=1 \ -d stepId=cws000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true, "Data": { "Id": "cwi000000000000", "CreatedBy": "00Aeh4wb9by9whl", "Status": "pending", "StepId": "cws000000000000", "WorkflowId": "cwf000000000000", "MessageId": "005000000000000" } }</code></pre> <h2>Removing items from the workflow</h2> <p>Removing posts and messages from the workflow will revert them to <strong>Drafts</strong>.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/workflow-item/005000000000000 -X DELETE</code></pre> <h3>Example Result</h3> <pre><code>{ "Result": true }</code></pre><h1>Workflow Step</h1> <p>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. </p> <h2>Get Workflow Step</h2> <p>Get a single workflow step by ID.</p> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/workflow-step/cwskempkanbh37g</code></pre> <h3>Example Result</h3> <pre><code>{ "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" } ] }</code></pre> <h2>List Steps</h2> <p>List all steps in the account or a specific workflow.</p> <ul> <li><strong>workflowId</strong> <em>(Optional)</em></li> </ul> <h3>Example Request</h3> <pre><code>curl -i https://api.oktopost.com/v2/workflow-step?workflowId=cwf000000000000</code></pre> <h3>Example Result</h3> <pre><code>{ "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": [] } ] }</code></pre> <hr> <div> <a href="/web/20210421053928/https://www.oktopost.com/" class="page-footer__link page-footer__link--dark">© 2021 Oktopost</a> <a href="/web/20210421053928/https://www.oktopost.com/privacy" class="page-footer__link page-footer__link--dark">Privacy Policy</a> <a href="/web/20210421053928/https://www.oktopost.com/terms" class="page-footer__link page-footer__link--dark">Terms & Conditions</a> </div> </div> </div> </main> <script src="https://web.archive.org/web/20210421053928js_/https://app-ab21.marketo.com/js/forms2/js/forms2.min.js" type="text/javascript"></script> <script src="/web/20210421053928js_/https://www.oktopost.com/dist/js/vendor.min.js?eb8." type="text/javascript"></script> <script src="/web/20210421053928js_/https://www.oktopost.com/dist/vendor/highlight.pack.min.js?eb8." type="text/javascript"></script> <script src="/web/20210421053928js_/https://www.oktopost.com/dist/vendor/wpp-4.1.0.min.js?eb8." type="text/javascript"></script> <script src="/web/20210421053928js_/https://www.oktopost.com/dist/js/views.min.js?eb8." type="text/javascript"></script> <script src="/web/20210421053928js_/https://www.oktopost.com/dist/js/app.min.js?eb8." type="text/javascript"></script> <script> Oktopost.Config.StartupData.set({"uploads":{"originals":"https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/cdn-www.oktopost.com\/uploads\/web\/originals","cards":"https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/cdn-www.oktopost.com\/uploads\/web\/generated\/w450,h300,fcrop,q80"},"cdnURL":"https:\/\/web.archive.org\/web\/20210421053928\/https:\/\/cdn-www.oktopost.com","environment":"production"}); Oktopost.Boot.launch(); </script> </body> </html>

CINXE.COM

Oktopost API Reference