Profiles

A profile is one brand, client, or sub-account you publish on behalf of — a single set of connected social accounts. Every post targets exactly one profile. It’s the same object whichever way you work:

In the dashboard — each brand appears under Connections as a profile. Most customers create and connect profiles here, with no code.
Via the API — you reference that same profile by its profile_id (9f2b4c17-…) on every post.

One API key manages all your profiles — there’s no separate key per brand:

Your API key
├── profile: Acme Coffee   → Instagram, Facebook (3 Pages), TikTok
├── profile: Acme Tea      → Instagram, X
└── profile: Client — Nova → LinkedIn, YouTube

One profile holds multiple Facebook Pages — you don’t need a separate profile per Page. Once connected, the dashboard lists every Page on that Facebook account, and each post picks one with facebook_page_id (auto-selected when the profile has only one Page). To publish the same content to several Pages, send several posts, one per Page. See Discover Page & board IDs. One exception: if a Page is pinned to the profile, the pin wins over facebook_page_id — see Pin a Page to a profile.

How many profiles you get

Each plan includes a fixed number of profiles:

Plan	Profiles
Starter	1
Growth	4
Business	10
Custom	Unlimited

When you reach your plan’s limit, upgrade to add more profiles.

Create a profile

In the dashboard

Go to Connections → Connect account and authorize each platform you want to publish to. The profile is created for you — no profile_id to manage by hand.

Via the API

Starting a connection creates the profile and returns a branded, time-limited connect URL in one call:

curl -X POST https://api.madiad.com/v1/connections/start \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "friendly_name": "Acme Coffee" }'

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "friendly_name": "Acme Coffee",
  "access_url": "https://connect.madiad.com/o/abc123def456",
  "expires_in": "48h"
}

Use the returned profile_id (9f2b4c17-…) whenever you publish a post.

Skip the platform picker

POST /v1/connections/start returns a link to a page where the user chooses which platform to connect. If you would rather render that choice in your own UI, ask for one platform and get the platform’s own authorization URL back:

curl -X POST https://api.madiad.com/v1/connections/start-platform \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83", "platform": "instagram" }'

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "platform": "instagram",
  "authorize_url": "https://www.instagram.com/oauth/authorize?...",
  "expires_in": 900
}

Like /v1/connections/start, it creates the profile when profile_id is omitted, and accepts an optional friendly_name.

The authorize_url carries a single-use state that expires in about 15 minutes (expires_in, in seconds). Redirect the user to it immediately — never mint one ahead of time or cache it, unlike the 48-hour link from /v1/connections/start.

Every platform can be started this way except Bluesky, which authenticates with an app password rather than OAuth and returns 400 platform_not_startable — send those users to the shared connect link instead.

List your profiles via API

Two endpoints return your profiles. Which one you want depends on whether you also need to know what each profile has connected.

Just the list

GET /v1/profiles returns every profile on the account, and nothing else:

curl https://api.madiad.com/v1/profiles \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profiles": [
    { "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83", "friendly_name": "Acme Coffee" },
    { "profile_id": "3d81a06f-5b24-4e97-9c1a-7f0d2e8b6a45", "friendly_name": "Acme Tea" }
  ]
}

Each element carries exactly two fields, profile_id and friendly_name. Profiles come back oldest first. The account is taken from your API key, so the call accepts no parameters and can never return another account’s profiles. It is a GET: it consumes no uploads and no FFmpeg minutes, only the per-minute rate limit. This is the one to call for a profile picker, or any time you only need the profile_id that every publish, connection and analytics call asks for. It reads MADIAD Hub’s own records and nothing else, so it answers fast and it keeps answering when a social platform is unreachable.

The list with connection detail

GET /v1/connections/status, called with profile_id omitted, returns every profile and the platforms each one has linked:

curl "https://api.madiad.com/v1/connections/status" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

Each element of the profiles array has profile_id and friendly_name as above, plus connected and accounts (detailed under Check which platforms are connected below). Assembling that detail needs a live lookup of the linked accounts, so this call is slower than GET /v1/profiles and it can return an error while that lookup is unavailable. When you only need the IDs, prefer GET /v1/profiles. To see how many profile slots remain on your plan, call GET /v1/usage — its profiles field returns used / limit / remaining. Each profile starts empty. Open its connect page in a browser and sign in to every platform you want to publish to. MADIAD Hub stores the authorization, so you never handle platform tokens yourself.

Open the connect page

In the dashboard, click Connect account. Via the API, send the user (or yourself) to the access_url returned by /v1/connections/start.

Authorize each platform

Publish

Reference the profile by its profile_id in any post request.

Supported channels

A profile can connect any of the 22 channels listed on Channels, which also records which kind of post each one accepts. A post only succeeds on channels the target profile has actually connected. Listing a channel that isn’t connected returns an error for that channel.

