Chuyển tới nội dung chính

Scoutello API

The Scoutello API is a server-to-server API for synchronizing an organization's contacts, tasks, protocols, opportunities, projects, milestones, and events in both directions. It also exposes read-only outbound mail history, assignable-member lookup, and entity-aware tag discovery. Incremental GET/list routes and idempotent batch upserts are the synchronization primitives in this version. It does not expose delete operations or webhooks.

The API base URL is:

https://admin.scoutello.com/api/v1

It is also shown in Organization settings → Developer/API. The OpenAPI document is available at:

https://admin.scoutello.com/api/v1/openapi.json

External sales agents can start contact discovery, read candidate results and communication history, update CRM records, and prepare email drafts for human review. The agent runs in its own sandbox and controls research, qualification, and follow-up timing. See external sales agents and contact discovery for the complete flow.

CapabilityREST routesExplicit scopes
Contact discoveryPOST/GET /scrape-jobs, GET /scrape-jobs/{id}scrape-jobs.write/read
Import or cancel discoveryPOST /scrape-jobs/{id}/import, POST /scrape-jobs/{id}/cancelscrape-jobs.write; imports additionally require contact and project access
Incoming mailGET /inbound-mails, GET /inbound-mails/{scoutelloId}inbound-mails.read
Reviewed email draftsPOST /mail-drafts/batch-upsert, GET /mail-drafts, GET /mail-drafts/{scoutelloId}mail-drafts.write/read; writes additionally require contact and project access

Tenant identity always comes from the credential. Scraping uses a stable caller requestId for idempotency. Scoutello does not expose acquisition campaign creation or execution.

Contacts can be filtered by projectScoutelloId and groupScoutelloId. Outbound mail history can be filtered by project, contact, or conversationId; draft lists can be filtered by project and contact. These filters are bound to pagination cursors. Add inReplyToInboundMailScoutelloId to a mail-draft record to prepare a properly threaded reply. Every outgoing draft requires human approval and send.

Create and protect a key​

For modular organizations, the CRM module must be active in addition to the key's required scopes. A valid key cannot activate a missing module. Requests return HTTP 403 with error code module_not_active when CRM access is unavailable. An organization administrator can review or activate CRM in Subscription; retry after access is active.

An organization administrator can create an integration and API key in Organization settings → Developer/API. The complete key is shown once. Copy it into a secret manager before closing the dialog; Scoutello cannot display the complete key again.

  • Use a separate integration and key for each external system and environment.
  • Grant only the scopes that system needs.
  • Never put a key in browser code, a URL, source control, logs, support messages, or client-side storage.
  • Rotate keys on a schedule. When an active integration is rotated, the replacement key works immediately and the previous key remains valid for no more than 15 minutes so the external system can switch without downtime. An existing earlier expiry still applies, so the previous key may stop working sooner.
  • If a key may have been exposed, pause the integration before rotating it. Pausing temporarily rejects all of the integration's keys. A rotation while paused has no overlap: the previous key stays disabled, and the replacement key remains disabled until the integration is resumed.
  • Permanently revoke the entire integration when disconnecting an external system. Revocation disables every one of its keys and cannot be undone.

Send the key on every authenticated request:

Authorization: Bearer YOUR_API_KEY

Bearer authentication is preferred. Clients that cannot set Authorization may use x-api-key instead. Do not send both headers; requests with different values in both headers are rejected.

The API is intended for backend clients and does not enable cross-origin browser access.

Use GET /whoami after configuring a key to verify the integration, organization, scopes, and key limits without retrieving user personal data.

Scopes​

