Skip to content

Approvals

With UmbSocial Pro licensed, a writer who can’t schedule posts can still get them published: they submit a draft for approval, and someone with the Approve permission approves it (choosing when it goes out) or returns it with a note. Nobody without Schedule or Approve can put a post on the calendar.

Approvals are off on a new site: a site where one person writes and publishes doesn’t need them. While they are off, UmbSocial works as without Pro: a writer without Schedule saves drafts, and someone with Schedule publishes them.

Switch them on with the approval settings (ManageSettings):

  • Approvals enabled lets writers submit their drafts for approval. Off by default.
  • Allow self-approval lets an approver approve a post they wrote themselves, or one they were the last to change while it awaited approval. Off by default, so a post always has a second pair of eyes: approving your own post is refused (approval.own_post), and so is approving a post you changed last (approval.self_edited).

The settings are GET and PUT /umbraco/management/api/v1/umbsocial/pro/settings/approvals, with the body { "approvalsEnabled": true, "allowSelfApproval": false }. Reading them needs View, so the backoffice can tell whether to offer the approval actions. Changing them needs ManageSettings.

The two settings are kept in Umbraco’s key/value store (umbracoKeyValue) as UmbSocial.Pro.ApprovalsEnabled and UmbSocial.Pro.AllowSelfApproval, beside UmbSocial’s own UmbSocial. keys. Saving writes only the values that changed. Pro has no table of its own for them.

Switching approvals off never strands a post: posts already awaiting approval can still be approved or returned. Only new submissions stop (approval.disabled).

With approvals on, the composer’s footer bar offers the steps, each only to the people it is for:

  • Submit for approval (primary) is for a writer who has Write but not Schedule, on a new post or a draft. It saves the draft, submits it, shows a notice and takes you back to the queue.
  • Approve (primary) is for someone with Approve, on a post awaiting approval. With Allow self-approval off, it isn’t shown to the post’s author (their own post is refused anyway: approval.own_post). It puts the post in the queue. Its menu has Approve for a time…, which asks for a date and time, and Approve and publish now. Any edits the approver made in the composer are saved first, and the post is approved as they now see it. With Allow self-approval off, an approver who has just changed the post can’t then approve it (approval.self_edited): another approver, or the writer after a return, has to see the change first.
  • Approve when the page goes live is the main button instead of Approve on a post timed to its page: one whose page isn’t live yet, or one the writer chose When the page goes live for. It keeps the post waiting for its page, with the writer’s choice under After the page goes live, which the approver can change before approving. Its menu has Approve into the queue, Approve for a time… and Approve and publish now. On a post whose page is already live and whose writer didn’t choose it, Approve when the page goes live is in the menu of Approve instead. For a post written with AI the button reads Review and post when the page goes live.
  • Return to writer is for someone with Approve, on a post awaiting approval. It asks for a note (required, at most 1,000 characters) and returns the post to its writer as a draft.

After each step you are taken back to the queue. A post awaiting approval can be edited by an approver, who then approves or returns it; saving it as an approver keeps it awaiting approval. The note a returned post carries is shown above the editor, read-only, when its writer opens it. The queue’s status filter has Awaiting approval.

While approvals are off, Submit for approval is not shown. Approve and Return to writer stay for posts that are already awaiting approval, so switching approvals off never strands one. The composer reads the setting once when it loads.

Each step is written to the post’s history (Umbraco’s audit log, shown as the post’s History tab) with UmbSocial’s other entries, through the core’s ISocialAudit, so it shows who did it and when:

Step History entry
Submit “Submitted for approval”, by the writer.
Approve “Approved”, by the approver. Scheduling the post adds the core’s own “Scheduled” or “Added to the queue” entry beside it.
Return “Returned to the writer”, by the approver, with the note as its detail.

The entries’ actions are submitted, approved and returned. A step that is refused writes nothing, and a history entry that can’t be written is logged and never stops the step.

Settings › UmbSocial › Approvals (needs ManageSettings) has the two settings as switches, Approvals enabled and Allow self-approval, both off by default. Select Save in the footer bar (or press Ctrl+S) to save them. If you leave the page with changes you haven’t saved, Umbraco asks whether to discard them.

Step Who From To
Submit The post’s writer (Write), for their own draft only Draft AwaitingApproval. A review note from an earlier return is cleared.
Approve Approve AwaitingApproval Scheduled: in the queue, for a time, or now, as the approver chooses. Or, for a post with a page, timed to the page: Waiting for its page until the page is published, or given its time at once if the page is already live. The approver is recorded as the post’s ApprovedByUserKey.
Return Approve AwaitingApproval Draft, with the approver’s note (1 to 1,000 characters) as its review note, shown to the writer in the composer.

