User & Company Management

Managing users and companies in the MediaViz API — creating accounts, listing users, updating roles, and removing users.

Get Company Creation Token

Request a Company Creation Token

Before creating a company account, you'll need a company creation token from MediaViz. This token authorizes the creation of a new company and is tied to the email address of the intended account owner.

To request a token, contact MediaViz support with the email address you plan to use for the owner account. MediaViz will generate and send a token to that address. Tokens expire after 7 days — if yours expires before you complete setup, simply request a new one.

Create User and Company

Create a New Company and Owner

Use the company creation token from the previous step to register a new company and its owner account in a single call. The token authorizes the operation and is consumed on success — it cannot be reused. The resulting user will have owner access to the company, which grants full administrative access.

Request Sample

const { user_id, company_id } = await mediaviz.users.createUserAndCompany(
  'Jane Smith',
  'jane@example.com',
  's3cur3P@ss',
  null,  // companyId — omit to create a new company
  null,  // profilePicture — optional avatar URL
  null,  // paymentPlanType — optional billing plan
  'Acme Photography',
  {
    inviteToken: 'company_creation_token'
  }
);

import type { UserDisplay } from '@mediaviz/sdk';

const { user_id, company_id }: UserDisplay = await mediaviz.users.createUserAndCompany(
  'Jane Smith',
  'jane@example.com',
  's3cur3P@ss',
  null,  // companyId — omit to create a new company
  null,  // profilePicture — optional avatar URL
  null,  // paymentPlanType — optional billing plan
  'Acme Photography',
  {
    inviteToken: 'company_creation_token'
  }
);

const { user_id, company_id } = await mediaviz.users.createUserAndCompany(
  'Jane Smith',
  'jane@example.com',
  's3cur3P@ss',
  null,  // companyId — omit to create a new company
  null,  // profilePicture — optional avatar URL
  null,  // paymentPlanType — optional billing plan
  'Acme Photography',
  {
    inviteToken: 'company_creation_token'
  }
);

result = mediaviz.users.create_user_and_company(
    'Jane Smith',
    'jane@example.com',
    's3cur3P@ss',
    None,  # companyId — omit to create a new company
    None,  # profilePicture — optional avatar URL
    None,  # paymentPlanType — optional billing plan
    'Acme Photography',
    invite_token='company_creation_token'
)
# result['user_id'], result['company_id']

$result = $mediaviz->users->createUserAndCompany(
  'Jane Smith',
  'jane@example.com',
  's3cur3P@ss',
  null,  // companyId — omit to create a new company
  null,  // profilePicture — optional avatar URL
  null,  // paymentPlanType — optional billing plan
  'Acme Photography',
  [
    'inviteToken' => 'company_creation_token'
  ]
);
// $result['user_id'], $result['company_id']

curl -X POST 'https://api.mediaviz.ai/api/v1/users/new_company/?invite_token=company_creation_token' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "company_id": null,
  "profile_picture": null,
  "payment_plan_type": null,
  "password": "s3cur3P@ss",
  "company_name": "Acme Photography"
}
JSON

Response Sample

{
  "user_id": "usr_01abc123",
  "company_id": "cmp_01xyz456",
  "email": "jane@example.com",
  "message": "Verification email sent."
}

Add User to Existing Company

Add a Standard User

Once a company exists, owners and company admins can add additional users. Provide the target user's name, email, account_type (1 = standard, 2 = company admin), and the company_id returned when the company was created. The new user will receive a verification email and must confirm their address before logging in.

Request Sample

const { user_id } = await mediaviz.users.createUser('John Doe', 'john@example.com', 1, 'cmp_01xyz456');

import type { UserDisplay } from '@mediaviz/sdk';

const { user_id }: UserDisplay = await mediaviz.users.createUser('John Doe', 'john@example.com', 1, 'cmp_01xyz456');

const { user_id } = await mediaviz.users.createUser('John Doe', 'john@example.com', 1, 'cmp_01xyz456');

result = mediaviz.users.create_user('John Doe', 'john@example.com', 1, 'cmp_01xyz456')
# result['user_id']

$result = $mediaviz->users->createUser('John Doe', 'john@example.com', 1, 'cmp_01xyz456');
// $result['user_id']

curl -X POST 'https://api.mediaviz.ai/api/v1/users/' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "John Doe",
  "email": "john@example.com",
  "company_id": "cmp_01xyz456",
  "account_type": 1
}
JSON