ScopeAllows
contacts.readList and retrieve contacts. Organization-account and access-bearing member contacts are excluded.
contacts.writeValidate and apply contact upserts.
tasks.readList and retrieve non-private tasks.
tasks.writeValidate and apply task upserts.
protocols.readList and retrieve non-private protocols.
protocols.writeValidate and apply protocol upserts.
opportunities.readList and retrieve opportunities.
opportunities.writeValidate and apply opportunity upserts.
projects.readList and retrieve projects.
projects.writeValidate and apply project and participant upserts.
milestones.readList and retrieve project milestones.
milestones.writeValidate and apply milestone upserts.
members.readList accepted members with member Customer ID, User ID, and display name only.
events.readList and retrieve events and core schedules.
events.writeValidate and apply event upserts.
mails.readRead sent and failed organization-owned outbound mail history.
mail-drafts.readRead this integration's standalone email approval drafts and delivery status.
mail-drafts.writePrepare or revise email drafts for human approval; never approve or send.
tags.readDiscover selectable tags for supported entity types.
scrape-jobs.readRead contact discovery jobs and candidates.
scrape-jobs.writeCreate, import, and cancel contact discovery jobs. Imports also require contact/project scopes.
inbound-mails.readRead incoming organization messages and the acting member's personal inbox.

Private tasks and protocols are never returned by this API. A missing scope returns an authorization error; it is not treated as an empty result.

A nonmember CRM contact can be read and referenced even when it is linked to a Scoutello login. The response contains only the organization's CRM fields, never User identity or access fields. Contacts with a role, permissions, invitation, acceptance, or organization-account status remain hidden. Editing a login-linked contact remains prohibited (protected_contact), including otherwise unchanged CRM fields. To reference an existing readable contact from a task/protocol, contacts.write can establish its external link with only externalId, scoutelloId, and optional externalUpdatedAt. Later link-metadata-only updates use externalId and optional externalUpdatedAt; omit the bootstrap scoutelloId once linked. This never changes the contact or its User. Accepted-member assignment uses the separate members.read projection.

New keys use the sctl_api_ prefix and start with contacts.write only. Every other scope is an explicit opt-in that an organization administrator must grant when creating or rotating a key. Existing credentials keep their current scopes and remain valid.

Project-linked contacts and email drafts​

Contact upserts accept optional projectScoutelloId / projectExternalId and companyScoutelloId / companyExternalId pairs (choose one per pair). The contact, company relationship, and project membership are saved atomically per item. Adding project membership requires projects.write; omitted references preserve other relationships and memberships. Contact detail readbacks include projectParticipations when projects.read is granted. Sales-project agents must explicitly include the project reference, even when reusing a contact.

Standalone drafts use the existing human approval system, without a workflow run:

MethodPathPurpose
GET/mail-draftsPaginated integration-owned drafts; optional projectScoutelloId and status filters.
GET/mail-drafts/{scoutelloId}Current version, review link, content hash, approval/send status and eventual mail ID.
GET/mail-drafts/external/{externalId}Look up a stable integration external ID.
POST/mail-drafts/batch-upsertValidate or apply draft preparation.

Draft preparation requires mail-drafts.write, contacts.read, and projects.write. The referenced contact becomes a project participant. The approver must be an accepted organization member with email-edit permission. Sender selection uses that member's existing permitted organization or personal sender settings; arbitrary From addresses are not accepted.

{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}

Inspect every validation result before repeating with mode: "apply". Read the resulting ID to obtain reviewUrl, draftVersion, contentHash, status, dispatchStatus, and mailScoutelloId. Use expectedVersion: 0 only for creation and the current returned version for revisions. Context and approver are immutable; reviewed/dispatched drafts reject changed content. Identical retries return the original draft.

Drafts appear in the project/contact Email tabs and dashboard approval notifications. API preparation sends no email, including notification emails; existing workflow notification-email behavior is unchanged. The assigned human can edit recipients, subject, body, and supported attachments, save the version, then Approve & send. Integrations cannot perform approval or dispatch. Failed or ambiguous delivery is never retried blindly. When converting protocol-based drafts, preserve the protocols and cross-reference their replacements.

MCP access​

The same Scoutello API key and scopes can be used with the streamable HTTP MCP endpoint:

https://admin.scoutello.com/api/v1/mcp

Configure the MCP client to send Authorization: Bearer YOUR_API_KEY. The legacy /api/mcp URL remains a path compatibility alias, but new clients should use the versioned endpoint. Former sctl_mcp_ credentials are not accepted; replace them with a Scoutello API integration key.