Connect a manual-credential channel

The OAuth channels connect by signing in on the connect page. Eleven channels work differently — Telegram, Discord, Slack, Mastodon, Nostr, Lemmy, dev.to, Hashnode, WordPress, Whop and listmonk have no OAuth login, so instead you link your own bot, webhook, API key or application password with POST /v1/connections/{channel}. Channels lists the exact fields for all eleven. The two worked examples below show the shape; the others follow it exactly.

Telegram — bring your own bot

Message @BotFather on Telegram and send /newbot to create a bot. Copy its bot token.
Add the bot to your target channel or group as an administrator so it can post.
In the dashboard, open Connections → Telegram, paste the bot token and the chat ID (@yourchannel or a numeric id like -100123456789), then connect.

Via the API

curl -X POST https://api.madiad.com/v1/connections/telegram \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
    "bot_token": "123456:ABC-DEF...",
    "chat_id": "@yourchannel",
    "name": "Announcements"
  }'

Required fields: profile_id, bot_token, chat_id. name is an optional label. The bot must be an administrator of the target channel or group. chat_id is either @channelname or a numeric id like -100123456789. Returns 400 if any required field is missing.

{
  "profiles": [
    {
      "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
      "friendly_name": "Acme Coffee",
      "connected": ["telegram"],
      "accounts": [
        { "platform": "telegram", "display_name": "Announcements", "username": null, "avatar": null }
      ]
    }
  ]
}

Discord — channel webhook

In Discord, go to Server Settings → Integrations → Webhooks → New Webhook, pick the channel you want to post to, and click Copy Webhook URL.
In the dashboard, open Connections → Discord, paste the webhook URL, then connect.

Via the API

curl -X POST https://api.madiad.com/v1/connections/discord \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
    "webhook_url": "https://discord.com/api/webhooks/...",
    "name": "Marketing channel"
  }'

Required fields: profile_id, webhook_url. name is an optional label. Returns 400 if either required field is missing.

{
  "profiles": [
    {
      "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
      "friendly_name": "Acme Coffee",
      "connected": ["discord"],
      "accounts": [
        { "platform": "discord", "display_name": "Marketing channel", "username": null, "avatar": null }
      ]
    }
  ]
}

The manual-credential channels are not covered by Analytics — follower, reach, and engagement metrics aren’t available for any of them, and neither is Google Business Profile.

Uploads are unlimited on every paid plan. FFmpeg is still metered where it is enabled, and that allowance is account-wide: all your brands draw from one monthly pool, so a busy brand can borrow from a quieter one. The number of profiles is the cap to plan around. See Usage.

Discover Page & board IDs

Some platforms require an ID you need to look up before posting. Use these endpoints to retrieve those IDs for a given profile.

Facebook Pages

If a profile has more than one connected Facebook Page, pass facebook_page_id in your post request to choose which Page to publish to. List the available Pages with:

curl "https://api.madiad.com/v1/connections/facebook/pages?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "pages": [
    { "id": "1029384756102938", "name": "Acme Coffee", "picture": "https://..." }
  ]
}

Each page has id, name, and picture (avatar URL, may be null). Pass the chosen id as facebook_page_id when posting. If the profile has exactly one Page it is selected automatically — this endpoint is only needed when there are several. Returns 400 if profile_id is missing, 404 if the profile is not yours.

LinkedIn Pages

LinkedIn publishes either as the connected person or as an organization Page they administer. To publish as an organization, pass its ID as target_linkedin_page_id (see Platform options). List the organizations available to a profile with:

curl "https://api.madiad.com/v1/connections/linkedin/pages?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "success": true,
  "pages": [
    {
      "id": "urn:li:organization:12345678",
      "name": "Acme Coffee",
      "picture": "https://...",
      "vanityName": "acme-coffee",
      "followers": 1280
    }
  ]
}

The id is a full urn:li:organization:… URN, not a bare number — pass it verbatim as target_linkedin_page_id. Omit that field and the post goes out as the connected person instead. Only id and name are part of the contract; the other fields are extra detail and may change. Returns 409 platform_not_connected when the profile has no LinkedIn account linked, and 404 not_found when the profile is not yours.

Pinterest boards

Pinterest requires a board ID on every pin. List the boards available to a profile with:

curl "https://api.madiad.com/v1/connections/pinterest/boards?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "boards": [
    { "id": "987654321012345678", "name": "Seasonal Menu" }
  ]
}

Each board has id and name. Pass the chosen id as pinterest_board_id when posting — this field is always required for Pinterest. Returns 400 if profile_id is missing, 404 if the profile is not yours.

Pin a Page to a profile

Connecting Facebook links an account, and one account may administer several Pages; LinkedIn works the same way with organization Pages, and Google Business with locations. Pinning one Page (or location) to a profile fixes the destination: every post from that profile goes there, and nothing can fall back to whichever Page the connected account happens to treat as its default.

