Chorvia
← Back to SupportOrganization Management

Manage Organization Users via API

Organization administrators can add and manage members programmatically using the Chorvia API — ideal for syncing from your HR system, an internal tool, or an onboarding script.

1. Generate an API Key

API access is available to organization administrators only. To create a key:

  1. Log in to your organization admin account
  2. Go to Settings → API Access (or visit /org/api-key)
  3. Click Generate API Key
  4. Copy the key immediately — it is shown only once and stored only as a hash

Keep it secret. Anyone with your key can manage your organization's members. If a key is exposed, generate a new one (which revokes the old key) or delete it from the same page.

2. Authentication

Send your key with every request using either header:

Authorization: Bearer chv_your_api_key
X-API-Key: chv_your_api_key

3. Check Your Organization & Seats

GET /api/org/me returns your organization's identity and current seat usage. Use it to confirm your key and check remaining capacity before adding members.

curl https://chorvia.com/api/org/me \
  -H "Authorization: Bearer chv_your_api_key"

Example response:

{
  "organizationId": "clx123...",
  "name": "Acme Inc",
  "subscriptionStatus": "active",
  "expiresAt": null,
  "seats": { "limit": 50, "used": 12, "remaining": 38 }
}

4. Add a Single Member

POST /api/org/create-member adds one member to your organization. You do not need to pass your organization id — it is taken from your API key. If the email already belongs to an existing Chorvia user, that user is added to your organization; otherwise a new account is created with the details you provide.

curl -X POST https://chorvia.com/api/org/create-member \
  -H "Authorization: Bearer chv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "password": "a-temporary-password",
    "gender": "female",
    "dateOfBirth": "1990-05-14"
  }'

Fields:

  • email (required)
  • firstName, lastName, password, gender, dateOfBirth — required when creating a brand-new member; not needed when adding an email that already has a Chorvia account
  • organizationId (optional) — defaults to your organization. If provided it must match your own organization, or the request is rejected

5. Invite Many Members at Once

POST /api/org/bulk-import/create creates invitations for up to 100 people in one call. Each person receives an email invitation (valid for 7 days) to set their own password.

curl -X POST https://chorvia.com/api/org/bulk-import/create \
  -H "Authorization: Bearer chv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "users": [
    { "email": "a@acme.com", "firstName": "Ann", "lastName": "Lee", "gender": "female", "age": 34 },
    { "email": "b@acme.com", "firstName": "Bo", "lastName": "Ng", "gender": "male", "age": 41 }
  ] }'

Member Limits & Billing

  • If your organization has a member limit, API calls that would exceed it are rejected with a 403. Check remaining seats with GET /api/org/me.
  • Members added via the API are covered by your organization's subscription automatically — they are billing-exempt and never billed individually.

Response Codes

  • 200 / 201 — success
  • 401 — missing or invalid API key
  • 403 — member limit reached, or an organizationId that isn't yours
  • 409 — the user is already a member of an organization
  • 400 — missing or invalid fields

Prefer a no-code option? You can add members individually or via CSV/Excel from your dashboard — see Managing Team Members and Bulk Import Members.

Related Articles