A social media scheduler needs more than a calendar and a publish button. It needs connected accounts, durable media URLs, a queued publishing job, and a way to distinguish one successful destination from another that failed.
Outstand provides the connection and publishing API. Your application owns the calendar, customer permissions, and recovery experience. This guide follows a post from account connection to delivery, with the checks that keep an accepted API request from being mistaken for a published post.
1. Connect accounts from your backend
Generate an API key in the Outstand dashboard and send it as Authorization: Bearer YOUR_API_KEY. Keep that key on your server, not in browser code. See authentication and organization permissions for access controls. Creating a post through the REST API requires both posts:create and posts:publish.
Choose the credential setup for each network before connecting customers. Managed Keys let you use Outstand's OAuth application on supported networks. X, Google Business Profile, Vimeo, and Reddit require your own app credentials. Bluesky connects with an app password instead of OAuth. The configuration guides cover these differences.
For an OAuth connection, request an authorization URL:
1curl https://api.outstand.so/v1/social-networks/linkedin/auth-url \
2 -H 'Authorization: Bearer YOUR_API_KEY' \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "redirect_uri": "https://yourapp.example/social/connected",
6 "tenant_id": "customer_123"
7 }'Read the URL from data.auth_url in the { "success": true, "data": { ... } } response, then redirect the customer there. Here, redirect_uri is your application's final destination, not the callback URL registered with the social platform.
Do not assume every network returns the same callback parameters. LinkedIn and Facebook return a pending session token because the customer still needs to choose profiles or pages. From your backend, retrieve the choices with GET /v1/social-accounts/pending/{sessionToken}, then finalize the selection:
1curl https://api.outstand.so/v1/social-accounts/pending/SESSION_TOKEN/finalize \
2 -H 'Authorization: Bearer YOUR_API_KEY' \
3 -H 'Content-Type: application/json' \
4 -d '{"selectedPageIds":["SELECTED_PROVIDER_PAGE_ID"]}'The finalization response contains connectedAccounts, each with an Outstand id. Google Business Profile also has a location-selection step, but currently uses its own dashboard finalization route rather than this generic REST finalizer. Other OAuth networks can create the account before returning, although not all include its ID on the redirect. Follow the connection contracts and pending connection reference rather than treating a redirect alone as a completed connection.
2. Store account IDs, not network names
List connected accounts after connection:
1curl 'https://api.outstand.so/v1/social-accounts?tenantId=customer_123' \
2 -H 'Authorization: Bearer YOUR_API_KEY'The account list is in data, alongside pagination fields including total, limit, and offset. Paginate when necessary. Persist each returned id, network, username, and your own customer association.
The accounts field on a post takes connected account IDs or exact usernames. Prefer IDs: they identify a particular connection without relying on a handle that can change or overlap across networks. "linkedin" and "x" are network names, not destination selectors. Never construct an account ID yourself.
There is an important validation edge case: if none of the identifiers resolve, creation returns 400; if some resolve, unmatched entries can be silently dropped. Compare the returned post.socialAccounts IDs with your intended destination set. Also authorize those IDs against the current customer in your own backend. A tenant filter helps retrieve the right accounts, but does not replace your application's authorization checks.
3. Upload and confirm media before scheduling
Skip this step for a text-only post. Otherwise, request an upload URL:
1curl https://api.outstand.so/v1/media/upload \
2 -H 'Authorization: Bearer YOUR_API_KEY' \
3 -H 'Content-Type: application/json' \
4 -d '{"filename":"launch.jpg","content_type":"image/jpeg"}'The response uses success and data; save data.id and data.upload_url. The upload URL expires after one hour. Upload the bytes directly, then confirm through the authenticated API:
1curl -X PUT 'PASTE_UPLOAD_URL_HERE' \
2 -H 'Content-Type: image/jpeg' --data-binary @launch.jpg
3
4curl -X POST https://api.outstand.so/v1/media/MEDIA_ID/confirm \
5 -H 'Authorization: Bearer YOUR_API_KEY' \
6 -H 'Content-Type: application/json' \
7 -d '{}'Read the public file URL from the confirmation response's data.url. Attach that URL and a clean filename to a post container. Do not pass a mediaIds field: that is not the attachment format.
Media must remain publicly reachable over HTTPS, without authentication, at publishing time. A URL that works when the customer saves a post can still expire before delivery. Outstand uploads have a 60-day retention period; track the returned expires_at, especially if your calendar stores older assets. See media upload.
For video, optional processMedia: true requests per-network processing and requires media:process. Processing is not a promise that any source file will satisfy every platform. Check the relevant network's requirements and inspect response warnings. Leave it out of a basic image integration.
4. Create the scheduled post and confirm it is queued
Convert the customer's chosen local time to UTC and send scheduledAt as an ISO 8601 timestamp with Z. The API rejects dates more than 30 days ahead. For a longer calendar, keep future entries in your own database until they enter that window.
This server-side JavaScript example schedules an image post one hour ahead. Replace the account and media placeholders with values returned by the API:
1const scheduledAt = new Date(Date.now() + 60 * 60 * 1000).toISOString();
2// Persist this body and key before sending; reuse both on transport retries.
3const idempotencyKey = 'schedule-entry-123-v1';
4const body = {
5 accounts: ['OUTSTAND_ACCOUNT_ID'],
6 containers: [{
7 content: 'Our launch is live.',
8 media: [{ url: 'PUBLIC_CONFIRMED_MEDIA_URL', filename: 'launch.jpg' }],
9 }],
10 scheduledAt,
11};
12const response = await fetch('https://api.outstand.so/v1/posts', {
13 method: 'POST',
14 headers: {
15 Authorization: `Bearer ${process.env.OUTSTAND_API_KEY}`,
16 'Content-Type': 'application/json',
17 'Idempotency-Key': idempotencyKey,
18 },
19 body: JSON.stringify(body),
20});
21const result = await response.json();
22if (!response.ok || !result.success) {
23 throw new Error(result.error || `Outstand returned ${response.status}`);
24}
25console.log(result.post.id, result.post.scheduled, result.warnings);The response envelope is { success, post }, not { data: post }. Store post.id and check post.scheduled. A timestamp alone does not prove a publishing job exists.
If queue creation fails after the post is saved, the API returns 202 with success: true, scheduled: false, an error message, and the saved post. Do not create another post blindly. Recover the existing one by sending PATCH /v1/posts/{id} with a new scheduledAt, then check the scheduling result again.
Omit scheduledAt for immediate queued publishing. To reschedule an unpublished post, patch its timestamp. To cancel, use DELETE /v1/posts/{id}. Once any destination has published, editing or rescheduling is rejected with 409; target accounts are not editable either. See create, update, and cancel.
Platform-specific options belong in top-level blocks such as linkedin or instagram. A network's content override changes its root text, not shared media or thread replies. Check warnings for unrecognized request keys rather than assuming an ignored option worked.
5. Treat delivery as a per-account result
Creation accepts work; it does not confirm publication. Read GET /v1/posts/{id}, whose response also contains success and post.
Each entry in post.socialAccounts has status (pending, published, or failed), error, platformPostId, and publishedAt. The post-level publishedAt is set on the first successful destination. It therefore does not mean every destination succeeded.
Keep a row for each post-account pair in your database. Your UI can then show “LinkedIn published, Instagram failed” instead of a misleading green check for the entire post. Store native platform IDs and URLs when available. Use post details to reconcile outcomes when a webhook is missing or your receiver was unavailable.
Separate three recovery paths:
- API request retry: for a transport timeout or retryable API response, retry the same saved body with the same idempotency key. Back off and honor
Retry-Afterwhen supplied, including for API rate limits. - Saved but not queued: repair the existing post's schedule rather than submitting another create request.
- Destination failure: read the per-account error, correct credentials, permissions, media, or quota issues, and deliberately retry only the failed destinations with a new post. Do not resend successful accounts.
The publishing worker records caught platform failures on the affected account and continues to the next destination. Do not assume every failed platform call is automatically retried. Queue-level retries are a separate mechanism, not a blanket guarantee of eventual delivery or exactly-once publishing.
If an error leaves it unclear whether a network accepted the post, inspect the destination before retrying. A timeout after platform acceptance can be ambiguous; a new create request cannot undo an already-live post.
Idempotency protects creation for 24 hours, scoped to your organization and endpoint. A replay includes Idempotency-Replayed: true. Reusing a key with a different body returns 422; an identical request still in progress returns 409 with Retry-After. Persist the timestamp too: recalculating “one hour from now” on retry changes the body. This protection does not deduplicate a deliberately new publishing attempt on a social network.
6. Verify signed webhooks before updating your calendar
Configure an HTTPS endpoint and signing secret in Settings > Webhooks. Subscribe to post.published, post.error, and account.token_expired for scheduler feedback.
post.published means at least one destination succeeded. post.error means none succeeded in that publishing run. Both carry event, timestamp, and data, with data.postId and data.socialAccounts. Successful account results contain native post details; failures contain error. A published event can therefore include failures too. Token-expiration events should prompt a reconnection flow, not another unchanged publishing attempt.
Outstand signs the exact JSON request body with HMAC-SHA256. The header is X-Outstand-Signature: sha256=<lowercase hex digest>. Verify raw bytes before parsing JSON, not a reserialized req.body:
1import { createHmac, timingSafeEqual } from 'node:crypto';
2
3export function verifyOutstandWebhook(rawBody, signature, secret) {
4 if (typeof signature !== 'string' || !/^sha256=[0-9a-f]{64}$/.test(signature)) {
5 return false;
6 }
7 const expected = createHmac('sha256', secret).update(rawBody).digest();
8 const received = Buffer.from(signature.slice(7), 'hex');
9 return received.length === expected.length && timingSafeEqual(received, expected);
10}Pass your HTTP server's unmodified body buffer, the signature header, and your configured secret. Reject invalid signatures. For valid events, durably enqueue processing before returning 2xx; acknowledging first and keeping work only in memory risks losing it.
Handle duplicates with an inbox record and idempotent per-account updates. The payload timestamp is signed as part of the body, but the signature header has no separate freshness value. Signature verification alone does not prevent replay. Use the payload timestamp and your stored delivery history as part of your policy. See the webhook reference for event schemas.
The resulting scheduler has clear boundaries: your calendar records intent, post.scheduled confirms queued work, per-account results describe delivery, and verified webhooks keep your application synchronized. Build around those distinctions rather than equating a successful create request with a successful social post.