Profiles

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. Batch delete: send rows with _is_deleted: 1 to tombstone labels in bulk; omit timestamp to delete as of now, or pair it with a past timestamp to record a historical removal (the equivalent of DELETE /v0/profiles/{address}/labels, one row per wallet/label).

post/v0/profiles/labels

Request

  • Base URL: https://api.formo.so
  • URL: https://api.formo.so/v0/profiles/labels
  • Auth: HTTP bearer

Request body

tag_idstring required

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

valuestring

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

chain_idstring

Optional chain identifier the label applies to

timestampstring 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_deleted0 | 1

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.

addressstring required

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

Response

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

successful_rowsinteger required

Number of rows accepted and forwarded to ingest.

quarantined_rowsinteger required

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

Changes

No recorded changes to this operation across all 1 revision of this API.