---
title: "Invite user to investor"
method: POST
path: "/v0/investors/{investorId}/users"
tags: ["Users"]
---

# Invite user to investor

`POST /v0/investors/{investorId}/users`

## Request

- Base URL: `https://distributor-api.spiko.io`
- URL: `https://distributor-api.spiko.io/v0/investors/{investorId}/users`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/spiko/apis/spiko-distributor-api/docs/v0/investors/:investorId/users/post.ts> (a function with typed inputs; its response is checked against the schema)

**Invite a new user to join an investor account.**

- If the user already has a Spiko account, they will be added directly to the investor with the specified role.
- If the user does not have a Spiko account, an invitation email will be sent.
- Returns either the created invitation or the added user depending on the scenario.

## Path parameters

- `investorId` string, uuid, required: a Universally Unique Identifier

## Request body

- object
  - `email` string, required: Email address of the user to invite
  - `firstName` string, required: First name of the user to invite
  - `lastName` string, required: Last name of the user to invite
  - `role` 'admin' | 'manager' | 'viewer', required: Role to assign to the invited user: "admin" for full access, "manager" to place and manage orders without administrative access, "viewer" for read-only access.

## Response `200`

Success

- union
  - object
    - `type` 'invitation-sent', required
    - `invitation` object, required
      - `email` string, required
      - `firstName` string, required: a valid name, of max size 255, non empty, without number, some special characters are forbidden
      - `lastName` string, required: a valid name, of max size 255, non empty, without number, some special characters are forbidden
  - object
    - `type` 'user-added', required
    - `user` object, required
      - `userId` string, uuid, required: a Universally Unique Identifier
      - `email` string, required
      - `firstName` string, required: a valid name, of max size 255, non empty, without number, some special characters are forbidden
      - `lastName` string, required: a valid name, of max size 255, non empty, without number, some special characters are forbidden

## Other responses

- `400`: The request did not match the expected schema
- `401`: Authentication failed. Two bodies are possible: the schema below when the API rejects the credentials, and `{ "error": { "code", "status", "request", "message" } }` when the API gateway rejects them first. Only the former carries a `_tag`.
- `403`: Forbidden
- `404`: NotFound
- `409`: Account already exists | Invitation already exists
- `503`: The investor is undergoing a scheduled upgrade, access is temporarily paused to ensure data safety.

---

[API](https://skmtc.dev/spiko/apis/spiko-distributor-api.md) - [All operations](https://skmtc.dev/spiko/apis/spiko-distributor-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spiko/apis/spiko-distributor-api/revisions/dd06889f4c79?raw)