Team roles and post approval
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/rolesanswers"enabled": false; - the approval routes (
/api/uploadposts/approvals*) answer503 Service Unavailablewith"error_code": "post_approvals_disabled"; client_approvalin 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
| Role | Can do |
|---|---|
| Owner | Everything (the account holder, without X-Act-As-User). |
| Admin | Everything a member can do today, and approves or rejects posts. |
| Editor | Reads (profiles, calendar, history, status, analytics), uploads media and creates posts. Its posts wait in the approval queue (pending_approval). |
| Contributor | Like Editor, but its posts are saved as drafts (draft) that a reviewer schedules. |
| Viewer | Reads 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_code | Meaning |
|---|---|
team_role_forbidden | The role does not allow this action (role and permission included). |
team_profile_forbidden | The profile is not one of the member's, or the route is not available to members limited to some profiles. |
team_approvals_disabled | Editors and Contributors cannot create posts while post approval is off. |
team_page_not_pinned / team_page_forbidden | Facebook or LinkedIn Page not pinned to the profile / a different Page from the pinned one. |
team_access_unavailable | The 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 path | Who | What |
|---|---|---|
GET /api/uploadposts/approvals | Everyone with access | Open 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 reviewer | One item, with its fields, preview and thumbnail (signed URLs) and the Page that will be used. |
PATCH /api/uploadposts/approvals/{id} | Author or reviewer | Edit while open; same body as editing a scheduled post. Each edit raises version. |
DELETE /api/uploadposts/approvals/{id} | Author or reviewer | Withdraw (author) or discard (reviewer); its media is deleted. |
POST /api/uploadposts/approvals/{id}/approve | Owner, Admin | Approve: {"version": 3, "comment": "...", "scheduled_date": "...", "timezone": "...", "publish_now": true}. |
POST /api/uploadposts/approvals/{id}/reject | Owner, Admin | Reject: {"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.
| Status | error_code |
|---|---|
| 400 | invalid_body, version_required, comment_required, invalid_comment, invalid_scheduled_date, invalid_status, invalid_limit, invalid_before |
| 404 | approval_not_found |
| 409 | approval_closed, approval_version_changed, approval_expired, scheduled_date_in_past, approval_state_changed, NO_QUEUE_SLOTS, QUEUE_BUSY |
| 429 | Monthly upload limit, SCHEDULED_POSTS_LIMIT, or approvals_limit (too many open items) |
| 500 | approval_failed (the item is open again and credits are returned) |
| 503 | post_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.