Bulk upsert users

curl --request POST \
  --url https://api.example.com/api/v1/users/bulk \
  --header 'Content-Type: application/json' \
  --data '
{
  "users": [
    {}
  ]
}
'

import requests

url = "https://api.example.com/api/v1/users/bulk"

payload = { "users": [{}] }
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({users: [{}]})
};

fetch('https://api.example.com/api/v1/users/bulk', 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.example.com/api/v1/users/bulk",
  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([
    'users' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "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.example.com/api/v1/users/bulk"

	payload := strings.NewReader("{\n  \"users\": [\n    {}\n  ]\n}")

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

	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.example.com/api/v1/users/bulk")
  .header("Content-Type", "application/json")
  .body("{\n  \"users\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/users/bulk")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"users\": [\n    {}\n  ]\n}"

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

{
  "data.accepted": 123,
  "data.rejected": 123,
  "data.errors": [
    {}
  ],
  "meta.received": 123
}

POST

api

users

bulk

Bulk upsert users

curl --request POST \
  --url https://api.example.com/api/v1/users/bulk \
  --header 'Content-Type: application/json' \
  --data '
{
  "users": [
    {}
  ]
}
'

import requests

url = "https://api.example.com/api/v1/users/bulk"

payload = { "users": [{}] }
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({users: [{}]})
};

fetch('https://api.example.com/api/v1/users/bulk', 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.example.com/api/v1/users/bulk",
  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([
    'users' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "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.example.com/api/v1/users/bulk"

	payload := strings.NewReader("{\n  \"users\": [\n    {}\n  ]\n}")

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

	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.example.com/api/v1/users/bulk")
  .header("Content-Type", "application/json")
  .body("{\n  \"users\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/users/bulk")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"users\": [\n    {}\n  ]\n}"

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

{
  "data.accepted": 123,
  "data.rejected": 123,
  "data.errors": [
    {}
  ],
  "meta.received": 123
}

The backfill counterpart to single-record upsert. Send up to 1,000 user records in one POST; per-record validation errors are surfaced in the response, the rest are queued.

SDK is the recommended path. vf.users.identifyBulk() wraps this endpoint with strong typing and pairs cleanly with the exported chunk() helper for backfills larger than 1,000 records.

Request

POST /api/v1/users/bulk HTTP/1.1
Host: api.vibefollow.com
Authorization: Bearer sk_live_••••
Content-Type: application/json

Body

{
  "users": [
    {
      "external_user_id": "usr_42",
      "email": "jane@acme.io",
      "traits": { "name": "Jane Doe", "plan": "pro" }
    },
    {
      "external_user_id": "usr_43",
      "email": "noel@acme.io",
      "traits": { "name": "Noel Carter", "plan": "trial" }
    }
  ]
}

users

User[]

required

Array of user records. Each entry has the same shape as the single-record body. Minimum 1, maximum 1,000 records.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "accepted": 487,
    "rejected": 13,
    "errors": [
      { "index": 12, "code": "validation", "message": "Invalid email", "field": "email" },
      { "index": 47, "code": "validation", "message": "external_user_id must be at least 1 character" }
    ]
  },
  "meta": { "received": 500 }
}

data.accepted

number

Records that passed validation and were enqueued.

data.rejected

number

Records that failed validation. Each has a corresponding entry in data.errors.

data.errors

object[]

Per-record validation failures. index correlates back to the position in the input users array — the record at that position was not enqueued.

Show Error object

index

number

required

0-based position in the request users array.

code

string

required

Machine-readable error code (e.g. "validation").

message

string

required

Human-readable detail.

field

string

Field path inside the record that failed, when applicable (e.g. "email").

meta.received

number

Total records in the request payload. accepted + rejected === meta.received is an invariant — every record is accounted for.

Idempotency is automatic. The (project_id, external_user_id) uniqueness constraint on tracked_users means re-sending the same record with the same external_user_id is treated as an update, not a duplicate. Any chunk that returns 429 or 5xx is safe to retry.

Examples

import { VibeFollow, chunk } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });

// Backfill any size by pairing with chunk()
for (const slice of chunk(allUsers, 1000)) {
  const result = await vf.users.identifyBulk(slice);
  if (result.data.errors.length > 0) {
    console.warn('skipped', result.data.errors);
  }
}

curl https://api.vibefollow.com/api/v1/users/bulk \
  -X POST \
  -H "Authorization: Bearer $VIBEFOLLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      { "external_user_id": "usr_42", "email": "jane@acme.io" },
      { "external_user_id": "usr_43", "email": "noel@acme.io" }
    ]
  }'

Common errors

401 auth_required

Missing or malformed Authorization header.

400 validation_failed

The envelope failed validation — users is missing, not an array, empty, or contains more than 1,000 records. Per-record validation failures do not trigger 400; they surface in data.errors.

429 rate_limited

Standard per-project rate limit; honor Retry-After.

429 backfill_queue_full

The project’s ingest queue is saturated (50,000+ jobs waiting or delayed). Back off, drain, then resume in smaller chunks.

5xx server_error

Retry the same chunk — the upsert is idempotent via the unique (project_id, external_user_id) constraint.

Sizing

Max records per request

1,000

Recommended chunk size

1,000

Backfill queue cap

50,000 waiting jobs / project

Upsert user Track event

​Request

​Body

​Response

​Examples

​Common errors

​Sizing

Max records per request

Recommended chunk size

Backfill queue cap

Request

Body

Response

Examples

Common errors

Sizing