Company management

Create a company, look it up, update its details, and manage the users who belong to it.

This guide covers the full company lifecycle: creating a company, fetching and updating its details, and adding or removing members.

All company endpoints require a valid JWT Bearer token. Obtain one by logging in with PATCH /user/login. See the user management guide.

Create a company

1. Create the company

   Send a POST request to /company with the company details. The authenticated user becomes the company’s owner and is automatically added as a member with the Administrator role.

   Two default roles are created for every new company:

   • Administrator — full access to manage users and data.
   • Viewer — read-only access to company data.

   email · string · required

   Company email address. Used as a unique identifier when looking up the company.

   name · string

   Company display name.

   description · string

   Short description of the company.

   industry · string

   Industry the company operates in.

   phone_number · string

   Contact phone number, e.g. 1236547899.

   address · object

   Optional postal address.

   Show address properties

   street · string

   Street address.

   city · string

   City.

   state · string

   State or province abbreviation.

   postal_code · string

   Postal/ZIP code.

   country · string

   Country name.

   curl --request POST \
     --url http://localhost:8000/company \
     --header "Authorization: Bearer <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{
       "email": "[e-mail]",
       "name": "Acme Corp",
       "description": "We make everything.",
       "industry": "Manufacturing",
       "phone_number": "1236547899",
       "address": {
         "street": "123 Main St",
         "city": "Cape Town",
         "state": "CT",
         "postal_code": "8000",
         "country": "South Africa"
       }
     }'
   

   A successful response returns 201 Created with the new company record.

   data · object

   Show properties

   id · integer

   Unique company ID. Save this — you need it for most subsequent operations.

   name · string

   Company display name.

   description · string

   Company description.

   industry · string

   Industry.

   phone_number · string

   Contact phone number.

   email · string

   Company email address.

   address · object

   Postal address object.
2. Add users to the company

   Use POST /company/{company_id}/users to invite existing Userverse users by email. You must specify a role — any role that exists on the company.

   email · string · required

   Email address of the user to add.

   role · string

   Role name to assign. Defaults to Viewer if omitted.

   curl --request POST \
     --url http://localhost:8000/company/42/users \
     --header "Authorization: Bearer <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{
       "email": "[e-mail]",
       "role": "Viewer"
     }'
   

   A successful response returns 201 Created.

Fetch a company

Send a GET request to /company and provide either email or company_id as a query parameter. When both are provided, email takes priority.

You must be a member of the company to retrieve its details.

# Look up by email
curl --request GET \
  --url "http://localhost:8000/company?email=[e-mail]" \
  --header "Authorization: Bearer <your_access_token>"

# Look up by ID
curl --request GET \
  --url "http://localhost:8000/company?company_id=42" \
  --header "Authorization: Bearer <your_access_token>"

A successful response returns 200 OK with the company record.

Update a company

Send a PATCH request to /company/{company_id} with the fields you want to change. All fields are optional.

You must have the Administrator role in the company to update it.

curl --request PATCH \
  --url http://localhost:8000/company/42 \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Acme Corporation",
    "description": "Updated description.",
    "industry": "Technology"
  }'

A successful response returns 200 OK with the updated company record.

Manage company members

List members

Send a GET request to /company/{company_id}/users to retrieve a paginated list of members.

curl --request GET \
  --url "http://localhost:8000/company/42/users" \
  --header "Authorization: Bearer <your_access_token>"

You can filter the results with optional query parameters:

Parameter	Type	Description
role_name	string	Filter by role name.
first_name	string	Filter by user first name.
last_name	string	Filter by user last name.
email	string	Filter by user email address.

Each record in the response includes all standard user fields plus a role_name field indicating the user’s role in this company.

Add a member

Send a POST request to /company/{company_id}/users with the user’s email and the role to assign.

curl --request POST \
  --url http://localhost:8000/company/42/users \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "[e-mail]",
    "role": "Viewer"
  }'

Remove a member

Send a DELETE request to /company/{company_id}/user/{user_id} to remove a specific user.

curl --request DELETE \
  --url http://localhost:8000/company/42/user/7 \
  --header "Authorization: Bearer <your_access_token>"

A successful response returns 200 OK with the removed user’s record.

Related guides

Roles and permissions

Create and manage custom roles within a company.

User management

Register, log in, and manage user profiles.