Every user who goes through KYC, signs an escrow, or uploads source-of-funds docs must first exist as a Geldstuck user. Most integrations push users in two flows:
  1. Live sync - when a user signs up in your app, call add-user to mirror them.
  2. Nightly reconciliation - a batch job runs add-user-bulk to catch anything the live sync missed.

​
Live sync - single user

curl https://api.geldstuck.com/v1/tenants/add-user \
  -H "x-api-key: $GELDSTUCK_PUBLIC_KEY" \
  -H "x-api-secret: $GELDSTUCK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: user-sync-$CRM_ID" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }'
Use your internal user ID as the idempotency key suffix. Retries are then safe: if the sync job restarts, we’ll return the existing user instead of erroring.

​
Bulk sync - up to 10,000 users

For CRM snapshots, onboarding migrations, or reconciliation jobs, use the bulk endpoint. 
curl https://api.geldstuck.com/v1/tenants/add-user-bulk \
  -H "x-api-key: $GELDSTUCK_PUBLIC_KEY" \
  -H "x-api-secret: $GELDSTUCK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "Alice", "email": "alice@example.com" },
    { "name": "Bob",   "email": "bob@example.com"   }
  ]'
Response: 
{
  "created": 1842,
  "skipped": 158,
  "failed": [
    { "index": 203, "email": "invalid", "error": "email_invalid" }
  ]
}
skipped entries are users whose email already exists for this tenant - this is a no-op success. Inspect failed to see which rows couldn’t be ingested.

​
Nightly CRM sync pattern

1

Export delta

Grab users created or updated in the last 24 hours from your CRM.
2

De-duplicate by email

Guarantees the bulk endpoint’s skipped count is meaningful.
3

Chunk to 1,000

We accept up to 10,000 per call - 1,000 gives smaller retry units.
4

Retry on 429

Honor Retry-After. Use the rate-limit helper.
5

Log `failed[]` to your ops channel

So someone can fix invalid emails before the next run.

​
Event on success

Each added user fires a tenant.users.invite webhook. Subscribe if you want to drive downstream automation (welcome email, Slack alert, analytics event).