Mirsad Partner API

Keys and authentication

Create keys yourself: sign in to portal.mirsad.si as an owner or admin of your organisation and open API keys. A key is shown once; Mirsad stores only a fingerprint of it, so copy it straight into your secret store. You can revoke a key on the same page at any time.

Send the key on every request. Keys are 43 characters and start with mk_.

Authorization: Bearer mk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Conventions

• JSON only. Send Content-Type: application/json with request bodies (at most 10 KB). Responses carry Cache-Control: no-store.
• Your own ids. Every post and sign-in carries your external_campaign_id and external_creator_id (1–100 printable characters, no spaces), so you never need to map Mirsad's ids back.
• Missing is null, never 0. If Instagram does not show a number (likes hidden by the creator, views on a photo), the field is null. Treat null as "unknown", not as zero.
• Times are ISO 8601 in UTC (2026-10-20T19:57:10.226Z). Dates (campaign_ends_on, from, to) are calendar dates in Baku time (UTC+4).
• Lists are newest first and paged with limit (1–200, default 50) and an opaque cursor: pass back next_cursor until it is null.
• Only your data. Every answer contains only your organisation's own posts and creators. An id from another organisation is a 404.

Quick start

Three calls from registration to numbers. The figures are an example. Put your key in an environment variable first:

export MIRSAD_KEY='mk_…'

1. Register the post when the creator publishes:

curl -s -X POST https://api.mirsad.si/v1/tracked-posts \
  -H "Authorization: Bearer $MIRSAD_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.instagram.com/reel/XXXXXXXXXXX/","username":"creator.username","external_campaign_id":"spring-sale","campaign_ends_on":"2026-10-31"}'

2. About 10 minutes later, read it back. The status is now active and latest holds the first reading:

{
  "id": "cc995e67-2873-4e7a-9e74-3847305b8132",
  "status": "active",
  "media_type": "reel",
  "posted_at": "2026-10-06T12:28:33.000Z",
  "latest": { "captured_at": "2026-10-20T19:57:10.226Z", "views": 268, "likes": 7, "comments": 0, "followers": 666 }
}

3. Show the campaign with one call: GET /v1/campaigns/spring-sale/summary.

How tracking works

1. You register a post with its link, the creator's Instagram username, your campaign id and the campaign's last day. It starts as pending.
2. First reading within about 10 minutes. Mirsad finds the post among the creator's recent posts and stores its numbers. Status becomes active.
3. One reading a day at 04:30 Baku time, kept forever as a history (not overwritten). That is what /metrics returns.
4. A final reading on the first run after campaign_ends_on; then status becomes ended and reading stops.

Public readings come from Instagram's official Business Discovery API: views (Reels only), likes, comments and the creator's follower count. Shares, saves, reach and stories need the creator to sign in.

Links that work: https://www.instagram.com/p/<code>/, /reel/<code>/, /reels/<code>/, /tv/<code>/, with or without the username in the path; tracking parameters such as ?igsh= are ignored. Stories and profile links are refused.

curl -s "https://api.mirsad.si/v1/tracked-posts?external_campaign_id=spring-sale&limit=50" \
  -H "Authorization: Bearer $MIRSAD_KEY"

{ "data": [ /* posts, as in GET /tracked-posts/{id} */ ], "next_cursor": null }

{
  "id": "cc995e67-2873-4e7a-9e74-3847305b8132",
  "platform": "instagram",
  "url": "https://www.instagram.com/reel/XXXXXXXXXXX/",
  "username": "creator.username",
  "external_campaign_id": "spring-sale",
  "external_creator_id": null,
  "campaign_ends_on": "2026-10-31",
  "status": "active",
  "status_note": null,
  "media_type": "reel",
  "posted_at": "2026-10-06T12:28:33.000Z",
  "created_at": "2026-10-20T19:56:51.116Z",
  "last_checked_at": "2026-10-20T19:57:10.226Z",
  "latest": { "captured_at": "2026-10-20T19:57:10.226Z", "views": 268, "likes": 7, "comments": 0, "followers": 666 },
  "latest_insights": null  // filled when the creator has signed in
}

