Batch Update Properties

Batch update user properties

curl --request POST \
  --url https://api.formo.so/v0/profiles/properties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "display_name": "alice.eth",
    "email": "alice@example.com"
  },
  {
    "address": "EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV",
    "twitter": "bob"
  }
]
'

import requests

url = "https://api.formo.so/v0/profiles/properties"

payload = [
    {
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "display_name": "alice.eth",
        "email": "alice@example.com"
    },
    {
        "address": "EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV",
        "twitter": "bob"
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
      display_name: 'alice.eth',
      email: 'alice@example.com'
    },
    {address: 'EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV', twitter: 'bob'}
  ])
};

fetch('https://api.formo.so/v0/profiles/properties', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.formo.so/v0/profiles/properties",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'address' => '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
        'display_name' => 'alice.eth',
        'email' => 'alice@example.com'
    ],
    [
        'address' => 'EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV',
        'twitter' => 'bob'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.formo.so/v0/profiles/properties"

	payload := strings.NewReader("[\n  {\n    \"address\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\",\n    \"display_name\": \"alice.eth\",\n    \"email\": \"alice@example.com\"\n  },\n  {\n    \"address\": \"EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV\",\n    \"twitter\": \"bob\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.formo.so/v0/profiles/properties")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"address\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\",\n    \"display_name\": \"alice.eth\",\n    \"email\": \"alice@example.com\"\n  },\n  {\n    \"address\": \"EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV\",\n    \"twitter\": \"bob\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.formo.so/v0/profiles/properties")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"address\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\",\n    \"display_name\": \"alice.eth\",\n    \"email\": \"alice@example.com\"\n  },\n  {\n    \"address\": \"EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV\",\n    \"twitter\": \"bob\"\n  }\n]"

response = http.request(request)
puts response.read_body

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

POST

profiles

properties

Batch update user properties

curl --request POST \
  --url https://api.formo.so/v0/profiles/properties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "display_name": "alice.eth",
    "email": "alice@example.com"
  },
  {
    "address": "EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV",
    "twitter": "bob"
  }
]
'

import requests

url = "https://api.formo.so/v0/profiles/properties"

payload = [
    {
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "display_name": "alice.eth",
        "email": "alice@example.com"
    },
    {
        "address": "EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV",
        "twitter": "bob"
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
      display_name: 'alice.eth',
      email: 'alice@example.com'
    },
    {address: 'EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV', twitter: 'bob'}
  ])
};

fetch('https://api.formo.so/v0/profiles/properties', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.formo.so/v0/profiles/properties",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'address' => '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
        'display_name' => 'alice.eth',
        'email' => 'alice@example.com'
    ],
    [
        'address' => 'EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV',
        'twitter' => 'bob'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.formo.so/v0/profiles/properties"

	payload := strings.NewReader("[\n  {\n    \"address\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\",\n    \"display_name\": \"alice.eth\",\n    \"email\": \"alice@example.com\"\n  },\n  {\n    \"address\": \"EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV\",\n    \"twitter\": \"bob\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.formo.so/v0/profiles/properties")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"address\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\",\n    \"display_name\": \"alice.eth\",\n    \"email\": \"alice@example.com\"\n  },\n  {\n    \"address\": \"EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV\",\n    \"twitter\": \"bob\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.formo.so/v0/profiles/properties")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"address\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\",\n    \"display_name\": \"alice.eth\",\n    \"email\": \"alice@example.com\"\n  },\n  {\n    \"address\": \"EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV\",\n    \"twitter\": \"bob\"\n  }\n]"

response = http.request(request)
puts response.read_body

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

Deleting properties in a batch

A null value deletes (unsets) that property, exactly as on the single-wallet endpoint. Set and unset can mix freely within and across rows:

curl -sS -X POST \
  -H "Authorization: Bearer <your_workspace_api_key>" \
  -H "Content-Type: application/json" \
  -d '[
    { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "display_name": "alice.eth", "email": null },
    { "address": "EPjFWaYbrgqCC2Qbg4EV4FjUreEMKwMn1zNbiboXXKV", "twitter": null }
  ]' \
  "https://api.formo.so/v0/profiles/properties"

user_id cannot be unset (it participates in identity stitching); a row with "user_id": null fails request validation with 400 BAD_REQUEST. The literal string _is_deleted is a reserved internal value and is rejected wherever a property value is accepted.

Authorizations

Authorization

string

header

required

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

Body

application/json

Required array length: 1 - 100 elements

address

string

required

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

user_id

string

display_name

string | null

farcaster

string | null

discord

string | null

twitter

string | null

instagram

string | null

website

string | null

github

string | null

facebook

string | null

tiktok

string | null

youtube

string | null

avatar

string | null

description

string | null

location

string | null

ens

string | null

lens

string | null

basenames

string | null

linea

string | null

Response

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

API Documentation

Events API

Profiles API

Query API

Alerts API

Charts API

Contracts API

Segments API

Batch Update Properties

Deleting properties in a batch

Authorizations

Body

Response

​Deleting properties in a batch

Authorizations

Body

Response

Deleting properties in a batch