T
testing
API Reference: Users & Organizations Managing Customer Accounts via API

This guide explains how to use the API to manage customer profiles, organizations, and user invitations. Whether you are building an automated onboarding flow or handling administrative reporting, these endpoints provide full control over your customer accounts.

Authentication Required

All endpoints in this guide require a valid authentication token. Ensure you include your Bearer token in the Authorization header of your requests.

The Onboarding Workflow

When a new customer signs up, you typically need to provision an organization, customize it, and mark their setup as complete. The API provides a streamlined sequence for this.

sequenceDiagram
    participant Client
    participant API
    Client->>API: POST /v1/organization
    API-->>Client: Returns {organization_id}
    Client->>API: POST /v1/organization/{organization_id}/upload-logo
    Client->>API: POST /v1/organization/{organization_id}/complete-onboarding
    API-->>Client: 200 OK (Status: Active)
  1. 1

    Create the organization

    Start by creating a new organization workspace. Make a POST request to /v1/organization with the customer's initial details. The response will include the new organization_id.

  2. 2

    Upload branding assets

    Personalize the customer's workspace by uploading their company logo using POST /v1/organization/{organization_id}/upload-logo.

  3. 3

    Complete onboarding

    Once all initial settings are configured, finalize the process by calling POST /v1/organization/{organization_id}/complete-onboarding. This activates the organization and triggers any necessary background provisioning.

Managing Organizations

You can manage the lifecycle and settings of organizations using standard RESTful endpoints.

ActionMethodEndpointDescription
List My OrganizationsGET/v1/organizationReturns all organizations the current authenticated user belongs to.
Get DetailsGET/v1/organization/{organization_id}Retrieves the configuration and status of a specific organization.
Update SettingsPUT/v1/organization/{organization_id}Modifies the organization's profile or settings.
DeleteDELETE/v1/organization/{organization_id}Permanently removes the organization and its associated data.


Deleting an organization is irreversible. Ensure you prompt the user for confirmation before invoking the DELETE endpoint.

Users and Invitations

Organizations are collaborative. Use these endpoints to manage the users within an organization and handle the invitation lifecycle.

ActionMethodEndpoint
List UsersGET/v1/organization/{organization_id}/user
List Pending InvitesGET/v1/invitations
Accept InvitePOST/v1/invitations/{invitation_id}/accept
Remove UserDELETE/v1/organization/{organization_id}/user/{user_id}

When a user logs in, you can check /v1/invitations to display any pending requests they have to join other organizations, allowing them to accept via the UI.

Administration & Reporting

If you are building an internal dashboard or require system-level access, use the administrative endpoints. These require elevated privileges and allow you to view data across all organizations.

ActionMethodEndpoint
List All OrganizationsGET/v1/organization/all
List All CustomersGET/v1/admin/customers
Customer OverviewGET/v1/admin/customers/{organization_id}
Export to CSVGET/v1/admin/customers/export

Server-to-Server (S2S) Actions: For internal billing or feature flagging, you can toggle active subscriptions directly via the internal endpoint: POST /internal/subscriptions/{organization_id}/toggle-active.

Frequently Asked Questions

How do I export my customer list?

Administrators can generate a CSV of all customer data by making a GET request to /v1/admin/customers/export. This is useful for importing into CRMs or external reporting tools.

What happens when onboarding is completed?

Calling the complete-onboarding endpoint transitions the organization's status from pending to active. Depending on your system configuration, this may also trigger welcome emails or begin billing cycles.

Can a user belong to multiple organizations?

Yes. A single authenticated user can be invited to and accept invitations for multiple organizations. The GET /v1/organization endpoint will return an array of all organizations they currently have access to.