Skip to content

Social Media API for Marketing Agencies: Multi-Client Publishing, Scheduling, and Analytics

A social media API for marketing agencies needs to do more than publish a single post.

Post for a client: POST /v1/posts contract example
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "instagram", "accountId": "client_a_ig" },
      { "platform": "facebook", "accountId": "client_a_fb" },
      { "platform": "pinterest", "accountId": "client_a_pin" }
    ]
  }'
Illustrative request
Example line 1

curl -X POST {{API_BASE_URL}}/v1/posts \

Illustrative request
Example line 2

-H "x-access-key: your-api-key" \

Illustrative request
Example line 3

-H "Content-Type: application/json" \

Agencies manage many client accounts across different platforms, need to keep each client's credentials and history separate, and need a clear path from draft to approval to publishing to reporting. This guide explains how one integration can support that workflow: connect isolated client accounts, use cross-platform posting for a single client request, separate approval and scheduling from the final publish step, and pull per-client analytics for reporting. It also preserves the exact request contract for posting to a client so a team can evaluate the field mapping before implementation.

Agency-scale multi-client publishing task

Marketing agencies rarely manage one social presence. A single agency may handle dozens of client accounts, each with its own profiles on Twitter, Instagram, YouTube, TikTok, Facebook, Threads, and Pinterest. The operational problem is not only volume. It is separation: the right content must go to the right client, on the right platform, under the right account, and the resulting performance data must be attributable to that client rather than blended into an agency-wide total.

A useful agency workflow therefore starts with multi-account management. Each client account should be connected and managed independently, with its own credentials and posting history. That isolation is the control that prevents the most damaging agency error: publishing client A's announcement to client B's audience. When account identity is explicit in every request, the team can audit what was sent, where it was sent, and for whom.

The second part of the task is cross-platform posting. Instead of maintaining a separate integration for every social platform, the agency builds one request shape and varies the targets inside it. For a given client, one piece of content can be directed to several connected accounts at once. The agency still decides which platforms are appropriate for that client and that message; the API simply removes the need to repeat the same publishing logic platform by platform.

Workflow map: connect, draft, approve, publish, report

A practical agency workflow has five stages. First, connect each client's social accounts and keep them isolated. Second, draft content once and map it to the correct platform and account targets for that client. Third, route the draft through Approval & Scheduling Workflows so a reviewer can approve, edit, or hold it before anything is published. Fourth, publish programmatically after approval, using one request per client. Fifth, collect per-client analytics so each client report reflects only that client's accounts and platforms.

This sequence matters because approval and publishing are different decisions. Scheduling for review is not the same as publishing. A team should be able to prepare content in advance, let the client or an internal approver check it, and only then trigger the publish request. Building that approval flow around the API, rather than hard-coding it into a single platform's dashboard, lets the agency apply the same review standard to every client.

API contract sheet: posting to a client

Posting to a client uses a POST request to /v1/posts. Authentication is supplied through the x-access-key header. The JSON body contains a content field and a platforms field. The platforms field is a list of targets, and each target contains a platform field and an accountId field. In the worked example, one client is published to Instagram, Facebook, and Pinterest by listing three targets, each pairing a platform name with that client's accountId for the platform.

Use the field names exactly as shown. The accountId ties a target to a specific connected client account, while the platform identifies which social platform that account belongs to. Keeping those two fields separate makes multi-client publishing auditable: a reviewer can read the request and see that a particular piece of content was intended for a particular client's Instagram account, a particular client's Facebook account, and a particular client's Pinterest account, rather than for an ambiguous agency account.

Worked example: one client, three platforms

The worked example in the code section titled Post for a client shows the full request for one client. The content announces a summer collection. The platforms list contains three entries: instagram with accountId client_a_ig, facebook with accountId client_a_fb, and pinterest with accountId client_a_pin. The request uses the x-access-key header for authentication and sends the body as JSON.

To adapt this pattern to another client, keep the same structure and change only the client-specific values. Replace the content with that client's message, and replace each accountId with the connected account identifier for that client on the relevant platform. Do not reuse another client's accountId values. Before sending, check that every target belongs to the same client, that the platform name matches the account, and that the content is appropriate for each platform in the list. That pre-send check is the main safeguard against cross-client mistakes.

