Skip to main content
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 user’s behalf, and is the target of every Post you create.

​
Anatomy of a profile

A profile response includes:
  • id — UUID, stable across the profile’s lifetime
  • name — human-readable label shown in the dashboard
  • The network it belongs to (Instagram, X, Facebook, TikTok, YouTube, LinkedIn, Pinterest, etc.)
  • The connection state (active, expired, requires reconnection)
  • Network-specific metadata (handle, page ID, business account ID, etc.)
See GET /workspaces/{workspace}/profiles in the API reference for the full schema.

​
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 going through its own browser-based OAuth consent flow. To add a profile:
  1. Sign in to app.publishbuddy.com.
  2. Open the workspace.
  3. Go to Profiles → Connect new profile.
  4. Choose the network, complete the OAuth handshake, and grant the required permissions.
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 connection state flips to requires_reconnection and any post targeting it will fail 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 profile connection state if you build dashboards on top of the API, and surface a “Reconnect in PublishBuddy” prompt to your users when needed.

​
Profile vs SocialProfileEntity

You’ll occasionally see references to social_profile_entity in the API (especially on Pinterest posts, where the entity is the Board the pin goes to). An entity is a sub-resource inside a profile — think of it as “this profile has several boards / channels / playlists, and the post targets a specific one”. Most networks don’t use entities — for Instagram, X, Facebook (page), TikTok, etc., the profile is the only thing you target. Pinterest is the main case where you’ll need to pick an entity (the board) when creating a post.

​
Per-network quirks

Different networks expose different fields on a post (privacy status on YouTube, board ID on Pinterest, commercial content flags on TikTok, trial parameters on Instagram Reels, etc.). The PostResource schema includes nullable fields for all of these — only the ones relevant to the target profile’s network are meaningful. The dashboard’s post composer applies the right field set per network — when scripting against the API, refer to the relevant endpoint’s request schema for the supported parameters.

​
Next

Posts

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