Insights

Update the insight notes of fans in bulk

PATCH/v1/accounts/{account_id}/insights

Sets the free-text CRM note of up to 50 fans of this account in a single call. Each item carries the concurrency token from a prior GET of that note, in its etag field (the If-Match header is not read here). Items are independent: each one is written or refused on its own, and a refused item never cancels the others.

The response lists every item in the order sent, with its status: updated (written, or already identical; etag is the new token), precondition_failed (the note changed since you read it, nothing written; current_etag is the fresh token, retry with it or read the note again), unknown_fan (the account has no relation with this fan yet, nothing created), unavailable (the write of this note failed: retry this item later with the same etag, and read the note again if the retry reports precondition_failed). The call answers 200 even when no item is written.

Retrying a call whose response was lost reports precondition_failed on the items it had already written: read those notes again.

Required scopewrite:insights

Rate limit5 requests per minute

curl -X PATCH 'https://api.fansquare.so/v1/accounts/c851d9d6-b90b-4958-aed2-2fdaa2fe21a3/insights' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "fan_id": "0197a3c2-1111-7222-8333-444455556666",
      "note": "Prefers short replies. Birthday on March 3.",
      "etag": "8c41d07e"
    },
    {
      "fan_id": "0197a3c2-2222-7222-8333-444455556666",
      "note": "Asked for the Lisbon pictures.",
      "etag": "3f9a2b10"
    },
    {
      "fan_id": "0197a3c2-3333-7222-8333-444455556666",
      "note": null,
      "etag": "c07d55e2"
    }
  ]
}'

{
  "updated": 1,
  "results": [
    {
      "fan_id": "0197a3c2-1111-7222-8333-444455556666",
      "status": "updated",
      "etag": "a51e9c47"
    },
    {
      "fan_id": "0197a3c2-2222-7222-8333-444455556666",
      "status": "precondition_failed",
      "current_etag": "e2b84f03"
    },
    {
      "fan_id": "0197a3c2-3333-7222-8333-444455556666",
      "status": "unknown_fan"
    }
  ]
}

Parameters

Headers

Fansquare-Versionstringrequired
API version to pin. Accepts the mineral name or the release date of a version.

Path

account_idstringrequired
MYM account id (account.external_id in GET /v1/creators).
min length 1

Body

application/json

itemsarray of objectsrequired
The notes to write, 1 to 50 per call, each fan once.
min items 1max items 50
fan_idstringrequired
MYM fan id.
format uuid
notestring | null
New note text, or null to clear it. Omit to leave the note unchanged. Plain text, stored as sent. Use \n for a line break and \n\n for a blank line between paragraphs. Each escape counts as one character against the 2000 limit.
max length 2000
etagstringrequired
Concurrency token of this note, from a prior GET or PATCH (quoted or not).

Response

OK, application/json

updatedintegerrequired
Number of items with the status updated.
resultsarray of objectsrequired
One entry per item, in the order sent.
fan_idstringrequired
MYM fan id, as sent.
statusstringrequired
Outcome of this item: updated, precondition_failed, unknown_fan or unavailable.
Valuesupdatedprecondition_failedunknown_fanunavailable
etagstring
New concurrency token of the note. Present when status is updated.
current_etagstring
Current concurrency token of the note. Present when status is precondition_failed: retry with it, or read the note again.

curl -X PATCH 'https://api.fansquare.so/v1/accounts/c851d9d6-b90b-4958-aed2-2fdaa2fe21a3/insights' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Fansquare-Version: Amethyste" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "fan_id": "0197a3c2-1111-7222-8333-444455556666",
      "note": "Prefers short replies. Birthday on March 3.",
      "etag": "8c41d07e"
    },
    {
      "fan_id": "0197a3c2-2222-7222-8333-444455556666",
      "note": "Asked for the Lisbon pictures.",
      "etag": "3f9a2b10"
    },
    {
      "fan_id": "0197a3c2-3333-7222-8333-444455556666",
      "note": null,
      "etag": "c07d55e2"
    }
  ]
}'

{
  "updated": 1,
  "results": [
    {
      "fan_id": "0197a3c2-1111-7222-8333-444455556666",
      "status": "updated",
      "etag": "a51e9c47"
    },
    {
      "fan_id": "0197a3c2-2222-7222-8333-444455556666",
      "status": "precondition_failed",
      "current_etag": "e2b84f03"
    },
    {
      "fan_id": "0197a3c2-3333-7222-8333-444455556666",
      "status": "unknown_fan"
    }
  ]
}