Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SoftwareVerse/userverse/llms.txt

Use this file to discover all available pages before exploring further.

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.
curl --request POST \
  --url http://localhost:8000/company \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "acme@example.com",
    "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
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": "bob@example.com",
    "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=acme@example.com" \
  --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:
ParameterTypeDescription
role_namestringFilter by role name.
first_namestringFilter by user first name.
last_namestringFilter by user last name.
emailstringFilter 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": "bob@example.com",
    "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.

Roles and permissions

Create and manage custom roles within a company.

User management

Register, log in, and manage user profiles.

Build docs developers (and LLMs) love

Get started for freeTalk to us