Posts

Add collaborators to Instagram posts via API

With instagram.collaborators, the post goes out with other accounts invited as collaborators. It works on feed, reels and story, through the same POST /posts call, with no app review.

The request

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "post-5120",
  "format": "feed",
  "caption": "Parceria nova",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.example.com/parceria.jpg"
    }
  ],
  "instagram": {
    "collaborators": [
      "marca_parceira",
      "criador_oficial"
    ]
  }
}

What you can do

  • Invite collaborators on feed, reels and story.
  • Send usernames without @: Connect strips a leading @ and lowercases them.
  • Combine it with user tags in media[].user_tags on the media.
  • Use both instagram and instagram_business accounts.

Rules and limits

  • At most 5 collaborators per post.
  • Each username is up to 30 characters: letters, numbers, period and underscore, without @.
  • On a story, collaborators is the only option of the instagram block.
  • The answer is 202: the post is published in the background. Follow it with GET /posts/{uuid}.
  • external_reference is required and Idempotency-Key avoids duplicating.

Main fields

FieldTypeRequiredDescription
external_referencestringYesThe post's id in your system (up to 100 characters). Prevents publishing the same post twice on the same account.
formatstringYesPost format. On Instagram: feed, reels or story. On Facebook: feed, reels or story.
mediaarrayYesList of media, in order. Each item has type and url.
instagram.collaboratorsarrayNoUp to 5 users invited as collaborators, without @. Works on feed, reels and story.
media.user_tagsarrayNoInstagram only. User tags (username, x and y), up to 20 per media. On an image, x and y from 0 to 1 go together.

Who it is for

  • Partnership posts

    Brands and creators publish together: the SaaS sends the post from the brand account and invites the creator as a collaborator.

  • Agencies

    The agency publishes from the client's account and invites its own account as a collaborator.

  • Influencer AI agent

    An agent builds the campaign post and automatically invites the profiles on the partner list.

Works with

  • Instagram Business
  • Instagram

Frequently asked questions

How many collaborators can I invite?

Up to 5 per post, on feed, reels or story.

Do I send the @ in the username?

No. Send it without @; a leading @ is stripped and the value is lowercased.

Is a collaborator the same as tagging a user?

No. Collaborators go in the instagram block; user tags go in media[].user_tags.

Related

See everything you can do with Posts

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.