MCP tools map directly to the REST contract and use the same runtime schemas, tenant checks, integration lifecycle, rate limit, and service methods. For example, contacts_list, contacts_get, contacts_get_by_external_id, and contacts_batch_upsert mirror the four contact routes. The same pattern applies to tasks, protocols, opportunities, projects, milestones, and events; mail exposes mails_list and mails_get, members expose members_list, while tags expose tags_list.

The server only advertises tools allowed by the current key's scopes. A key with contacts.read can discover the contact read tools but not contacts_batch_upsert; a key with contacts.write gets the batch-upsert tool but not the read tools. whoami is always available. Write tools have the same immediate effects as their REST equivalents, so use mode: "validate" when a caller should inspect a batch without applying it.

MCP is also server-to-server and does not enable cross-origin browser access. Its JSON-RPC transport needs a dedicated URL, so it cannot share an individual REST resource URL even though authentication and data behavior are shared.

For complete client configuration, verification, tool mapping, and troubleshooting instructions, see the MCP integration guide.

Read records​

Contacts, tasks, protocols, opportunities, projects, milestones, and events use the same read routes:

GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}

Replace contacts with tasks, protocols, opportunities, projects, milestones, or events for the other synchronization resources. externalId appears in a read DTO when the record has been linked by this integration.

A list response has this envelope:

{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}

limit must be from 1 to 100. Results are ordered by the effective time when their public API representation changed and then by Scoutello ID. This effective time can be later than the returned entity updatedAt when integration-link metadata changed. Cursors are opaque: store and send them unchanged, and do not derive meaning from their contents.

The first response fixes snapshotAt for that traversal. Follow nextCursor until hasMore is false before starting another incremental read. This prevents records changing during pagination from making the current traversal unstable.

For incremental synchronization, consume every cursor page and then persist that traversal's snapshotAt as the high-water timestamp. Pass it as the ISO 8601 updatedSince value on the next traversal. The lower bound is inclusive, so retrying a completed snapshot can return boundary records but cannot skip them.

A single-record response has this envelope:

{
"data": {},
"requestId": "request-id"
}

Single-contact responses also include a relations array. Each relation keeps its Scoutello relation ID, creation time, type, notes, and connectedFrom and connectedTo contact references. Contact references contain the Scoutello ID and this integration's external ID when one exists. Contacts excluded by the API's organization-access privacy boundary are not exposed through relations. The contact list response stays compact and does not include relations; use either single-contact route when relationship detail is needed.

Work filters and cursor scope​

Contact lists accept search, type (person, company, supplier, other), status, and tagIds. Search is trimmed, case-insensitive, and limited to 200 characters / 10 whitespace-separated tokens. Every token must occur in at least one of firstName, lastName, or companyName, including legacy company names stored in lastName. Characters such as % and _ are matched literally. Tags use any-of matching with 1–50 IDs. All supplied filters combine with AND. REST encodes tag IDs as repeated parameters; MCP supplies an array:

GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two

Contact cursors are bound to the organization, integration, and every filter. Keep filters on each page; changing a filter rejects the cursor. Tag order/duplicates and search token order/case/whitespace do not change the effective filter.

Work list routes accept the following additional filters; other resource/field combinations are rejected:

ResourceFilters
TasksprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtocolsprojectScoutelloId, milestoneScoutelloId, status (draft or final)
OpportunitiesprojectScoutelloId, stage, ownerScoutelloUserId
Projectsstatus, assignedContactScoutelloId
MilestonesprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore is exclusive; dueAfter is inclusive. They compare the task due date or milestone end date; records without that date do not match. Supply timezone-aware ISO date-times. All filters apply before pagination. Continue a cursor with exactly the same filters, including updatedSince, and the same organization/integration. Page size may change. Old unscoped cursors must restart from the saved high-water timestamp after this release.

Projects, milestones, assignments, and notes​

GET /members (MCP members_list) uses standard pagination and requires members.read. It returns scoutelloId (member Customer ID), scoutelloUserId (User ID), and displayName. Only accepted organization members with a role appear; the lookup does not expose emails or permissions.

