Skip to main content

Team roles and post approval

Not generally available yet

Team roles and post approval are not generally available yet. Until they are:

  • every team member keeps today's access (full access to every profile), and GET /api/uploadposts/teams/roles answers "enabled": false;
  • the approval routes (/api/uploadposts/approvals*) answer 503 Service Unavailable with "error_code": "post_approvals_disabled";
  • client_approval in Generate JWT has no effect.

Team members use their own API key or dashboard session plus the header X-Act-As-User: <owner email> (the accounts shared with them are listed by GET /api/uploadposts/teams/shared-with-me). The account owner invites members and sets their role from the dashboard (Team); roles and profile lists can only be changed by the owner, never by an API key or another member. Inviting, accepting, rejecting or removing members and changing a member's role or profiles are dashboard-only: there is no API key route for them.

Roles​

RoleCan do
OwnerEverything (the account holder, without X-Act-As-User).
AdminEverything a member can do today, and approves or rejects posts.
EditorReads (profiles, calendar, history, status, analytics), uploads media and creates posts. Its posts wait in the approval queue (pending_approval).
ContributorLike Editor, but its posts are saved as drafts (draft) that a reviewer schedules.
ViewerReads only.

Any role can also be limited to some profiles: such a member only sees and acts on those profiles, and only through the routes that can check the profile (others answer 403 team_profile_forbidden). A limited member publishing to Facebook or LinkedIn uses the Page pinned to the profile (Facebook Page, LinkedIn Page): GET /api/uploadposts/facebook/pages and /linkedin/pages only list that Page (or "pages": [] with "page_pin_required": true); naming another Page (facebook_page_id, target_linkedin_page_id, linkedin_page_id, page_urn) answers 403 team_page_forbidden, and naming one, or publishing to Facebook, without a pinned Page answers 403 team_page_not_pinned (the owner or an Admin pins it). LinkedIn without a Page posts to the personal profile of the login, as usual. Secrets (tokens, API keys, webhook URLs...) are removed from every answer to members who are not unlimited Admins.

GET /api/uploadposts/teams/roles returns the matrix and who you are:

{
"success": true,
"enabled": true,
"approvals_enabled": true,
"roles": ["owner", "admin", "editor", "contributor", "viewer"],
"permissions": {"owner": ["account", "read", "compose", "approvals_own", "approvals_review", "audit", "manage"], "editor": ["account", "read", "compose", "approvals_own"], "...": []},
"approval_roles": ["editor", "contributor"],
"your_email": "[email protected]",
"your_role": "editor",
"your_profiles": ["client-a"]
}

GET /api/uploadposts/teams/members (owner only) adds role and profiles (null = every profile) to each member.

Access errors (403)​

error_codeMeaning
team_role_forbiddenThe role does not allow this action (role and permission included).
team_profile_forbiddenThe profile is not one of the member's, or the route is not available to members limited to some profiles.
team_approvals_disabledEditors and Contributors cannot create posts while post approval is off.
team_page_not_pinned / team_page_forbiddenFacebook or LinkedIn Page not pinned to the profile / a different Page from the pinned one.
team_access_unavailableThe member's access could not be checked; try again.

Posting as an Editor or Contributor​

The upload endpoints work the same, but nothing is published or scheduled: the post goes to the queue and the answer is 202 Accepted:

{
"success": true,
"pending_approval": true,
"approval_id": "9f2c4e1a7b3d4c5e8a6f0b1c2d3e4f50",
"approval_status": "pending_approval",
"job_id": null,
"request_id": "...",
"scheduled_date": "2026-11-20T09:00:00Z",
"message": "..."
}

With add_to_queue the answer has "queued": true and no slot: the slot is picked when the post is approved. GET /api/uploadposts/status?request_id= answers the approval state (pending_approval, draft, approving, rejected, withdrawn, expired) until it is approved; after that, the job's status as usual. Repeating the request with the same Idempotency-Key returns its current state without reserving anything.

The approval queue​

