Social profiles

A profile is one connected social account inside a workspace, for example “Acme’s Instagram business account” or “Acme on X”. Each profile is tied to exactly one social network, holds the OAuth credentials needed to publish on that account’s behalf, and is the target of every post you create. The dashboard calls profiles social accounts. The API calls them profiles.

Anatomy of a profile

{
  "id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
  "name": "Acme",
  "network": "instagram",
  "avatar": "https://scontent.cdninstagram.com/...",
  "social_id": "17841400000000000",
  "workspace_id": "9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c",
  "profile_type": "business_profile",
  "own_type": "workspace",
  "connected": true,
  "status": "active",
  "synchronization_status": "synchronized",
  "has_queue": true,
  "entities": []
}

Field	Notes
`id`	UUID, stable across the profile’s lifetime. This is the `profile_id` you pass when creating posts.
`name`	The account’s display name on the social network.
`network`	The network slug: `facebook`, `instagram`, `instagram-direct`, `x`, `linkedin`, `pinterest`, `tiktok`, `youtube`, `threads`, `bluesky`, `telegram`, or `google-profile` (Google Business Profile). `instagram-direct` is an Instagram account connected with Instagram login instead of through a Facebook Page; both behave the same when posting.
`avatar`	The account’s avatar URL on the network.
`social_id`	The account’s ID on the network itself.
`workspace_id`	The workspace the profile belongs to.
`profile_type`	The kind of account, for example `business_profile` or `page`.
`own_type`	`workspace` for accounts connected to this workspace. `public` marks competitor accounts that were added for analytics only. Every member of the workspace sees `public` profiles.
`connected`	Whether the OAuth connection is currently valid.
`status`	`active` or `inactive`. Posts can only target active profiles.
`synchronization_status`	State of the analytics sync: `synchronization_in_process`, `synchronized`, or `failed_synchronization`.
`has_queue`	Whether queue timeslots are configured. Required for `publish_type: queue_using_timeslots`.
`entities`	Sub-entities of the account, for example Pinterest boards. Use an entity `id` as `boardId` when posting to Pinterest.

Listing profiles

curl "https://api.publishbuddy.com/v1/workspaces/$WORKSPACE_ID/profiles?sort=name&per_page=50" \
  -H "Authorization: Bearer $PUBLISHBUDDY_TOKEN" \
  -H "Accept: application/json"

The list holds the profiles you can access: every profile for the workspace owner, and for other members the profiles they have been given access to plus every public profile. It is paginated (default 50 per page, maximum 100) and accepts a sort parameter: name, -name, created_at, or -created_at. A leading - sorts descending, and any other value is 422. The default is created_at: the order the profiles were connected in, oldest first. See Pagination. Full schema: GET /workspaces/{workspace}/profiles in the API reference.

Connecting a profile

Profile connection happens entirely in the dashboard. There is no API endpoint to connect a new profile, because every supported network requires its own browser-based consent flow. To add a profile:

Sign in to app.publishbuddy.com.
Open the workspace and go to Social Accounts.
Click Add Social Accounts, choose the network, and complete the network’s sign-in and permission steps.

For Facebook you connect a Page, not a personal profile. For Instagram you connect a professional account (Business or Creator). Once connected, the profile is immediately usable from the API.

When a profile needs reconnection

Social networks expire OAuth tokens periodically, sometimes on a schedule, sometimes when the user changes their password or revokes access. When that happens, the profile’s connected field flips to false and any post targeting it fails with an error_message explaining the cause. The API does not let you complete the OAuth refresh. The user has to reconnect from the dashboard, the same way they originally connected. Monitor connected if you build dashboards on top of the API, and surface a “Reconnect in PublishBuddy” prompt to your users when needed.

Profile vs entity

A profile’s entities array lists sub-resources inside the connected account. On Pinterest, the entity is the board the pin goes to. Each entity carries an id, name, about, image.link, social_id, and a social_profile_entity_type. Most networks do not use entities. For Instagram, X, Facebook, TikTok, and the rest, the profile is the only thing you target. Pinterest is the main case where you need to pick an entity (the board) when creating a post.

Per-network settings

Network-specific settings live in the post’s platform_content object, keyed by platform slug. See Per-network parameters for the full request shape.

Network	`platform_content` key	Highlights
Instagram (both connection types)	`instagram`	`contentType` (`post`, `reels`, `story`, `trial reel`), `settings.graduation_strategy` for trial reels (`MANUAL` or `SS_PERFORMANCE`), `settings.location`
TikTok	`tiktok`	`settings.privacyLevel` (required: `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, or `SELF_ONLY`), `settings.allowComments`, `settings.allowDuet`, `settings.allowStitch`, `commercial_content_type`
YouTube	`youtube`	`settings.title`, `settings.privacyStatus`, `settings.category`, `settings.license`
Pinterest	`pinterest`	`settings.boardId` (required: an entity `id` from the profile), `settings.targetUrl`, `settings.title`
Facebook	`facebook`	`settings.videoType: "reel"`, `cta` (`type` and `link`), `settings.location`
LinkedIn, Threads, Bluesky	`linkedin`, `threads`, `bluesky`	Text and media only; the block accepts a per-platform `content` override
X, Telegram, Google Business Profile	none	Text and media only; no `platform_content` block

The dashboard’s post composer applies the right field set per network. When scripting against the API, refer to POST /workspaces/{workspace}/posts in the API reference for the canonical schema.

Posts

How to plan, schedule, and publish content to one or many profiles.

Getting started

Core concepts

How-to guides

API essentials

Anatomy of a profile

Listing profiles

Connecting a profile

When a profile needs reconnection

Profile vs entity

Per-network settings

Next

Posts

​Anatomy of a profile

​Listing profiles

​Connecting a profile

​When a profile needs reconnection

​Profile vs entity

​Per-network settings

​Next

Posts

Anatomy of a profile

Listing profiles

Connecting a profile

When a profile needs reconnection

Profile vs entity

Per-network settings

Next