POST
/
v1
/
tenants
/
add-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-42" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }'

{
  "id": "usr_01HX3ZAB...",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "tenantId": "tnt_01HX3Z8MQW...",
  "status": "invited",
  "createdAt": "2026-04-22T09:13:02.000Z"
}
Creates (or returns) a user. Idempotent on email: if a user with this email already exists, we return the existing record.

​
Body

​
name
string
required
Display name.
​
email
string
required
Valid RFC 5322 email.
​
phone
string
E.164 phone, e.g. +14155552671.
​
metadata
object
Up to 20 key/value pairs, 500 chars each.

​
Returns

​
id
string
User ULID (usr_...).
​
name
string
​
email
string
​
phone
string
​
tenantId
string
​
status
string
invited, active, disabled.
​
createdAt
string
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-42" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }'

{
  "id": "usr_01HX3ZAB...",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "tenantId": "tnt_01HX3Z8MQW...",
  "status": "invited",
  "createdAt": "2026-04-22T09:13:02.000Z"
}

​
Events

Fires tenant.users.invite on successful creation.