Tagging People & Collaborators

Attach accounts and co-authors to your media. Use Publer's API to tag people and invite collaborators within the same JSON payload used to create the Instagram post.

Supported Tags & Specs

Tag	Platform	Per post	Coordinates
People	Instagram	20	Required on IG photos
Collaborators	Instagram	3	Not used

Request Structure

Both are arrays on an entry in media[], never on the post itself. In a multi-image post, every entry carries its own tags.

1. People Tags

Positioned tags on a photo — the dots a viewer taps to reveal an account.

{
  "bulk": {
    "state": "scheduled",
    "posts": [{
      "accounts": [{ "id": "ACCOUNT_ID" }],
      "networks": {
        "instagram": {
          "type": "photo",
          "text": "New drop",
          "media": [{
            "path": "https://cdn.example.com/shot.jpg",
            "user_tags": [
              { "username": "publer", "x": 0.5, "y": 0.5 },
              { "username": "partnerbrand", "x": 0.2, "y": 0.8 }
            ]
          }]
        }
      }
    }]
  }
}

On Instagram photos, both x and y are required. On Instagram Reels, they are ignored.

On Instagram photos, a people tag missing x or y is discarded silently — the post publishes without it, and no error is returned. Always send both.

Up to 20 people tags per post. Duplicates are removed automatically.

2. Collaborator Tags

Invites another account to co-author the post, so it appears on both profiles once accepted.

"media": [{
  "path": "https://cdn.example.com/reel.mp4",
  "collaborator_tags": [{ "username": "partnerbrand" }]
}]

Up to 3 collaborators per post.

Collaborator tags require an Instagram account connected through Facebook. Accounts connected via the direct Instagram API skip them without error. People tags work on either connection type.

Common Parameters

Field	Type	Required	Description
user_tags[].username	string	Yes	Account username, without the @
user_tags[].x	number	IG photos	Horizontal position, 0.0–1.0 from the left edge
user_tags[].y	number	IG photos	Vertical position, 0.0–1.0 from the top edge
collaborator_tags[].username	string	Yes	Username of the account to invite

Extra fields are accepted but dropped before publishing: people tags send only username, x and y; collaborator tags send only username.

Workflow

People Tags

1. Build your media[] entry as normal.
2. Add user_tags with a username per account, plus x/y for Instagram photos.
3. Schedule with POST /api/v1/posts/schedule and poll the returned job_id.

Collaborator Tags

1. Add collaborator_tags with the co-author's username.
2. Publish. The invitation is sent automatically.
3. The post appears on the collaborator's profile only once they accept.

Best Practices

• Keep coordinates inside 0.05–0.95 so tag bubbles are not clipped at the edges of the image.
• Tag the subject, not the corner — Instagram positions the label from the point you give.
• Send collaborator invitations only to accounts expecting them; an unaccepted invitation leaves the post on your profile alone.
• There is no API to look up usernames. Supply values you already hold.

Related Topics

• Reels, Shorts & Stories — Short-form formats
• Post with Location — Attaching a place to a post