Tasks accept assignedScoutelloUserIds; opportunities use ownerScoutelloUserId. Projects and milestones use assignedContacts: [{"scoutelloId":"member-customer-id"}]. Assignments require accepted members of the credential's organization. Omitted assignments remain unchanged; [] clears them. Project, milestone, task, and protocol imports are silent: they do not send assignment notifications or communications.

Event assignedContacts supports readable CRM contacts and accepted members supplied by member Customer ID. Accepted members stay unavailable as ordinary CRM contact references or external-link targets; use the member assignment field for team responsibility.

Create milestones with a name and either projectScoutelloId or projectExternalId. They support description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (defaults to 0), and assignedContacts. Dates cannot end before they start. Each milestone has a stable external link scoped to the integration. Its project cannot be changed through the API. Creates and updates localize name/description in the organization's language.

Tasks and protocols accept project, milestone, and opportunity references as <entity>ScoutelloId or <entity>ExternalId, for example milestoneExternalId. Supply only one spelling per relation, including when clearing with null. All relations must belong to the credential's organization. A milestone-only reference infers the project; a conflicting project, or explicitly clearing a project while retaining its milestone, is rejected. A linked opportunity with a project must agree with the work's project. Omitted relationships preserve current values; explicit null clears a relationship when the remaining context is valid. Reads expose both ID spellings and task assignments.

Task planning and workflows​

Task status is the immutable key of a status in the task's effective workflow, not a fixed enum. Read the available organization and project workflows with GET /task-workflows using the tasks.read scope. Each status includes its key, label, lifecycle type (backlog, unstarted, started, completed, or cancelled), color, order, default flag, and archive state. Project entries indicate whether the organization workflow is inherited. Workflow configuration remains dashboard-administered.

Tasks accept nullable priority (low, medium, high, or urgent) and estimatedEffortMinutes, plus nullable startDate and dueDate. Task reads include the denormalized statusType, parent reference, compact subtask references, and blockedBy / blocks references.

Create or update a one-level subtask with either parentTaskScoutelloId or parentTaskExternalId; null promotes it to a top-level task. Dependencies use arrays of { "scoutelloId": "..." } or { "externalId": "..." } references in blockedBy and blocks. Omitted relationship fields preserve them, while an empty dependency array clears that direction. The API rejects nested subtasks, parent-child dependencies, cross-organization dependencies, duplicates, self-references, and direct or transitive cycles.

Task list filters accept an exact workflow status, lifecycle statusType, priority, parentState (top_level, subtask, or parent), and blockedState (blocked, blocking, or unblocked).

Protocols additionally accept status: "draft" | "final" (new records default to final). A new protocol requires type, date, and either a contact or valid project/milestone context. contactExternalId: null clears its contact only when project/milestone context remains. Internal project notes can therefore be created and read without inventing a customer. Draft/final describes the note's state and never sends a communication. Private tasks and protocols remain inaccessible.

Project participants​

Project participants contains additive upserts keyed by a contact reference, for example:

{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}

Participants describe prospects/customers associated with a project; accountable members use assignments. Omitted participants, an empty array, and omitted participant fields preserve existing data. null clears role, notes, or groupScoutelloId. Duplicate resolved contacts in one payload are rejected. Groups must already belong to the selected project; reads include participantGroups (ID/name) and participant IDs, contacts, role, notes, and group ID. Removing participants or creating groups is currently available in the dashboard.

Batch upsert records​

Write up to 100 records with the resource's batch route:

POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}

Task batches resolve their task records before applying parent and dependency relationships. This two-phase processing allows a parent, blocker, or blocked task to reference another task created in the same batch by its external ID, regardless of record order.

Use the OpenAPI document for each resource's fields and validation constraints. Every record must have a stable externalId between 1 and 200 characters. Treat it as an opaque technical identifier: do not use an email address, name, API secret, or other personal data. externalUpdatedAt is optional, but strongly recommended when the source system provides a reliable modification timestamp.

