Batch add or update user labels

Upsert up to 100 labels across many wallets in one request; each item carries its own address. Modelled on the events ingest API: rows with an invalid address (ENS names are NOT resolved here; pass a literal EVM 0x... or Solana address) are quarantined (skipped and reported in the response) rather than failing the whole batch. A request where every row is invalid returns 400. Requires profiles:write scope.

POST /v0/profiles/labels

cURL

batchLabels

curl --request POST \
  --url https://api.formo.so/v0/profiles/labels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "tag_id": "vip",
    "value": "tier-1"
  },
  {
    "address": "EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV",
    "tag_id": "airdrop_eligible",
    "chain_id": "1"
  }
]
'

200

Example

{
  "successful_rows": 123,
  "quarantined_rows": 123,
  "errors": [
    {
      "index": 123,
      "reason": "<string>",
      "address": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API Keys.

Body

application/json

Required array length: 1 - 100 elements

tag_id · string · required

Label identifier (lowercased on write). e.g. vip, airdrop_eligible, coinbase.verified_account

address · string · required

Wallet address the label applies to. Literal EVM (0x...) or Solana address only; ENS names are not resolved in batch requests.

value · string

Optional label value (e.g. tier name, country code)

chain_id · string

Optional chain identifier the label applies to

timestamp · string<date-time>

Optional ISO-8601 event-time for the label. When provided, the label is recorded at this time instead of the server's current time; used to backfill historical values (e.g. an open_interest reading from a past week) so label-based retention can evaluate them at the right point in time. Must not be in the future. Defaults to server time when omitted.

_is_deleted · enum<integer>

Optional tombstone flag for backfilled removals. 1 records the row as a soft-delete (label removed) instead of a live value; pair it with a past timestamp to express "label removed at past time T" so point-in-time retention drops the wallet from that week. The future-timestamp guard still applies. Defaults to 0 (a live label) when omitted.

Available options: 0, 1

Response

200

application/json

Batch processed. Returns counts of forwarded vs quarantined rows, with a per-row errors entry for each quarantined row.

Acknowledgement for a batch write. successful_rows counts rows accepted and forwarded to ingest after a 2xx (ingestion is async/eventually-consistent; there is no follow-up read). quarantined_rows counts rows skipped for an invalid address or no valid keys; errors (omitted when nothing was quarantined) maps each skipped row back to its request index.

successful_rows · integer · required

Number of rows accepted and forwarded to ingest.

quarantined_rows · integer · required

Number of rows skipped (invalid address, or no valid keys).

errors · object[]

One entry per quarantined row. Omitted when quarantined_rows is 0.

Show child attributes