pozyDocs
Dashboard

Getting started

Core concepts

How workspaces, members, profiles, connected accounts, posts, media, webhooks and API keys fit together in Pozy.

Pozy has a small object model. Learn these eight nouns and every endpoint in the API reference reads naturally.

#The model at a glance

Text
Workspace  (billing, rate limits, members, API keys, webhooks)
├── Members            owner · admin · member · viewer · billing
├── API keys           full or profile-scoped, read-write or read
├── Webhook endpoints  events, optional profile and account filters
└── Profiles           one per brand, client or customer (externalId)
    └── Connected accounts   instagram, linkedin, whatsapp, metaads ...
        ├── Posts            one post, many per-platform targets
        ├── Conversations    DMs, comments, reviews, mentions
        └── Ads, numbers, analytics ...
Object What it is Id field Where you meet it
Workspace Your team in Pozy. Owns billing, keys, webhooks and every profile. none in requests (implied by the key) Dashboard, GET /v1/auth/verify
Member A person in the workspace with a role. userId GET /v1/users
Profile A group of connected accounts for one brand or customer. profileId /v1/profiles
Connected account One login on one platform, such as an Instagram business account or a WhatsApp number. accountId /v1/accounts
Post Content you publish, with one target per account. postId /v1/posts
Media item An image, video, GIF or document attached to a post. url mediaItems, POST /v1/media/presign
Webhook endpoint A URL Pozy calls when events happen. webhookId /v1/webhooks/settings
API key A secret that authenticates requests. id /v1/api-keys

#Workspace

The workspace is the top of the tree. Everything you create belongs to exactly one workspace, and an API key can never reach another workspace's data.

Billing is per workspace: connected accounts are counted across all of its profiles (pricing). Rate limits are per workspace too, shared by every key (rate limits).

#Members and roles

People join a workspace by invitation and get one role:

Role Can do
owner Everything, including billing and deleting the workspace.
admin Everything except owning billing and deleting the workspace.
member Publish, reply, run ads and automations. No API keys, team, webhooks or billing.
viewer Read only.
billing Billing and usage only.

Roles apply to dashboard sessions and to OAuth tokens issued to the MCP server. API keys carry their own permissions instead (authentication). See Roles and permissions for the full matrix.

#Profiles

A profile groups connected accounts. Use one per brand you manage, or one per customer if you build a product on Pozy. A profile can hold several accounts on the same platform, such as three Facebook Pages.

Each profile can carry an externalId, your own id for it (a customer id, a tenant slug). Every webhook names the profiles it concerns along with their externalId, so you can route events without a lookup (route webhooks).

Profiles are free. Only connected accounts are billed. Every workspace has a default profile, flagged isDefault: true.

#Connected accounts

A connected account is one authorised login: an Instagram professional account, a LinkedIn page, a YouTube channel, a WhatsApp number, a Meta ad account, a Shopify store. You create them through a connect flow (connecting accounts), never with a password typed into your own app.

Fields you will use often:

Field Meaning
_id The account id. Posts, messages and analytics calls take it as accountId.
platform The platform id, such as instagram, twitter (X) or googlebusiness.
profileId The profile it lives in.
username, displayName How the account appears on the platform.
isActive false once it is disconnected.
needsReconnection true when the platform revoked access and the owner has to reconnect.

Account ids are stable for the life of the connection. When access lapses, run the connect flow again with reconnectAccountId set to the existing id: the account keeps its id and history (account health).

#Posts and targets

A post is one piece of content sent to one or more accounts. Each account it goes to is a target, an entry in platforms[]:

JSON
{
  "content": "Default text for every target",
  "mediaItems": [{ "type": "image", "url": "https://pozy.ai/media/launch.jpg" }],
  "platforms": [
    { "platform": "instagram", "accountId": "6720f41a8d3be96c1e5a02f7" },
    { "platform": "linkedin", "accountId": "6720f5c2e17a4b08d9f3a61b", "customContent": "A longer version for LinkedIn." }
  ],
  "scheduledFor": "2026-11-03T10:00:00",
  "timezone": "America/New_York"
}

The post has an overall status (draft, pending_approval, scheduled, publishing, published, partial, failed, cancelled) and each target has its own status, platform post id and URL. A post where some targets published and others failed ends as partial, and you can retry only the failed ones (post lifecycle).

Per-target overrides live on the target: customContent, customMedia, scheduledFor and platformSpecificData for options only one platform understands (platform settings).

#Media

Attach media by URL in mediaItems. For files on your machine or server, ask Pozy for an upload URL with POST /v1/media/presign, upload the file there, then use the returned public URL in the post (media uploads). Media is served from https://pozy.ai/media/....

#Webhooks

A webhook endpoint is a URL plus a list of events. Pozy sends a signed POST each time one of those events happens: a post published, an account disconnected, a DM received, an ad rejected. Endpoints can be narrowed to some profiles or accounts (webhooks).

#API keys

API keys authenticate server-to-server requests. A key belongs to the workspace, not to a person, and keeps working when the member who created it leaves. Keys can be limited to some profiles, made read-only, or barred from whole areas of the API (authentication).

#Ids and formats

  • Ids are opaque strings. Store them as text and never parse them.
  • Times are ISO 8601. Responses use UTC (2026-11-03T15:00:00.000Z). Requests may send a local time plus a timezone (an IANA name such as Europe/Madrid) where an endpoint accepts one.
  • Field names are camelCase (accountId, scheduledFor). A few query parameters are spelled the platform's way, such as redirect_url on connect calls. Unknown body fields are ignored, so a misspelled field fails quietly: check the response. Some list endpoints, such as GET /v1/posts, reject unknown query parameters with a 400 that names them.
  • Platform ids are lowercase and stable. X is twitter in the API.