The request body is limited to 1 MiB. mode defaults to apply:

  • apply validates and writes accepted records.
  • validate performs the same validation and matching without writing, returning would_* outcomes.

For contact imports, matchByEmail can be set to true on the request. It defaults to false; external ID is the safer default identity boundary.

Omitted fields preserve the current value. An explicit null clears a nullable field, and a supplied empty assignment/tag array clears that relation. Project participants are additive upserts: an empty array leaves the roster unchanged. Contact, task, opportunity, and event tag writes use Scoutello tag IDs. Relationship external IDs are resolved only through links belonging to the current integration, while Scoutello user IDs used for ownership or responsibility must identify accepted members of the current organization.

Opportunity creates require an account or contact, and lost opportunities require a loss reason. Monetary amounts use integer cents. Project and event names and descriptions are read and written in the organization's configured language. Event writes support explicit dates and daily, weekly, or monthly recurrence with exclusions; published visibility tiers remain subject to Scoutello's legal-readiness gates. The API does not expose event ticketing, participants, media, templates, newsletters, collaborations, or other advanced event-management controls.

Discover tags​

Use the tags endpoint before supplying tagIds:

GET /tags?entity=events&type=category

entity is required and accepts contacts, tasks, opportunities, or events. It maps to the corresponding stored tag relevancy. type is optional and accepts category or attribute. Selectable categories may be organization-owned or global; selectable attributes come from Scoutello's curated global attribute set. Results include scoutelloId, the name localized to the organization language, type, and relevancy. Cross-organization, wrong-relevancy, and non-selectable tag IDs reject the affected batch item.

Read outbound mail history​

Mail history is read-only:

GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}

Only organization-owned mail in sent or failed status is returned. Responses contain common stored headers and body, BCC, status and timestamps, project/event/newsletter references, attachment IDs and types, and aggregate recipient delivery/open/click/bounce/complaint/rejection statistics. Drafts, queued or scheduled mail, per-recipient rows, rendered snapshots, raw provider errors, and attachment download URLs are never exposed. A later recipient delivery update advances the mail's effective synchronization timestamp so the mail appears in incremental reads again. There are no mail write routes.

An apply result can be created, updated, linked, unchanged, stale_ignored, or rejected. Validation uses would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale, or rejected. A valid batch request returns HTTP 200 even when individual records are rejected, so always inspect every item and the response summary. Keep the response requestId when asking Scoutello support to investigate a failure.

Timestamps and conflicts​

When externalUpdatedAt is present, Scoutello uses it to reject stale changes without failing the rest of the batch. A stale_ignored result is terminal for that older payload; fetch the current record before deciding whether to send a newer version.

Treat timestamps as UTC ISO 8601 values. Preserve their original precision and do not substitute the time when a sync job happened for the source record's modification time.

Idempotency​

The idempotency boundary is the integration plus externalId. Scoutello compares a canonical payload hash and the optional externalUpdatedAt value, so retrying the same record does not create duplicates and can return unchanged.

With externalUpdatedAt, the same timestamp and payload is unchanged, an older timestamp is stale_ignored, and the same timestamp with a different payload is a version conflict. For a link that has never accepted a timestamp, the same timestamp-less payload remains unchanged while a changed payload is applied in arrival order. After a link has accepted a timestamp, a changed payload that omits externalUpdatedAt is rejected as a version conflict so unversioned data cannot overwrite versioned state. This is why source modification timestamps are strongly recommended.

Audit trail​

Accepted API creates, updates, and link-only synchronization actions appear in Scoutello changelogs with Public API as the source and are tied to the responsible integration. Operational run summaries retain request IDs and aggregate result counts for troubleshooting; they do not retain record payloads or API secrets.

Errors and retries​

Request-level errors use this envelope:

{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}

