Accounts API Reference

Manage account creation, user management, and account-level operations.

Base Path: /api/accounts

Overview

The Accounts API provides endpoints for managing accounts, users within accounts, and account settings. Supports user invitations, role management, and account profile management.

Key Operations

API Endpoints

POST /api/accounts/signup

Signup New Account

Allows new user to signup and create a new account.

Authentication

None

Request Body

{
  "email": "user@example.com",
  "password": "secure_password_123",
  "firstName": "John",
  "lastName": "Doe",
  "accountName": "Acme Corporation",
  "country": "US"
}

Response

{
  "id": 1,
  "email": "user@example.com",
  "accountId": 10,
  "accountName": "Acme Corporation",
  "createdAt": "2026-06-02T10:30:00Z"
}
POST /api/accounts

Create Account

Creates a new account (authenticated users).

Authentication

Bearer Token

Request Body

{
  "name": "Enterprise Account",
  "description": "Main enterprise account",
  "primaryContact": "contact@enterprise.com"
}

Response

{
  "id": 2,
  "name": "Enterprise Account",
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/accounts

List Accounts

Gets all accounts with filters and pagination.

Authentication

Bearer Token

Query Parameters

Parameter Type Description
$filter string OData filter (e.g., name eq 'Acme')
$orderby string Sort order (e.g., createdAt desc)
$skip integer Number of records to skip
$top integer Number of records to return

Response

{
  "value": [
    {
      "id": 1,
      "name": "Acme Corporation",
      "createdAt": "2026-06-02T10:30:00Z"
    }
  ],
  "count": 1
}
GET /api/accounts/{id}

Get Account by ID

Gets account details by ID.

Authentication

Bearer Token

Path Parameters

Parameter Type Description
id integer Account ID

Response

{
  "id": 1,
  "name": "Acme Corporation",
  "description": "Main account",
  "status": "active",
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/accounts/{name}

Get Account by Name

Gets account details by name.

Authentication

Bearer Token

Path Parameters

Parameter Type Description
name string Account name

Response

{
  "id": 1,
  "name": "Acme Corporation",
  "description": "Main account",
  "createdAt": "2026-06-02T10:30:00Z"
}
PUT /api/accounts/{id}

Update Account

Updates account details.

Authentication

Bearer Token (manage role required)

Path Parameters

Parameter Type
id integer

Request Body

{
  "name": "Updated Account Name",
  "description": "Updated description",
  "status": "active"
}

Response

{
  "id": 1,
  "name": "Updated Account Name",
  "updatedAt": "2026-06-02T11:00:00Z"
}
POST /api/accounts/{id}/users

Add New User to Account

Adds new user to account with specified roles.

Authentication

Bearer Token (manage role required)

Request Body

{
  "email": "newuser@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "roles": ["user", "viewer"]
}

Response

{
  "id": 100,
  "email": "newuser@example.com",
  "accountId": 1,
  "roles": ["user", "viewer"],
  "createdAt": "2026-06-02T10:30:00Z"
}
POST /api/accounts/{id}/users/{userId}

Add Existing User to Account

Adds existing user (by ID) to account.

Authentication

Bearer Token (manage role required)

Request Body

{
  "roles": ["user", "admin"]
}

Response

{
  "success": true,
  "message": "User added to account"
}
PUT /api/accounts/{id}/users/{userId}

Update User Roles

Updates account user roles.

Authentication

Bearer Token (manage role required)

Request Body

{
  "roles": ["admin", "user"],
  "status": "active"
}

Response

{
  "success": true,
  "message": "User roles updated"
}
PUT /api/accounts/{id}/users/{userId}/invite

Resend Invitation Email

Re-sends email invitation to user.

Authentication

Bearer Token (account manage role required)

Response

{
  "success": true,
  "message": "Invitation email resent"
}
DELETE /api/accounts/{id}/users/{userId}

Remove User from Account

Removes user from account.

Authentication

Bearer Token (manage role required)

Response

{
  "success": true,
  "message": "User removed from account"
}
DELETE /api/accounts/{accountId}

Delete Account

Deletes account (account owner required).

Authentication

Bearer Token (manage role + account owner required)

Response

{
  "success": true,
  "message": "Account deleted"
}

Error Responses

Code HTTP Status Description
ACCOUNT_NOT_FOUND 404 Account does not exist
ACCOUNT_ALREADY_EXISTS 409 Account name already exists
UNAUTHORIZED 403 User does not have required role
USER_ALREADY_IN_ACCOUNT 409 User already belongs to account

Quick Links

← Back to Overview ← Authentication API Orders API → Try the Playground