{
  "post": { /* the post */ },
  "source": "business_discovery",
  "data": [
    { "captured_at": "2026-10-20T19:57:10.226Z", "views": 268, "likes": 7, "comments": 0, "followers": 666 },
    { "captured_at": "2026-10-21T00:30:17.609Z", "views": 268, "likes": 7, "comments": 0, "followers": 666 }
  ]
}

{
  "external_campaign_id": "spring-sale",
  "posts": 2, "posts_with_readings": 2,
  "by_status": { "active": 2 },
  "totals": { "views": 290, "likes": 20, "comments": 5 },
  "posts_with_hidden_likes": 1,   // their likes are not in totals.likes
  "last_captured_at": "2026-10-21T00:30:17.609Z",
  "insights": { "posts_with_insights": 0, "totals": { "views": 0, "reach": 0, "saves": 0, "shares": 0, "total_interactions": 0 }, "last_captured_at": null },
  "data": [ /* posts */ ],
  "data_complete": true
}

How Instagram sign-in works

Public numbers have no reach, saves, shares or stories. When a creator signs in with Instagram, Mirsad also reads their own insights for their tracked posts once a day, and their stories every hour while they are live. The creator sees Instagram's consent screen for your organisation's app and can disconnect at any time.

1. Your server asks Mirsad for a one-time sign-in link for a creator.
2. The creator opens it in their phone's browser (where Instagram is logged in), sees a short Mirsad page, then Instagram's consent screen.
3. Mirsad sends them back to your return_url with the result in the query string, and sends your server a notification.
4. From then on latest_insights is filled on that creator's tracked posts, and stories appear under the connection.

curl -s -X POST https://api.mirsad.si/v1/connect-links \
  -H "Authorization: Bearer $MIRSAD_KEY" -H "Content-Type: application/json" \
  -d '{"external_creator_id":"cr-1042","username":"creator.username","return_url":"https://partner.example/creators/connected"}'

{
  "id": "…",
  "url": "https://portal.mirsad.si/connect/instagram?t=…",
  "external_creator_id": "cr-1042",
  "username": "creator.username",
  "expires_at": "2026-10-21T12:00:00.000Z"   // valid one hour, one use
}

{
  "id": "…", "platform": "instagram", "external_creator_id": "cr-1042",
  "status": "active", "end_reason": null,
  "ig_user_id": "…", "username": "creator.username", "account_type": "creator",
  "scopes": ["instagram_business_basic", "instagram_business_manage_insights"],
  "connected_at": "…", "ended_at": null, "token_expires_at": "…",
  "last_insights_at": "…", "last_stories_at": "…"
}

{
  "id": "evt_…",
  "type": "connection.connected",
  "created_at": "…",
  "data": { "connection": { /* as in GET /connections/{id} */ }, "replaces": ["…"] }
}

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received (a Buffer or string), before JSON.parse
export function verifyMirsad(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Statuses

Tracked post

Connection

Errors

Errors are JSON: {"error": "…"}, sometimes with details (a list of field problems) or extra fields.

Integration checklist

1. Create a read-and-write key in the portal and store it in your server's secret store.
2. When a creator's approved content goes live, call POST /tracked-posts with your campaign and creator ids and the campaign's last day. Retry on network errors; a repeat is answered with the same record.
3. Check that the creator's account is a Creator or Business account before the campaign starts; watch for status_note "not found yet".
4. Refresh your dashboard from /campaigns/{id}/summary (and /metrics for charts) once a day after 04:30 Baku time. 30 requests a minute is plenty for that; page with cursor instead of many small calls.
5. Show null as "not shown by Instagram", never as 0.
6. For sign-in (when enabled): create links server-side, handle every reason, verify notifications, and offer creators a disconnect button that calls DELETE /connections/{id}.