A pin overrides the page ID you send with a post. While a Page is pinned to a profile, the facebook_page_id in your publish request is ignored and the post goes to the pinned Page. The request still succeeds, so nothing in the response tells you the destination changed. The same holds for LinkedIn and target_linkedin_page_id, and for Google Business and gbp_location_id. To stop that from happening silently, a post naming a different page or location than the pin is refused with 409 page_pin_conflict.Pin only on a profile that serves one brand. On a profile you use deliberately to reach several Pages, leave it unpinned and address each post with facebook_page_id — or clear the pin first.

You can also set and clear pins in the dashboard, under Connections. Everything below works for facebook, linkedin and google_business; swap the platform in the path.

Read the current pin

curl "https://api.madiad.com/v1/connections/facebook/page?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "success": true,
  "pages": [
    { "id": "1029384756102938", "name": "Acme Coffee", "picture": "https://..." }
  ],
  "selected_page_id": "1029384756102938",
  "selected_page_name": "Acme Coffee"
}

pages is everything the connected account could publish to. selected_page_id and selected_page_name are the pin itself, and both are null when nothing is pinned. On the LinkedIn variant the ids are urn:li:organization:… URNs.

Set the pin

curl -X POST https://api.madiad.com/v1/connections/facebook/page \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83", "page_id": "1029384756102938" }'

Both profile_id and page_id are required; a missing page_id returns 400 invalid_request. The page_id must be one the connected account administers — pick it from pages above. The answer is the same object as the read, with selected_page_id now set. The pin is a property of the profile, read at the moment a post is published rather than when it is created — so it also governs posts that were already scheduled.

Clear the pin

curl -X DELETE https://api.madiad.com/v1/connections/facebook/page \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" }'

With the pin cleared, facebook_page_id on each post decides the destination again.

Google Business locations

google_business pins a location rather than a page. Its read answers with location fields in place of pages:

{
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "success": true,
  "locations": [
    { "name": "locations/15783951491896349152", "title": "Acme Coffee District 1" }
  ],
  "selected_location_id": "locations/15783951491896349152",
  "selected_location_name": "Acme Coffee District 1"
}

To set the pin, send the location’s name as page_id (or as location_id). When the connected Google account manages several locations, a post must either go to a pinned location or carry gbp_location_id; with a single location nothing is needed. The pinned location is also the profile’s default location for reviews and analytics.

Check which platforms are connected

To see which social platforms a profile currently has linked, call:

curl "https://api.madiad.com/v1/connections/status?profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

{
  "profiles": [
    {
      "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
      "friendly_name": "Acme Coffee",
      "connected": ["instagram", "facebook", "tiktok"],
      "accounts": [
        { "platform": "instagram", "display_name": "Acme Coffee", "username": "acmecoffee" }
      ]
    }
  ]
}

connected lists the platform slugs currently linked to the profile, and accounts carries the connected account name/handle per platform. Omit profile_id to get the status of every profile on your account. This is the on-demand way to check state; to be notified the moment a connection changes, subscribe to the connection.connected / connection.disconnected webhooks.

When to use multiple profiles

Agencies — one profile per client.
Multi-brand teams — one profile per brand.
Environments — separate profiles for test vs production audiences.

When you don’t need another profile: several Facebook Pages belonging to the same brand, or several accounts on different platforms for the same brand. They all live in one profile.

Get Started

Concepts

Integrations

API Reference

How many profiles you get

Create a profile

In the dashboard

Via the API

Skip the platform picker

List your profiles via API

Just the list

The list with connection detail

Supported channels

Connect a manual-credential channel

Discover Page & board IDs

Facebook Pages

LinkedIn Pages

Pinterest boards

Pin a Page to a profile

Read the current pin

Set the pin

Clear the pin

Google Business locations

Check which platforms are connected

When to use multiple profiles

​How many profiles you get

​Create a profile

​In the dashboard

​Via the API

​Skip the platform picker

​List your profiles via API

​Just the list

​The list with connection detail

​Connect social accounts

​Supported channels

​Connect a manual-credential channel

​Discover Page & board IDs

​Facebook Pages

​LinkedIn Pages

​Pinterest boards

​Pin a Page to a profile

​Read the current pin

​Set the pin

​Clear the pin

​Google Business locations

​Check which platforms are connected

​When to use multiple profiles

How many profiles you get

Create a profile

In the dashboard

Via the API

Skip the platform picker

List your profiles via API

Just the list

The list with connection detail

Connect social accounts

Supported channels

Connect a manual-credential channel

Discover Page & board IDs

Facebook Pages

LinkedIn Pages

Pinterest boards

Pin a Page to a profile

Read the current pin

Set the pin

Clear the pin

Google Business locations

Check which platforms are connected

When to use multiple profiles