Add or update user labels

Upsert one or more labels for a wallet. Accepts either a single label object or an array of labels. Labels with the same tag_id (and chain_id, if provided) are overwritten. Requires profiles:write scope.

POST /v0/profiles/{address}/labels

cURL

singleLabel

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

200

Example

{ "address": "<string>", "tag_id": "<string>", "value": "<string>", "chain_id": "<string>", "source": "<string>", "timestamp": "2023-11-07T05:31:56Z" }

Authorizations

Authorization · string · header · required

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

Headers

Idempotency-Key · string

Optional unique value (e.g. a UUID v4) that lets you safely retry POST/PUT/PATCH/DELETE requests. The first request runs normally; subsequent requests with the same key replay the stored response (status + body) for 24 hours, so retries can never double-create or double-charge. Two concurrent requests with the same key return 409 IDEMPOTENCY_IN_PROGRESS. Generate a fresh key per logical operation.

Maximum string length: 255

Path Parameters

address · string · required

Wallet address. Accepts an EVM (0x...) or Solana address, or an ENS name (e.g. vitalik.eth) which is resolved to an address.

Body

application/json

object

object[]

tag_id · string · required

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

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

Labels upserted. Single label in → bare UserLabel; array in → array of UserLabel. Echoes the normalised entries (lowercased tag_id; the caller-supplied timestamp when present, otherwise the server write time).

object

object[]

Canonical user-label resource. Echoed back from upsert calls so callers can cache the normalised entry without a follow-up read.

address · string · required

Wallet address the label applies to

tag_id · string · required

Label identifier (lowercased + trimmed on write)

value · string · required

Label value, empty string when omitted

chain_id · string · required

Chain identifier, empty string when omitted

source · string · required

Origin of the label (e.g. 'import')

timestamp · string<date-time> · required

Event-time of the label: the caller-supplied timestamp when provided (retrospective backfill), otherwise the server's write time.