Retry HTTP 429 and transient 5xx responses with exponential backoff and jitter. Honor Retry-After when it is present. Network failures may have happened after Scoutello accepted a request; sending the same batch again is safe because each record is idempotent by external ID and canonical payload. Do not automatically retry authentication, authorization, validation, version-conflict, or individual rejected outcomes without changing the request.

  1. Call /whoami during setup and verify the expected organization and scopes.
  2. Read every page changed since the last completed high-water mark and apply those changes to the external system idempotently.
  3. Send external changes to /batch-upsert, using stable external IDs and source modification timestamps.
  4. Persist checkpoints only after all pages and item results have been handled.
  5. Resolve conflicts according to the source system's ownership rules; do not emulate deletes by sending empty records.

Scoutello deliberately provides no public delete route in this first version. Handle deletion or archival policies outside the API until a documented lifecycle operation is introduced.

Social posts for human review​

The social API prepares posts for a named human reviewer. It cannot approve or publish them. REST and MCP use the same scopes and service.

ScopeEndpoints under /api/v1
social-channels.readGET /social-channels
social-posts.readGET /social-posts, GET /social-posts/{scoutelloId}
social-post-drafts.readGET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId}
social-post-drafts.writePOST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize

New scopes must be explicitly granted. Existing credentials gain no additional access. Use members.read to discover member user IDs, and select a reviewer with posting permission (newsletter.edit). Drafts do not require a CRM contact or project.

{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}

Use publishMode: "now" and scheduledAt: null to publish when approved. Each channel variant contains its complete text, settings, and ordered media IDs. Channel discovery returns supported formats, limits, and settings. The currently supported channels are LinkedIn profiles/pages, Facebook, Instagram, and Threads. Instagram requires media. A variant accepts up to ten images or videos.

Batches accept up to 100 unique external IDs within the existing 1 MiB request limit. mode: "validate" checks references and versions without saving drafts, uploading assets, creating notifications, or enqueueing work. Apply results include IDs, review links, versions, and per-record outcomes. Partial failures do not roll back successful siblings. A notification failure returns a warning with the saved review URL.

Retrieve the current draftVersion before revising a pending draft. Identical retries are idempotent and preserve later human edits. Reviewers cannot be changed in place. After approval or decline, use a new external ID for another proposal. Draft reads are limited to the calling integration; posting history covers all persisted Scoutello-created campaigns in the organization, including dashboard, script, and legacy Scoutello posts. It does not import external channel history.

Lists use the standard limit, cursor, and updatedSince parameters. Posts and drafts also accept channelId, status, after, before, and search; retain all filters on subsequent cursor pages. Date filters apply to publishing time (creation time for immediate pending drafts). Draft status filters approval status; post status matches a campaign or channel delivery status. Reads expose the last known delivery state, per-channel failures, public links, and reconciliation timestamps. Draft incremental reads also reflect campaign delivery changes.

Upload media​

  1. Call POST /social-media/uploads with clientUploadId, filename, contentType, size in bytes, and lowercase hexadecimal sha256 of the original bytes. Supported types are PNG, JPEG, WebP, MP4, WebM, QuickTime, and M4V. The upload ceiling is 500 MiB.
  2. Send the original bytes with HTTP PUT to the returned upload.url, using its headers. Upload URLs expire after 15 minutes. Reuse clientUploadId for retries of the same file; expired sessions or different files need a new ID.
  3. Call POST /social-media/uploads/{assetId}/finalize with a JSON body of {}. Finalization checks size, type, signature, and checksum, freezes a private copy, and returns the asset ID for mediaIds. Repeated finalization is safe.

Upload ownership is bound to the organization and integration. Drafts can reference finalized assets from their organization. Preview URLs are temporary; retrieve the draft again to refresh them. Upload URLs are never issued for finalized objects.

Human review and delivery​

The reviewer receives a dashboard notification and can open the post from Postings or its review URL. Editing creates another immutable version. Approval uses the displayed version and content hash, rechecks membership, channels and assets, and atomically creates one durable campaign. If the proposed time has passed, the reviewer must save an explicit new time or select publishing on approval.

Queue retries reuse the campaign and its platform receipts. Approved campaigns cannot be edited in place. Cancelling through the dashboard preserves their approval history and media; cancellation cannot interrupt an active dispatch. Poll the draft or campaign to distinguish approval from actual platform delivery.