Method and pathWhoWhat
GET /api/uploadposts/approvalsEveryone with accessOpen items (?status= comma-separated, profile_username, author, limit 1-200, before = previous next_before). Editors and Contributors only see their own. With count_only=true it answers only the numbers, with the same filters: {"success": true, "counts": {"pending_approval": 3, "draft": 1}, "total": 4}.
GET /api/uploadposts/approvals/{id}Author or reviewerOne item, with its fields, preview and thumbnail (signed URLs) and the Page that will be used.
PATCH /api/uploadposts/approvals/{id}Author or reviewerEdit while open; same body as editing a scheduled post. Each edit raises version.
DELETE /api/uploadposts/approvals/{id}Author or reviewerWithdraw (author) or discard (reviewer); its media is deleted.
POST /api/uploadposts/approvals/{id}/approveOwner, AdminApprove: {"version": 3, "comment": "...", "scheduled_date": "...", "timezone": "...", "publish_now": true}.
POST /api/uploadposts/approvals/{id}/rejectOwner, AdminReject: {"comment": "..."} (required, max 2000).

Approving needs the version you reviewed: if someone edited it meanwhile you get 409 approval_version_changed with current_version and the current item. The date used is the one you send; otherwise now (posts without a date, or publish_now); otherwise the next free queue slot (posts sent with add_to_queue); otherwise the post's own date. Credits are reserved at that moment (monthly limit 429, failed renewal 402). The answer has the new job_id and scheduled_date, and from there it is a normal scheduled post.

Items expire: an Editor's post whose date passes before anyone approves it becomes expired (it is never published late); posts without a date and drafts expire after 30 days.

Statuserror_code
400invalid_body, version_required, comment_required, invalid_comment, invalid_scheduled_date, invalid_status, invalid_limit, invalid_before
404approval_not_found
409approval_closed, approval_version_changed, approval_expired, scheduled_date_in_past, approval_state_changed, NO_QUEUE_SLOTS, QUEUE_BUSY
429Monthly upload limit, SCHEDULED_POSTS_LIMIT, or approvals_limit (too many open items)
500approval_failed (the item is open again and credits are returned)
503post_approvals_disabled

Approval by the end client​

For agencies using the white-label connect page: generate the profile's JWT with "client_approval": true and the end client can approve or reject the posts of that profile that are waiting (pending_approval; never drafts or other profiles) from the connect page. The end client cannot change the date. It needs both the profile setting and a link generated with "client_approval": true: a link generated without it cannot approve. Generate the JWT again with false to turn it off for every link. validate-jwt says whether a token can approve (profile.client_approval).

With the profile JWT as Authorization: Bearer <token>:

GET  /api/uploadposts/approvals/client
POST /api/uploadposts/approvals/client/{id}/approve {"version": 2, "comment": "OK"}
POST /api/uploadposts/approvals/client/{id}/reject {"comment": "Change the photo"}

Items, and the item of the approve and reject answers, come without author, who decided or internal ids (author_email, author_role, decided_by, decided_by_role, request_id, external_id, job_id, fields); the approve answer still has the new job_id and scheduled_date at the top level. Decisions are recorded as decided_by: "client:<profile>". Errors: 401 unauthorized, 403 client_approval_not_allowed or account_unavailable, 404 approval_not_found, and the approve/reject errors above.

Webhook events​

While post approval is on, the account webhook and webhook subscriptions can receive post_approval_requested, post_approved, post_rejected and post_approval_expired. They are strictly opt-in: they only arrive if the event is listed (an empty list, meaning "all events", does not include them).

{"event": "post_approved", "user_email": "[email protected]", "profile_username": "client-a", "approval": {"approval_id": "9f2c4e1a7b3d4c5e8a6f0b1c2d3e4f50", "status": "approved", "...": "..."}, "created_at": "2026-11-16T21:00:00Z"}

Team activity log​

GET /api/uploadposts/teams/audit?actor=&action=&profile_username=&target_id=&since=&until=&limit=50&cursor=

Owner and Admins not limited to some profiles. Newest first; page with cursor = the previous next_cursor. Rows are kept retention_days (400) days.

{
"success": true,
"items": [
{"id": "...", "action": "approved", "actor_email": "[email protected]", "actor_role": "owner", "target_type": "approval", "target_id": "9f2c4e1a7b3d4c5e8a6f0b1c2d3e4f50", "profile_username": "client-a", "details": {}, "at": "2026-11-16T21:00:00Z"}
],
"next_cursor": null,
"retention_days": 400
}

Actions: post_created, published (the real result of a member's or approved post), scheduled_edited, scheduled_cancelled, approval_requested, draft_created, approval_edited, approved, rejected, approval_withdrawn, approval_expired, member_access_changed. Invalid filters answer 400 (invalid_limit, invalid_cursor, invalid_date, invalid_<filter>).

See also the error code catalog.