Approve alone is enough to schedule a submitted post: the approver doesn’t also need Schedule. Approving for now, or for a time less than five minutes away, counts towards the same limit as publishing now from the composer (10 a minute for each user), so an approver’s account can’t flood the company’s channels either.

  • It is never sent. It has no scheduled time, and the publisher only picks up scheduled posts.
  • It keeps its page, and its choice under After the page goes live, from submitting to approving: a post written to wait for its page is offered to the approver that way.
  • Its writer can still edit it (saving it as a draft), and it stays awaiting approval. They can’t queue, schedule or publish it themselves: that needs Schedule.
  • An approver with Write can edit it too, to tighten the wording, say. It stays awaiting approval. An approver can’t edit or delete someone else’s draft or a scheduled post that way.
  • Whoever changes it last is recorded. With Allow self-approval off, that person can’t approve it (approval.self_edited), because nobody else has seen the text that would go out. Another approver can, and so can the same approver once someone else (the writer, say) has changed it after them. Returning it and having the writer submit it again starts afresh: what the writer submits is theirs. The record is kept in Pro’s own table, umbSocialProAwaitingEditor, and removed when the post is submitted again, approved or deleted.
  • Once approved, the writer can no longer change it: it isn’t a draft any more.
  • Someone with Schedule can still edit or schedule any post, an awaiting one included, as without Pro.

Approving and returning carry the post’s version as the approver saw it. If the post changed since (the writer saved a change, another approver returned it, or someone edited it), the request is refused with approval.changed: reload the post and decide again. So an approver never approves text they haven’t seen, and two approvers deciding at once can’t both win: a post that one of them returned is never scheduled by the other.

The same version protects every save in UmbSocial: see the management API (post.changed).

While UmbSocial isn’t licensed, posts awaiting approval stay as they are: nothing is deleted, and nothing is scheduled or sent. The Submit for approval, Approve and Return to writer buttons and the Approvals settings page are hidden, and the API refuses submitting, approving, returning and the approval settings with licence.pro_required. When the licence is active again, the posts are still waiting for an approver, and the settings are as they were.

All of these need UmbSocial to be licensed (licence.pro_required, status 403, otherwise). {key} is the post’s key, and expectedVersion is the post’s version as the approver loaded it (required).

  • POST /umbraco/management/api/v1/umbsocial/pro/posts/{key}/submit (Write) has no body. Refused with approval.disabled while approvals are off.
  • POST /umbraco/management/api/v1/umbsocial/pro/posts/{key}/approve (Approve) takes { "when": "Queue", "expectedVersion": "…" }, { "when": "At", "atUtc": "2026-11-12T09:00:00Z", "expectedVersion": "…" } or { "when": "Now", "expectedVersion": "…" }, or, for a post with a page, { "when": "OnPagePublish", "pageDelayMinutes": 60, "expectedVersion": "…" } (pageDelayMinutes is left out for the queue’s next free slot, or is 0, 60 or 1440). The post is scheduled as the composer would schedule it, with the same checks, so a time in the past is schedule.past, a full queue is schedule.no_free_slot, and OnPagePublish for a post with no page is schedule.needs_page. Too many approvals for now answer 429.
  • POST /umbraco/management/api/v1/umbsocial/pro/posts/{key}/return (Approve) takes { "note": "Add the link to the pricing page", "expectedVersion": "…" }.

Each answers 200 when it’s done, with the post’s key and its new version, as saving a post does: send that version with the next change, without reloading the post. A refusal is problem details with its codes in codes; an unknown post is 404 (post.not_found).

In UmbSocial.Pro.Notifications. The “…ing” ones run before the change: cancel one with an error message to refuse it (approval.cancelled:<message>, or approval_settings.cancelled:<message> for the settings). The post they carry is a copy of the stored post, so changing it changes nothing. The “…ed” ones run after the change was saved.

Notification When Properties
SocialPostSubmittingNotification Before a draft is submitted. Post, ByUserKey (the writer).
SocialPostSubmittedNotification After it was submitted. PostKey, ByUserKey.
SocialPostApprovingNotification Before a post is approved. Post, Schedule (When and AtUtc), ByUserKey (the approver).
SocialPostApprovedNotification After it was approved and scheduled, or approved to wait for its page. PostKey, ByUserKey, ScheduledForUtc (null for a post waiting for its page: it has no time until the page is published).
SocialPostReturningNotification Before a post is returned. Post, Note, ByUserKey (the approver).
SocialPostReturnedNotification After it was returned. PostKey, Note.
SocialApprovalSettingsSavingNotification Before the approval settings are saved. Change Target, or cancel. Target (ApprovalsEnabled, AllowSelfApproval), Existing.
SocialApprovalSettingsSavedNotification After they were saved. Settings.

The post notifications are raised only while UmbSocial is licensed. Scheduling an approved post also raises the core’s saving and saved notifications, as any scheduled post does.

From code, the same steps are IApprovalService (UmbSocial.Pro.Approvals): SubmitAsync, ApproveAsync and ReturnAsync, and the settings are IProSettingsService (UmbSocial.Pro.Persistence), which reads and writes the key/value keys. They don’t check the person’s permissions: your code decides who may call them. Pro’s services check the licence themselves, not only its endpoints: while UmbSocial isn’t licensed, a service that changes something refuses with licence.pro_required and changes nothing, and one that reads finds nothing.

Pro adds three events to the UmbSocial group in Settings › Webhooks: Social post submitted for approval (umbSocialPostSubmitted), Social post approved (umbSocialPostApproved) and Social post returned to writer (umbSocialPostReturned). Their payloads follow the same rules as the core’s, including the opt-in text and author, and never carry the review note. The approved event’s status is the post’s status when the webhook is sent, so a post approved to go out now may already be Publishing. A post approved to wait for a page that isn’t live yet has no time, so its scheduledForUtc is null and its status is WaitingForPage: if your handler expects a time on every approval, allow for that. See Webhooks.