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
| Field | Type | Required | Description |
|---|---|---|---|
| external_reference | string | Yes | The post's id in your system (up to 100 characters). Prevents publishing the same post twice on the same account. |
| format | string | Yes | Post format. On Instagram: feed, reels or story. On Facebook: feed, reels or story. |
| media | array | Yes | List of media, in order. Each item has type and url. |
| instagram.collaborators | array | No | Up to 5 users invited as collaborators, without @. Works on feed, reels and story. |
| media.user_tags | array | No | Instagram 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.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