Decision criteria for agency workflows

When evaluating an agency publishing setup, use four decision criteria. Account isolation asks whether each client's credentials and posting history are kept separate, so one client's activity cannot leak into another's. Cross-platform publishing asks whether one request per client can target multiple platforms through the platforms list. Approval and scheduling separation asks whether content can be prepared and reviewed before the publish request is sent. Per-client analytics asks whether engagement data can be pulled per account and per platform, so reports can be generated from real performance data for each client rather than from blended totals.

Additional criteria include whether the team can schedule content for multiple clients without adding integration complexity for each new client, and whether API keys can be shared across a team for collaborative workflows. Confirm how accounts are connected, how keys are issued and revoked, and how analytics are retrieved before committing client work to the integration.

Failure matrix and checks before publishing

Several failure cases should be checked before a client campaign depends on this workflow. A missing x-access-key header should be treated as an authentication failure and blocked before any publish attempt. Missing content should be caught during request preparation, because there is nothing meaningful to publish without it. An empty platforms list should also be caught before sending, since a request with no targets cannot reach any client account. An unknown platform value or an unknown accountId should be validated against the connected accounts for that client before the request is sent.

Partial multi-platform failure is the most important case to design for. When one request targets several platforms, the team needs to know what happens if one target succeeds and another fails. Record the exact request sent for each client, check the result for every target, and retry only the targets that did not succeed. Do not assume that a single response means every platform published, and do not resend the whole list blindly, because that could duplicate posts on the platforms that already succeeded.

Implementation checklist

Use a local checklist before implementation. Confirm the API base URL to use with the unchanged /v1/posts path. Confirm how x-access-key values are issued, stored, and rotated for the agency team. Build a mapping table for each client that lists every connected account, its platform, and its accountId, and verify that no accountId is shared between clients. Prepare the request builder so content, platforms, platform, and accountId are always populated from that mapping rather than typed by hand. Add a pre-send validation step that rejects missing content, an empty platforms list, unknown platform values, and accountId values that do not belong to the selected client.

Keep the approval step as a separate state from publishing, so scheduled or drafted content cannot be published until it is approved. Collect per-client analytics so results are stored by client, account, and platform. Verify the actual response and error behavior for successful, partially successful, and failed multi-platform requests, and record those findings before relying on the workflow for client campaigns.

POST /v1/posts request field map
Field or headerLocationType as shownRequiredness as shownPurpose
x-access-keyHeaderstring (example value)Present in example requestAuthentication for the request
contentJSON bodystringPresent in example requestPost content to publish
platformsJSON bodyarray of objectsPresent in example requestList of platform/account targets for the post
platformInside each platforms entrystringPresent in example requestSocial platform for that target, e.g. instagram, facebook, pinterest
accountIdInside each platforms entrystringPresent in example requestIdentifier of the client's connected account on that platform

Requiredness reflects presence in the example request shown on this page.

Failure matrix for multi-client posting
Failure casePre-send checkWhat to verify during implementation
Missing x-access-keyReject the request before sending; confirm key is configuredAuthentication error response and status
Missing contentReject during request preparationValidation error response and status
Empty platforms listReject during request preparation; require at least one targetValidation error response and status
Unknown platform valueValidate against supported platform list for connected accountsError response and status for unsupported platform
Unknown or wrong-client accountIdValidate accountId against the selected client's connected accountsError response and status for unknown accountId
Partial multi-platform failureRecord the exact request; check each target result individuallyWhether the response reports per-target success/failure and how retries should be scoped

Response bodies, status codes, and partial-failure reporting should be confirmed for your implementation before relying on them.

Agency workflow decision criteria
Decision criterionQuestion to answerWhy it matters for agencies
Account isolationAre credentials and posting history separate per client account?Prevents cross-client publishing mistakes
Cross-platform publishingCan one request per client target multiple platforms via platforms?Reduces per-platform integration work
Approval & Scheduling WorkflowsCan content be reviewed and approved before the publish request?Separates review from publishing
Per-client analyticsCan engagement data be pulled per account and per platform?Supports client-specific reporting
Team accessCan API keys be managed for collaborative team workflows?Supports shared agency operations

Use these criteria to evaluate whether the workflow fits your agency before committing client work.