Response Sample

{
  "user_id": "usr_02def789",
  "company_id": "cmp_01xyz456",
  "email": "john@example.com",
  "message": "Verification email sent."
}

Get All Company Users

List Users in a Company

Fetch the full list of users belonging to a company. The response includes each user's ID, name, email, and account_type. Use this to audit membership or resolve user IDs before performing updates or deletions.

Request Sample

const { users } = await mediaviz.users.getAllUsersByCompany('cmp_01xyz456');

import type { UserDisplay } from '@mediaviz/sdk';

const { users }: UserDisplay[] = await mediaviz.users.getAllUsersByCompany('cmp_01xyz456');

const { users } = await mediaviz.users.getAllUsersByCompany('cmp_01xyz456');

result = mediaviz.users.get_all_users_by_company('cmp_01xyz456')
# result['users']

$result = $mediaviz->users->getAllUsersByCompany('cmp_01xyz456');
// $result['users']

curl -X GET 'https://api.mediaviz.ai/api/v1/users/company/cmp_01xyz456' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

[
  {
    "user_id": "usr_01abc123",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "account_type": 3,
    "company_id": "cmp_01xyz456"
  },
  {
    "user_id": "usr_02def789",
    "name": "John Doe",
    "email": "john@example.com",
    "account_type": 1,
    "company_id": "cmp_01xyz456"
  }
]

Update User Account Type

Promote a User to Admin

Update a user's profile fields or role. Pass null for any field you don't want to change — only non-null values are applied. account_type accepts 1 (standard) or 2 (company admin); promoting to owner (3) requires contacting MediaViz support. A requesting user can only update users with a lower account type than their own.

Request Sample

const { user } = await mediaviz.users.updateUser(
  'usr_02def789',
  null,  // name — leave null to keep unchanged
  null,  // email — leave null to keep unchanged
  null,  // password — leave null to keep unchanged
  null,  // companyId — leave null to keep unchanged
  2
);

import type { UserDisplay } from '@mediaviz/sdk';

const { user }: UserDisplay = await mediaviz.users.updateUser(
  'usr_02def789',
  null,  // name — leave null to keep unchanged
  null,  // email — leave null to keep unchanged
  null,  // password — leave null to keep unchanged
  null,  // companyId — leave null to keep unchanged
  2
);

const { user } = await mediaviz.users.updateUser(
  'usr_02def789',
  null,  // name — leave null to keep unchanged
  null,  // email — leave null to keep unchanged
  null,  // password — leave null to keep unchanged
  null,  // companyId — leave null to keep unchanged
  2
);

result = mediaviz.users.update_user(
    'usr_02def789',
    None,  # name — leave null to keep unchanged
    None,  # email — leave null to keep unchanged
    None,  # password — leave null to keep unchanged
    None,  # companyId — leave null to keep unchanged
    2
)
# result['user']

$result = $mediaviz->users->updateUser(
  'usr_02def789',
  null,  // name — leave null to keep unchanged
  null,  // email — leave null to keep unchanged
  null,  // password — leave null to keep unchanged
  null,  // companyId — leave null to keep unchanged
  2
);
// $result['user']

curl -X PUT 'https://api.mediaviz.ai/api/v1/users/usr_02def789' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{}
JSON

Response Sample

{
  "user_id": "usr_02def789",
  "name": "John Doe",
  "email": "john@example.com",
  "account_type": 2,
  "company_id": "cmp_01xyz456"
}

Delete User

Remove a Standard User

Permanently removes a user from the platform. The caller must have a higher account type than the user being deleted. If you are deleting the company owner, you must supply a new_company_owner_id query parameter to transfer ownership before deletion proceeds.

Request Sample

const result = await mediaviz.users.deleteUser('usr_02def789');

const result = await mediaviz.users.deleteUser('usr_02def789');

const result = await mediaviz.users.deleteUser('usr_02def789');

result = mediaviz.users.delete_user('usr_02def789')

$result = $mediaviz->users->deleteUser('usr_02def789');

curl -X DELETE 'https://api.mediaviz.ai/api/v1/users/delete/usr_02def789' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyXzAxYWJjMTIzIiwiZXhwIjoxNzQzNjMwMzI5fQ.RwJF-KLLr8K5JgEtIeFiKWELcv-FDLNzMPHJ2St_wAo'

Response Sample

{
  "message": "User deleted successfully."
}