Genie API Reference Guide

Table of Contents

• 1. Application Overview
• 2. API Overview
• 3. Base URL and Environments
• 3.1 Calling through the web application
• 3.2 Cross-origin requests
• 4. Authentication and Session
• 4.1 Session model
• 4.2 CSRF protection
• 4.3 Sign-in flow
• 4.4 Authorization model
• 5. Common API Conventions
• 5.1 Request headers
• 5.2 Response envelopes
• 5.3 Status codes
• 5.4 The shared company and period selection
• 5.5 Filtering, sorting and pagination
• 5.6 Dates, times and periods
• 5.7 Request size limits
• 5.8 Numeric precision
• 5.9 Encrypted identifiers
• 5.10 File uploads and downloads
• 5.11 Error handling and diagnostics
• 6. How to Read the Endpoint Reference
• 7. Module Directory
• 8. Authentication, Session & Core
• 8.1 How authentication works end to end
• 8.2 Session and CSRF cookies
• 8.3 Health & CSRF
• 8.4 Credential Login & Password Recovery
• 8.5 Two-Factor Verification
• 8.6 Sign in with Google
• 8.7 Logout
• 8.8 Session State & Company Selection
• 8.9 Notifications
• 8.10 Company & Group Tree
• 8.11 Role Map Diagnostics
• 9. Admin
• 9.1 Company
• 9.2 Company Groups
• 9.3 Users
• 9.4 Reporting Groups
• 9.5 Logs (Task Audit / Activity Log)
• 9.6 QBO Sync Status
• 10. Client Success
• 10.1 Client Info
• 10.1.1 Company Info Configuration
• 10.1.2 Client Contacts Configuration
• 10.1.3 Company Data
• 10.1.4 Template Download and Import
• 10.2 Configure
• 10.2.1 Service Roles
• 10.2.2 Client Info Start Date
• 10.2.3 Service Team
• 10.2.4 Client Tags
• 11. Tasks & Time
• 11.1 Tasks
• 11.2 Task Board
• 11.3 Calendar
• 11.4 Projects
• 11.5 Task & Time Templates
• 11.6 Configure
• 11.7 Reports (Reports Builder)
• 11.8 Invoicing
• 11.8.1 Create Invoice
• 11.8.2 Configure
• 11.8.3 Post to GL
• 11.8.4 Timesheet Details
• 11.8.5 Invoicing Audit Log
• 11.9 Timesheet
• 11.9.1 Timesheet Conventions
• 11.9.2 Timesheet Entry
• 11.9.3 Timesheet Reports
• 11.9.4 Timesheet Configure
• 11.9.5 Timesheet Audit Log
• 12. Monthly Close
• 12.1 Close Status
• 12.2 Close Details
• 12.3 Open Comments
• 12.4 GL Validation
• 12.5 Firm Configuration
• 12.6 Review Assignments
• 12.7 QuickBooks Close Dates
• 12.8 Company Group Tree
• 13. Comments Center
• 13.1 Task Comments
• 13.2 Invoicing Comments
• 14. Report Center
• 14.1 Report List
• 14.2 Report Preview
• 14.3 Report Writer
• 14.4 Report Packages
• 14.5 Configure
• 15. Feedback Center
• 15.1 Suggestions
• 15.2 Support & Issues
• 16. Integrations
• 16.1 Google Integration (Drive / Sheets OAuth)
• 16.2 QuickBooks Online Integration
• 16.3 Integration Notes
• 16.3.1 Google OAuth (Drive / Sheets)
• 16.3.2 QuickBooks Online OAuth and connection
• 16.3.3 File attachment storage
• 16.3.4 Outbound e-mail
• 17. Deployment & Operational Considerations
• 18. Appendix A — Complete Endpoint Index
• A.1 Authentication, Session & Core
• A.2 Admin
• A.3 Client Success
• A.4 Tasks & Time
• A.5 Monthly Close
• A.6 Comments Center
• A.7 Report Center
• A.8 Feedback Center
• A.9 Integrations
• 19. Appendix B — Environment Variables
• B.1 Application
• B.2 Database
• B.3 Mail (SMTP)
• B.4 QuickBooks Online
• B.5 Google (Drive / Sheets)
• B.6 Object storage
• B.7 Web application
• 20. Appendix C — Health Checks & Operations
• C.1 Health endpoints
• C.2 Logging and request tracing
• C.3 Scheduled work
• C.4 Support information to capture

1. Application Overview

Genie is a practice-management platform for accounting firms. A firm's staff use it to plan and track client work, log time against that work, bill it, close each client's books every month, and report on all of it.

The product is organised into the following functional areas, which this document mirrors:

A number of route spellings, field names and response envelopes are retained for compatibility with earlier clients of this API. Where that affects how a request must be formed, this document states it at the endpoint concerned.

↑ Back to Table of Contents

2. API Overview

• Style: JSON over HTTP. The API is not REST-shaped: most operations are a POST to a verb-like path (/api/task/save, /api/invoicing/preview/delete) carrying the payload in the body, including many read operations. Path parameters are used sparingly.
• Transport: application/json for almost all endpoints. A small number accept multipart/form-data (file uploads) or return binary or base64 content (exports).
• Authentication: server-side session cookie. There is no bearer token or JWT scheme and no public API key.
• Versioning: the API is unversioned. There is no /v1 prefix and no version header.
• Path prefixes: most endpoints are served under /api/...; the authentication and OAuth routes are served at the root (/login, /csrf, /google/callback).
• Machine-readable specification: none is published. This document is the specification.

↑ Back to Table of Contents

3. Base URL and Environments

The backend listens on the port given by PORT (default 4000).

No production hostname is fixed in the application. Clients must substitute the base URL for their own environment; every path in this document is relative to it. The example requests use https://api.example.com as a placeholder.

3.1 Calling through the web application

The Genie web application proxies the API rather than calling it cross-origin. A browser client should call the application path, which is same-origin and therefore carries the session cookie without any cross-origin configuration.

Note that /api/google/signup maps to the backend's /google/signup (no /api segment), while the Google Drive routes map to /api/google/.... A proxy configuration must therefore declare the sign-up rule ahead of the general /api/google/* rule.

3.2 Cross-origin requests

A single browser origin is allowed, configured as FRONTEND_ORIGIN, and credentials are permitted on it. A browser client calling the backend directly must therefore be served from that origin and must send credentials with each request (credentials: 'include'). Calling through the application paths in §3.1 avoids cross-origin configuration altogether and is the recommended integration for browser clients.

↑ Back to Table of Contents

4. Authentication and Session

Endpoint-level detail is in 8. Authentication, Session & Core. This is the operational summary.

4.1 Session model

• Sessions are server-side and are persisted in the database, so any application instance can serve any request once a session exists.
• Cookie name: genie.sid — httpOnly, SameSite=Lax, Secure in production, lifetime 7 days.
• The session carries the signed-in user, the authentication state (2fa_pending or authenticated), the two-factor method in use, and the shared company and period selection described in §5.4.
• There is no refresh-token mechanism. A session ends when the cookie expires, when the user signs out, or when the stored session is removed.

4.2 CSRF protection

State-changing authentication endpoints require a synchronizer CSRF token:

1. GET /csrf issues a 32-byte hex token, stores it on the session, and returns it in a JavaScript-readable XSRF-TOKEN cookie.
2. The client replays it on protected requests in the X-XSRF-TOKEN header (a _token body field is also accepted).
3. A missing or mismatched token returns 403 {"message": "CSRF token mismatch."}.

CSRF protection applies to: POST /login, /password/email, /password/reset, /login/select-2fa, /login/verify/otp, /login/verify/googleotp, /login/verify/resend and POST /google/signup. It does not apply to the application (/api/...) endpoints, which rely on the session cookie and its SameSite=Lax restriction.

4.3 Sign-in flow

GET  /csrf                     → issue CSRF token (sets XSRF-TOKEN cookie)
POST /login                    → email + password  (X-XSRF-TOKEN required)
        │
        ├─ no 2FA required     → session state = 'authenticated'
        ├─ auth_type = '0'     → user must choose a method: POST /login/select-2fa
        ├─ auth_type = '1'     → Google Authenticator: POST /login/verify/googleotp
        └─ auth_type = '3'     → emailed OTP:          POST /login/verify/otp
                                  (resend via POST /login/verify/resend)
        │
GET  /login/check              → reports which branch applies; also generates and sends the OTP
        ↓
   on success: enc_log cookie set (HttpOnly), { redirect } returned
        ↓
GET  /api/check/session        → confirm the session on subsequent page loads
POST /api/logout               → end the session

Sign-in guardrails:

Sign in with Google is an alternative entry point: GET /google/redirect → Google consent → GET /google/callback, which either signs the user in or, for a Google identity that is not yet linked to a Genie account, sets a 60-second google cookie and routes to the account-linking screen served by GET /google/signup and POST /google/signup.

4.4 Authorization model

Authorization is enforced per endpoint rather than by a single global gate. Every authenticated request first resolves the caller from the session — an absent session, or a user who is inactive or deleted, produces 401 — after which each endpoint applies its own scope and permission rules. This document records those rules for every endpoint in the Authorization row of its fact table.

Two mechanisms are used.

a) Named roles — rows in user_roles:

Two flags on the user record sit above the role table: global_admin = 1 (system-wide access, ignoring firm scoping) and firm_admin = 1 (full access within the user's own firm).

b) Per-menu access levels — user_company_access and user_group_access rows grant an access level per menu. Throughout this document the levels are referred to by name — ACCESS_NO (1), ACCESS_VIEW (2), ACCESS_STANDARD (3) and ACCESS_ADMIN (4) — and the menus by id: 3 (Monthly Close), 10 (Client Success) and 81 (Tasks & Time):

↑ Back to Table of Contents

5. Common API Conventions

5.1 Request headers

No Authorization header, API key or tenant header is used — the firm and company scope is derived from the session.

5.2 Response envelopes

Three response shapes occur across the API.

a) The error envelope (most common):

{ "error": false, "data": [ ... ], "message": "Saved successfully." }

b) A bare object or array — several list endpoints return the rows directly, with no envelope.

c) A redirect instruction — the authentication endpoints return { "redirect": "/home" } for the client to navigate to, rather than issuing an HTTP redirect. The browser-visited OAuth routes are the exception and do issue real 302 responses.

Important for integrators: a failed business rule usually returns HTTP 200 (or 201) with {"error": true, "message": "..."}, not a 4xx status. Duplicate names, permission refusals applied server-side, "not found" conditions and grid validation failures are all reported this way. Clients must inspect the response body, not only the status code. HTTP error statuses are reserved for request validation (400), a missing or invalid session (401), explicit permission refusals (403) and unhandled failures (500).

5.3 Status codes

5.4 The shared company and period selection

Genie keeps one company selection and one as-on period on the session, shared by every screen. Selecting a company in Report Center also changes it in Client Success, Admin, Tasks & Time and Monthly Close. This is intentional: the selection is a single application-wide value.

Most data endpoints fall back to this session selection when the corresponding id is omitted from the request body.

5.5 Filtering, sorting and pagination

There is no single global convention. Endpoints that support these capabilities take them as body fields, and the field names differ per endpoint; each endpoint's Request body table is authoritative. The recurring patterns are:

• Filtering — a filter object, or discrete fields such as companyId, firmId, userId, status, fromDate / toDate, monthVal / yearVal. Multi-select filters are frequently sent as comma-separated id strings (for example "12,45,78") rather than JSON arrays; both forms are documented per endpoint.
• Sorting — where supported, sortBy or sortColumn plus sortOrder (asc / desc).
• Pagination — where supported, offset + limit, or page + perPage. Many list endpoints are unpaginated and return the full result set. A few endpoints accept offset/limit fields that do not affect the result set; these are noted individually.

5.6 Dates, times and periods

5.7 Request size limits

Request bodies are accepted up to 20 MB for both JSON and URL-encoded content. The allowance exists for Report Writer and Reports Builder saves, whose per-value conditional-formatting rules can produce very large payloads. Exceeding 20 MB returns 413.

5.8 Numeric precision

QuickBooks Online issues reference ids of up to 18 digits, beyond the range JavaScript can represent exactly as a number. Such values are returned as numbers when they fit that range and as strings when they do not. A client must therefore accept either a number or a numeric string for QuickBooks id fields (class_qbo, customer, item and location ids, and similar).

5.9 Encrypted identifiers

Some route parameters and body ids are exchanged in encrypted form rather than as plain integers — a base64 value that the API decrypts server-side. Endpoints accept either form:

• a plain numeric id — "123"
• a numeric id with a suffix — "123_profile"
• an encrypted base64 id — decrypted server-side (+ and space URL-encoding variants are both tolerated)

Where an endpoint's behaviour differs between the two forms, this document says so. Clients should treat these ids as opaque strings and echo back exactly what the API returned.

5.10 File uploads and downloads

• Uploads use multipart/form-data. The field name, accepted file types and any size limit are documented per endpoint. Feedback Center attachments are stored in Google Cloud Storage.
• Downloads take one of three forms, which differ by endpoint:
  1. a direct binary stream (.xlsx and similar) with a Content-Disposition header;
  2. base64 content inside a JSON envelope — several export endpoints return the file this way rather than as a stream, so the client must decode it rather than stream it;
  3. a two-step token flow — POST .../export builds the file and returns a single-use token, then GET .../export/generated/:token downloads it.

Deployment consideration: in the two-step flow the generated file is held in temporary server-side storage associated with the application instance that produced it, so the download request must reach that same instance. On several of these routes the single-use token is the only credential presented. See Deployment & Operational Considerations.

5.11 Error handling and diagnostics

• Failures that occur outside normal request handling are returned as JSON rather than as plain text: {"error": true, "msg": "The server failed to complete this request.", "debug": "<message>"}.
• All 5xx responses are logged server-side. Report requests are additionally traced on arrival and completion, and a connection closed before a response was sent is logged explicitly, so that "the request never arrived", "the request is still running" and "the request failed" can be distinguished during support investigations.

↑ Back to Table of Contents

6. How to Read the Endpoint Reference

Each endpoint is documented as:

• a heading with the HTTP method and full path;
• a one-line statement of purpose;
• a fact table — Module, Authentication, Authorization, Content type;
• Path parameters, Query parameters and Request body tables (omitted where the endpoint has none);
• an Example request;
• a Success response, with status code, example body and field descriptions;
• an Errors table listing the conditions the endpoint actually produces; where no endpoint-specific conditions are documented, the standard responses in §5.3 apply;
• Notes covering business rules, side effects, related endpoints and compatibility behaviour.

Where a detail is not established by the current implementation, it is marked "Not specified in the current implementation." rather than assumed.

↑ Back to Table of Contents

7. Module Directory

↑ Back to Table of Contents

8. Authentication, Session & Core

This module is the front door of the Genie backend. It covers backend health checks, the CSRF token lifecycle, credential login and password recovery, both two-factor branches (Google Authenticator and emailed OTP), "Sign in with Google", logout, and the shared server-side session state that every other screen reads when it loads — the signed-in user, their roles and per-company access map, and the selected company + as-on period that drives every data query in the product. It also carries three session-scoped areas that belong to no other feature area: the user notification feed, the shared company/group tree used by the "Select company/group" picker, and two read-only role-map diagnostics. Except where a route is documented as a browser redirect, every endpoint in this module exchanges JSON.

8.1 How authentication works end to end

1. Mint a CSRF token. The client calls GET /csrf once at boot. The token is stored on the server session and echoed in a JS-readable XSRF-TOKEN cookie; every state-changing auth POST must replay it in the X-XSRF-TOKEN header (or a _token body field).
2. Submit credentials. POST /login verifies the email and password against the stored password hash, stamps users.last_login, and records the user id and two-factor method on the session. Failures are throttled: 6 attempts per email|ip then a 60-second lockout.
3. Branch on auth_type. Login always answers redirect: "/login/check". The client then calls GET /login/check, which decides what the user must do next:
   - auth_type = 0 → the user has never chosen a 2FA method. Response is twoFactorType: "select"; they must call POST /login/select-2fa to pick Google Authenticator ('1') or email OTP ('3').
   - auth_type = 1 → Google Authenticator. Response is twoFactorType: "google", plus a QR code and secret when the user is not yet enrolled.
   - auth_type = 2 or 3 → an OTP is generated, stored on users.otp and emailed once per login attempt; response is twoFactorType: "otp".
   - Any other state → already authenticated, redirect: "/home".
4. Verify. POST /login/verify/googleotp (TOTP) or POST /login/verify/otp (emailed code). The body carries only the code — the user identity is read from the server session, never from the request. Emailed OTPs expire after 5 minutes; POST /login/verify/resend issues a fresh one with a 30-second cooldown.
5. enc_log + redirect. On success the server writes users.enc_log (an encrypted <userId>_<Y-m-d H:i:s> value), sets it as an HttpOnly enc_log cookie, marks the session authenticated, and returns { "redirect": "/home" }. The cookie is HttpOnly and is not readable by client-side scripts.
6. Bootstrap the app. The client then calls GET /api/check/session, which returns the user, roles, per-company access map and the selected company/period.

Google sign-in bypasses 2FA entirely. GET /google/redirect → Google consent → GET /google/callback, which either logs an already-linked user straight in (setting enc_log), or — for a brand-new Google identity — sets a 60-second google cookie and redirects to the "One Last Time" linking screen backed by GET /google/signup and POST /google/signup.

8.2 Session and CSRF cookies

Request validation is applied globally: declared types are coerced and unknown body properties are stripped rather than rejected. A validation failure returns HTTP 400 with { "message": [ ...messages ], "error": "Bad Request", "statusCode": 400 }.

8.3 Health & CSRF

Backend liveness ping used by hosting/uptime checks. Verifies the database connection as well as the process.

Example request

curl https://api.example.com/

Success response — 200 OK (or 503 Service Unavailable when the database probe fails)

{
  "status": "ok",
  "service": "smartbook-genie-backend",
  "message": "Backend and database are healthy.",
  "checks": {
    "database": { "status": "up", "latencyMs": 7 }
  },
  "timestamp": "2026-09-01T09:14:22.481Z"
}

Errors

Explicit health endpoint. Returns the same payload and behaviour as GET /, for platforms that require a named health path.

Example request

curl https://api.example.com/health

Success response — 200 OK (or 503)

{
  "status": "ok",
  "service": "smartbook-genie-backend",
  "message": "Backend and database are healthy.",
  "checks": {
    "database": { "status": "up", "latencyMs": 5 }
  },
  "timestamp": "2026-09-01T09:14:31.902Z"
}

Fields are identical to GET /.

Errors

Issues (or returns the existing) synchronizer CSRF token for this session and echoes it in a JS-readable cookie. Must be called before any CSRF-protected POST.

Example request

curl -c cookies.txt https://api.example.com/csrf

Success response — 200 OK

{ "csrfToken": "3f0b8c1de4a95c77b2c9f1a06d8e4471a2c5b93e0f6d18ca7b4e2d905c31af68" }

Errors

No endpoint-specific error conditions are documented for this endpoint; the standard responses in §5.3 Status codes apply.

Notes

• Idempotent: a session that already holds a token gets the same value back; a new token is only minted when the session has none.
• Sets cookie XSRF-TOKEN with httpOnly: false, path=/, sameSite=lax, secure in production — readable by JavaScript so the client can replay it.

8.4 Credential Login & Password Recovery

Verifies email and password and establishes the pre-2FA session.

Request body

Example request

curl -b cookies.txt -c cookies.txt -X POST https://api.example.com/login \
  -H 'Content-Type: application/json' \
  -H 'X-XSRF-TOKEN: 3f0b8c1de4a95c77b2c9f1a06d8e4471a2c5b93e0f6d18ca7b4e2d905c31af68' \
  -d '{"email":"jane.doe@example.com","password":"S3cret!pass"}'

Success response — 200 OK

{ "requires2fa": true, "redirect": "/login/check" }

Errors

Notes

• Only users with active = 1 and deleted = 0 can authenticate.
• Failed attempts are throttled at 6 attempts with a 60-second decay, counted per email|ip; the counter is cleared on a successful credential check. Throttle counters are held per application instance, so multi-instance deployments must preserve instance affinity for the login routes if the limit is to apply exactly as documented. See Deployment & Operational Considerations.
• Stored hashes carrying a $2y$ prefix are normalised to $2b$ for comparison only — stored values are never rewritten.
• On success users.last_login is stamped and session.login gets userId, authType, and state (2fa_pending or authenticated). otpGeneratedAt is cleared so a fresh OTP can be issued by GET /login/check.

The post-credential branch point: tells the client whether the user must select a 2FA method, enrol in Google Authenticator, enter an emailed OTP, or go straight to the app.

Example request

curl -b cookies.txt https://api.example.com/login/check

Success response — 200 OK (emailed-OTP branch)

{
  "requires2fa": true,
  "authType": "3",
  "twoFactorType": "otp",
  "redirect": "/login/verify"
}

Google Authenticator branch, first-time enrolment:

{
  "requires2fa": true,
  "authType": "1",
  "twoFactorType": "google",
  "redirect": "/login/verify",
  "enroll": true,
  "google2fa_secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
  "otpauthUrl": "otpauth://totp/jane.doe%40example.com?secret=JBSWY3DP...&issuer=Genie",
  "qr": "data:image/png;base64,iVBORw0KGgoAAAANS..."
}

Already-authenticated response:

{ "requires2fa": false, "authType": "3", "redirect": "/home" }

Errors

Notes

• Side effect: for auth_type 2 and 3 this endpoint generates a 4-digit OTP, writes it to users.otp, stamps session.login.otpGeneratedAt, and emails it (subject "OTP For Genie Login"). Delivery is email-only, so auth_type 2 and 3 behave identically.
• Idempotency: the OTP is issued only once per login attempt. Repeat calls to this route within the same login attempt do not issue a second code; issuance is gated on otpGeneratedAt, not on state.
• Side effect: for an un-enrolled auth_type = 1 user, a new base32 secret is generated and persisted to users.google2fa_secret.
• auth_type = 0 is treated as "must choose" — the user cannot reach the app until POST /login/select-2fa sets a real method.

Requests a password-reset link for an email address.

Request body

Example request

curl -b cookies.txt -X POST https://api.example.com/password/email \
  -H 'Content-Type: application/json' \
  -H 'X-XSRF-TOKEN: 3f0b8c1d...' \
  -d '{"email":"jane.doe@example.com"}'

Success response — 201 Created (the framework's default status for POST)

{ "message": "We have emailed your password reset link." }

Errors

Notes

• Account enumeration is prevented — the same message is returned for unknown emails, and no work is done for them.
• Side effect (known account only): any existing password_resets rows for that email are deleted and a new row is inserted holding a bcrypt hash of a 32-byte random token; the plain token only ever leaves the server inside the emailed link.
• Link format: {FRONTEND_ORIGIN|FRONTEND_URL|http://localhost:3000}/password/reset/<token>?email=<email>.
• resetUrl is never returned when NODE_ENV=production, and requires an explicit SHOW_DEV_RESET_LINK=true opt-in otherwise, so a mis-configured non-production deployment still cannot leak reset links.

Consumes a reset token, sets the new password, and signs the user straight in.

Request body

Example request

curl -b cookies.txt -c cookies.txt -X POST https://api.example.com/password/reset \
  -H 'Content-Type: application/json' \
  -H 'X-XSRF-TOKEN: 3f0b8c1d...' \
  -d '{
        "token":"9ad3...c1",
        "email":"jane.doe@example.com",
        "password":"N3wS3cret!",
        "password_confirmation":"N3wS3cret!"
      }'

Success response — 201 Created

{ "message": "Your password has been reset!", "redirect": "/home" }

Errors

Notes

• Tokens are valid for 60 minutes; an expired token also deletes every password_resets row for that email.
• Side effect: on success the password is re-hashed with bcrypt (cost 10), users.last_login is stamped, all password_resets rows for the email are deleted, and the session is marked authenticated — the user does not go through 2FA on this path.

8.5 Two-Factor Verification

For users whose auth_type is still 0, records their chosen second factor and returns everything the verify screen needs to continue.

Request body

Example request

curl -b cookies.txt -X POST https://api.example.com/login/select-2fa \
  -H 'Content-Type: application/json' \
  -H 'X-XSRF-TOKEN: 3f0b8c1d...' \
  -d '{"authType":"1"}'

Success response — 201 Created (Google Authenticator chosen)

{
  "requires2fa": true,
  "authType": "1",
  "twoFactorType": "google",
  "redirect": "/login/verify",
  "enroll": true,
  "google2fa_secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
  "otpauthUrl": "otpauth://totp/jane.doe%40example.com?secret=JBSWY3DP...&issuer=Genie",
  "qr": "data:image/png;base64,iVBORw0KGgoAAAANS..."
}

Email OTP chosen:

{ "requires2fa": true, "authType": "3", "twoFactorType": "otp", "redirect": "/login/verify" }

Fields are the same as GET /login/check. Note that on the Google branch this endpoint always returns the QR and secret — even for a user who already had a google2fa_secret — so the selection screen can display the QR inline the moment Google Authenticator is picked.

Errors

Notes

• Side effect: persists the choice to users.auth_type — this is permanent, not per-session.
• Side effect (email branch): immediately generates, stores and emails a fresh OTP and stamps otpGeneratedAt.
• Side effect (Google branch): generates and persists a google2fa_secret if the user did not already have one.
• Callable only mid-login. Only '1' and '3' are selectable; '2' exists in the schema but is not offered at login (it behaves the same as '3' — email delivery).

Verifies a Google Authenticator TOTP code and completes login.

Request body

Example request

curl -b cookies.txt -c cookies.txt -X POST https://api.example.com/login/verify/googleotp \
  -H 'Content-Type: application/json' \
  -H 'X-XSRF-TOKEN: 3f0b8c1d...' \
  -d '{"otp":"418205"}'

Success response — 201 Created

{ "redirect": "/home" }

Errors

Notes

• Identity comes from the server session only — the body carries the code and nothing else, so a caller cannot verify on another user's behalf.
• TOTP is checked with a window: 1 tolerance (one step either side of the current 30-second window).
• Side effect: clears users.otp, writes users.enc_log (the encrypted <userId>_<Y-m-d H:i:s> value) and users.enc_log_on, and marks the session authenticated.
• Cookie: sets enc_log with httpOnly: true, path=/, sameSite=lax, secure in production. The cookie is not readable by client-side scripts.
• Development environments only: when APP_ENV is set to local or development, a development-only bypass allows a small set of pre-configured test accounts to complete this step without a real authenticator code. It never applies to the emailed-OTP path and is inactive whenever APP_ENV is unset or set to anything else, so it does not exist in a production deployment.

Verifies the emailed OTP (for auth_type 2 and 3) and completes login.

Request body

Example request

curl -b cookies.txt -c cookies.txt -X POST https://api.example.com/login/verify/otp \
  -H 'Content-Type: application/json' \
  -H 'X-XSRF-TOKEN: 3f0b8c1d...' \
  -d '{"otp":"7413"}'

Success response — 201 Created

{ "redirect": "/home" }

Errors

Notes

• Identity comes from the server session only; the body carries just the code.
• OTP TTL is 5 minutes, measured from session.login.otpGeneratedAt. An expired code is cleared from users.otp as part of the rejection, forcing a resend.
• Side effect: on success clears users.otp and otpGeneratedAt, writes users.enc_log / enc_log_on, and marks the session authenticated.
• Cookie: sets enc_log (HttpOnly, path=/, sameSite=lax, secure in production).
• There is no dev master-code bypass on this route — the emailed path is never bypassed.

Issues a fresh emailed OTP and restarts the expiry clock.

Example request

curl -b cookies.txt -X POST https://api.example.com/login/verify/resend \
  -H 'X-XSRF-TOKEN: 3f0b8c1d...' \
  -H 'Content-Length: 0'

Success response — 201 Created

{ "message": "A new OTP has been sent." }

Errors

Notes

• Takes no request body.
• Anti-spam cooldown of 30 seconds between generations.
• Side effect: overwrites users.otp with a new 4-digit code, re-stamps otpGeneratedAt (resetting the 5-minute TTL), and emails the code.
• Only valid for the emailed-OTP branch — Google Authenticator users have nothing to resend.

8.6 Sign in with Google

Starts the Google OAuth flow by redirecting the browser to Google's consent screen.

Example request

GET /google/redirect HTTP/1.1
Host: api.example.com

Success response — 302 Found

HTTP/1.1 302 Found
Location: https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=https%3A%2F%2Fapp.example.com%2Fgoogle%2Fcallback&response_type=code&scope=openid+email+profile&access_type=online&prompt=select_account

Response body: no body — this route only issues a redirect.

Errors

No endpoint-specific error conditions are documented for this endpoint; the standard responses in §5.3 Status codes apply.

Notes

• The consent request uses the scopes openid email profile, with access_type=online and prompt=select_account.
• redirect_uri is derived as ${APP_URL}/google/callback (trailing slash trimmed; APP_URL defaults to http://localhost:3000). client_id comes from GOOGLE_CLIENT_ID.
• This is a browser navigation endpoint, not an XHR endpoint.

Google's OAuth redirect target. Exchanges the authorization code, then logs the user in, auto-links the Google account to a matching Genie account, or sends a brand-new Google identity to the account-linking screen.

Query parameters

Example request

GET /google/callback?code=4%2F0AeanS0b... HTTP/1.1
Host: api.example.com

Success response — 302 Found

Existing / auto-linked user:

HTTP/1.1 302 Found
Set-Cookie: enc_log=U0ZkV...; Path=/; HttpOnly; SameSite=Lax
Location: /home

Brand-new Google identity:

HTTP/1.1 302 Found
Set-Cookie: google=104829173650192837465; Path=/; HttpOnly; SameSite=Lax; Max-Age=60
Location: /login/google-link?code=U1ZWa1Zt...

Failure (never a non-2xx status — the error is carried in the redirect):

HTTP/1.1 302 Found
Location: /login?g_error=Login%20failed.%20Please%20try%20again

Response body: no body — this route only issues a redirect.

Errors

Notes

• Resolution order: (1) a user already holding this google_id; (2) a user with the same email — their google_id/google_email are written on the spot (auto-link); (3) otherwise, a new identity that must be linked manually.
• Google sign-in bypasses 2FA entirely — a matched user's session is marked authenticated immediately.
• Side effect (matched user): stamps last_login, writes enc_log / enc_log_on, and sets the HttpOnly enc_log cookie.
• Side effect (new identity): sets a 60-second HttpOnly google cookie holding the Google account id, and passes an encrypted <googleId>_<email> value as the code query parameter of the linking screen.
• The linking code is transient: it is minted here, consumed by the linking screen, and never persisted. It is encrypted with a padded variant of the cipher so that long Google identifier/email pairs survive the round trip intact.
• The redirect targets are frontend routes, not backend routes.

Validates the linking code from GET /google/callback against the 1-minute google cookie and returns the Google email for the "One Last Time" linking screen to display.

Query parameters

Example request

curl -b 'google=104829173650192837465' \
  'https://api.example.com/google/signup?code=U1ZWa1Zt...'

Success response — 200 OK

{ "email": "jane.doe@gmail.com" }

Errors

Notes

• The google cookie is read from the Cookie request header and must be sent with the request.
• Purely a read/validation step; it makes no database changes.

Completes account linking: verifies the user's existing Genie email + password, attaches the Google account, and signs them in.

Request body

Example request

curl -b cookies.txt -c cookies.txt -X POST https://api.example.com/google/signup \
  -H 'Content-Type: application/json' \
  -H 'X-XSRF-TOKEN: 3f0b8c1d...' \
  -d '{
        "code":"U1ZWa1Zt...",
        "email":"jane.doe@example.com",
        "password":"S3cret!pass"
      }'

Success response — 201 Created

{ "redirect": "/home" }

Errors

Notes

• Depends on GET /google/callback having issued the code; unlike GET /google/signup this endpoint does not re-check the google cookie, only that the code decrypts to two parts.
• Side effect: writes google_id and google_email onto the user, stamps last_login, and writes enc_log / enc_log_on.
• Cookie: sets enc_log (HttpOnly, path=/, sameSite=lax, secure in production).
• Marks the session authenticated immediately — no 2FA on the Google path.
• Password comparison uses the same $2y$ → $2b$ bcrypt normalisation as POST /login.

8.7 Logout

Tears down the authenticated session for browser clients.

Example request

curl -b cookies.txt -c cookies.txt -X POST https://api.example.com/api/logout -H 'Content-Length: 0'

Success response — 201 Created

{ "error": false, "message": "Logged out successfully." }

Errors

No endpoint-specific error conditions are documented for this endpoint; the standard responses in §5.3 Status codes apply.

Notes

• No CSRF token is required on this route, unlike the other authentication POSTs.
• Resets session.login to an empty object and clears the enc_log cookie (path=/). It does not destroy the underlying genie.sid session row or clear the XSRF-TOKEN cookie, so the CSRF token minted by GET /csrf survives and can be reused for the next login.
• users.enc_log in the database is left as-is; only the cookie is removed.

8.8 Session State & Company Selection

The bootstrap call every screen makes at mount. Validates the session and returns the signed-in user, their roles, their per-company menu access map, the selected company and as-on period, and supplementary dashboard data.

Example request

curl -b cookies.txt https://api.example.com/api/check/session

Success response — 200 OK

{
  "userData": {
    "id": 237,
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "user_name": "Jane Doe",
    "firm_id": 340,
    "firm_admin": 1,
    "roleArray": [11, 13],
    "roles": [
      { "id": 11, "role_name": "Monthly Close Manager" },
      { "id": 13, "role_name": "Invoice Approver" }
    ]
  },
  "user_id": "U0ZkV1ZtMTNaR1p0",
  "menuArray": [],
  "global_user_profile": "",
  "global_company_logo": "uploads/company/1163.png",
  "selectedCompany": {
    "company_id": 1163,
    "global_company_name": "Acme Manufacturing LLC",
    "global_company_logo": "uploads/company/1163.png",
    "qbo_connection": 1
  },
  "carryOver": {
    "company_id": 1163,
    "asOnDate": "2026-09-01",
    "monthVal": "Sep",
    "yearVal": 2026
  },
  "global_role_name": "Monthly Close Manager,Invoice Approver",
  "global_admin": false,
  "accessData": {
    "1163": [
      { "menu_id": 4, "access_type": 2 },
      { "menu_id": 9, "access_type": 1 }
    ]
  },
  "disableEmail": false,
  "downloadReport": [],
  "utilizationData": {
    "resData": [
      { "name": "Jane Doe", "billable_hours": "31.50", "target": "35.00" }
    ]
  },
  "firmInternalCompany": {
    "id": 1163,
    "name": "Acme Manufacturing LLC",
    "firm_internal_company": 1,
    "qbo_connection": 1
  },
  "sessionData": {
    "login": {
      "userId": 237,
      "state": "authenticated",
      "authType": "3",
      "company": {
        "company_id": 1163,
        "global_company_name": "Acme Manufacturing LLC",
        "global_company_logo": "uploads/company/1163.png",
        "qbo_connection": 1
      },
      "carryOver": {
        "company_id": 1163,
        "asOnDate": "2026-09-01",
        "monthVal": "Sep",
        "yearVal": 2026
      }
    },
    "company": {
      "company_id": 1163,
      "global_company_name": "Acme Manufacturing LLC",
      "global_company_logo": "uploads/company/1163.png",
      "qbo_connection": 1
    }
  }
}

Errors

Notes

• Side effect: this endpoint validates and seeds the session company. If the session holds no company, the first active company for the firm (preferring the firm-internal one) is selected and written to the session together with a matching carryOver. An already-selected company is resolved without an active = 1 filter, so a selection that points at an inactive company — as Report Center may legitimately hold — is preserved rather than replaced by a default.
• company_id: 0 (Global) round-trips untouched and is never replaced by a default company.
• The utilization query is raced against a 10-second timeout; on timeout utilizationData.resData comes back as [] rather than failing the whole session check.

Reads the shared company selection and as-on period out of the session, so a fresh browser or a second tab starts on the same company.

Example request

curl -b cookies.txt https://api.example.com/api/company/session

Success response — 200 OK

{
  "error": false,
  "company": {
    "company_id": 1163,
    "qbo_connection": 1,
    "global_company_name": "Acme Manufacturing LLC",
    "global_company_logo": "uploads/company/1163.png"
  },
  "carryOver": {
    "company_id": 1163,
    "asOnDate": "2026-09-01",
    "monthVal": "Sep",
    "yearVal": 2026
  }
}

Errors

Notes

• carryOver is never null: a session that only ever stored a company id still reads back a usable period, defaulting to the current month and year.
• The selection is held server-side in the session rather than in browser storage, so it is shared across tabs and browsers.

Changes the company every screen is scoped to. This is the single shared switch point — picking a company on Reports also changes it on Client Success, Admin, Tasks & Time and Monthly Close.

Request body — the body is loosely typed; no request body schema is applied, so no field-level validation rules are enforced. Keys read by this endpoint:

Example request

curl -b cookies.txt -X POST https://api.example.com/api/company/session \
  -H 'Content-Type: application/json' \
  -d '{"company_id":1163,"preserve_period":true}'

Success response — 201 Created

{
  "error": false,
  "company": {
    "company_id": 1163,
    "qbo_connection": 1,
    "global_company_name": "Acme Manufacturing LLC",
    "global_company_logo": "uploads/company/1163.png"
  },
  "carryOver": {
    "company_id": 1163,
    "asOnDate": "2026-09-01",
    "monthVal": "Sep",
    "yearVal": 2026
  }
}

Fields are identical to GET /api/company/session. Selecting Global (company_id: 0) returns global_company_name: "Global", global_company_logo: "", qbo_connection: 0.

Errors

Notes

• Side effect: writes both session keys together (company and carryOver) so they can never drift apart, and touches company.updated_at — which drives the "Last used" ordering on the Admin company list.
• Period semantics: without preserve_period the as-on month/year reset to today; with it, the existing period is kept and only the company id changes.
• The company lookup applies no active/deleted filter, so an inactive company whose historical reports must remain accessible can still be selected.

Changes only the as-on month/year, keeping the selected company. Backs Monthly Close's month/year selects.

Request body — the body is loosely typed; no request body schema is applied, so no field-level validation rules are enforced. Keys read by this endpoint:

Example request

curl -b cookies.txt -X POST https://api.example.com/api/company/session/period \
  -H 'Content-Type: application/json' \
  -d '{"monthVal":"Jul","yearVal":2026}'

Success response — 201 Created

{
  "error": false,
  "company": {
    "company_id": 1163,
    "qbo_connection": 1,
    "global_company_name": "Acme Manufacturing LLC",
    "global_company_logo": "uploads/company/1163.png"
  },
  "carryOver": {
    "company_id": 1163,
    "asOnDate": "2026-07-01",
    "monthVal": "Jul",
    "yearVal": 2026
  }
}

Fields are identical to GET /api/company/session.

Errors

Notes

• Side effect: rewrites session.carryOver with a recomputed asOnDate (always the 1st of the resolved month) and leaves session.company untouched.
• Because the period lives in the shared session, changing it on Monthly Close carries it to every other screen — the same way the company does.

8.9 Notifications

Returns the 10 most recent notifications for the signed-in user plus a total count — the header bell feed.

Example request

curl -b cookies.txt https://api.example.com/api/user-based/notification

Success response — 200 OK

{
  "notifications": [
    {
      "id": "invoice-approval-9814",
      "date": "08/28/2026",
      "time": "04:12 PM",
      "subtitle": "Approval required for INV-10422 Invoice",
      "title": "Jane Doe raised the Invoice(INV-10422). You Can Approve/Reject the Invoice.",
      "subject": null,
      "notificationsCount": 1,
      "user": "237",
      "enc_id": "U0ZkV1ZtMTNaR1p0",
      "invoiceBatchId": 9814,
      "invoiceNo": "INV-10422",
      "fromInvoice": true,
      "strtotime": 1787932320
    }
  ],
  "notificationsCount": 27
}

Each notification item is an untyped object whose keys vary by source. Common keys across sources: id, date (MM/DD/YYYY), time, title, subtitle, subject, user, strtotime (unix seconds; the only sort key). Source markers and extras include fromTimesheet + week, fromInvoice + enc_id/invoiceBatchId/invoiceNo, fromComment + attribute/invoiceNo, and fromMonthlyClose.

Errors

Notes

• Aggregates four sources — timesheet approvals/rejections, invoice approvals/rejections, comment threads, and Monthly Close — merged in the order timesheet → invoice → comments → monthly close, which is what decides display order whenever strtotime values tie.
• Read-only; nothing is marked as read or written back.

Returns the complete notification list for the signed-in user — the "See All" screen.

Example request

curl -b cookies.txt https://api.example.com/api/user-based/notification/all

Success response — 200 OK

[
  {
    "id": "invoice-approval-9814",
    "date": "08/28/2026",
    "time": "04:12 PM",
    "subtitle": "Approval required for INV-10422 Invoice",
    "title": "Jane Doe raised the Invoice(INV-10422). You Can Approve/Reject the Invoice.",
    "subject": null,
    "notificationsCount": 1,
    "user": "237",
    "enc_id": "U0ZkV1ZtMTNaR1p0",
    "invoiceBatchId": 9814,
    "invoiceNo": "INV-10422",
    "fromInvoice": true,
    "strtotime": 1787932320
  },
  {
    "id": "timesheet-approval-237-2026-W34",
    "date": "08/24/2026",
    "time": "09:03 AM",
    "subtitle": "Approval required for John Smith Timesheet",
    "title": "Timesheet approval required for the John Smith for the week 08/15/2026 - 08/21/2026",
    "subject": "",
    "week": "2026-W34",
    "user": "237",
    "fromTimesheet": true,
    "strtotime": 1787814180
  }
]

The response is a bare array (not wrapped in an object), sorted by strtotime descending, with no 10-item cap. Item fields are the same untyped, source-dependent shape described for GET /api/user-based/notification.

Errors

Notes

• Same aggregation and ordering as the bell feed; only the pagination differs.
• Takes no query parameters or request body.

8.10 Company & Group Tree

Returns the company/group hierarchy behind the shared "Select company/group" picker, plus flat lists of every visible group and company.

Example request

curl -b cookies.txt -X POST https://api.example.com/api/get/web-treeview -H 'Content-Length: 0'

Success response — 201 Created

{
  "tree": [
    {
      "id": 42,
      "name": "Est's Firm(test) Accounting Group",
      "expandable": true,
      "child": {
        "group": [
          {
            "id": 57,
            "name": "Boston project Group",
            "expandable": true,
            "child": {
              "group": [],
              "company": [{ "id": 1163, "name": "Acme Manufacturing LLC" }]
            }
          }
        ],
        "company": [{ "id": 1201, "name": "Northwind Traders Inc" }]
      }
    }
  ],
  "group": [
    { "id": 42, "name": "Est's Firm(test) Accounting Group" },
    { "id": 57, "name": "Boston project Group" }
  ],
  "company": [
    { "id": 1163, "name": "Acme Manufacturing LLC" },
    { "id": 1201, "name": "Northwind Traders Inc" }
  ],
  "cacheKey": "_TREE_DATA_237_3"
}

Errors

Notes

• Takes no request body, query or path parameters despite being a POST.
• The canonical path is api/get/web-treeview. A separate Monthly Close endpoint is available at api/get/treeview; the two are not interchangeable — this route returns the tree behind the shared "Select company/group" picker, while the Monthly Close route returns that module's own tree, built by different rules.
• Companies attach to every node, root or nested, with no gate — a group with companies but no child groups is still expandable.
• firm_internal_group / firm_internal_company rows are not hidden from the tree.
• Soft-deleted companies (deleted = 1) still appear as leaves; only deleted = 2 placeholder rows drop out. Groups apply whichever soft-delete column the schema has.
• Recursion is capped at a depth of 20 as a defence against malformed parent pointers.

8.11 Role Map Diagnostics

Read-only dry run that compares what the role-map engine would derive for a set of companies against what the database currently holds. Used to validate Client Success → Configure role propagation.

Request body

Example request

curl -b cookies.txt -X POST https://api.example.com/api/utilities/configure/debug/role-map-compare \
  -H 'Content-Type: application/json' \
  -d '{"companyIds":[1163,1201]}'

Success response — 201 Created

{
  "error": false,
  "totalCompanies": 2,
  "mismatches": 1,
  "allMatch": false,
  "report": [
    {
      "companyId": 1163,
      "firmId": 340,
      "primaryAccountant": { "computed": 512, "current": 512, "match": true },
      "mcManager": { "computed": 488, "current": 488, "match": true },
      "invoiceApprovers": { "computed": [512, 907], "current": [512], "match": false }
    },
    {
      "companyId": 1201,
      "firmId": 340,
      "primaryAccountant": { "computed": null, "current": null, "match": true },
      "mcManager": { "computed": 488, "current": 488, "match": true },
      "invoiceApprovers": { "computed": [], "current": [], "match": true }
    }
  ]
}

Errors

Notes

• Strictly read-only — SELECT queries only, no derived table is written.
• Companies are grouped by company.firm_id; a company whose firm_id is null or 0 is silently skipped and will not appear in report.
• "Computed" values are derived by the role-map engine from service_roles, service_role_users and cs_override_roles, with override-beats-default resolution; "current" values are read straight from the live derived tables.
• Diagnostic/support endpoint, not part of any end-user screen.

Read-only diagnostic dump of the raw inputs the role-map engine reads for a single company — useful when role-map-compare reports a mismatch and you need to see why.

Request body

Example request

curl -b cookies.txt -X POST https://api.example.com/api/utilities/configure/debug/role-map-inputs \
  -H 'Content-Type: application/json' \
  -d '{"companyId":1163}'

Success response — 201 Created

{
  "error": false,
  "companyId": 1163,
  "companyFirmId": 340,
  "firm": { "id": 88, "user_id": 340, "use_service_role": 1 },
  "roleFirmId": 340,
  "engineCurrentScope": "firm_id = ?",
  "engineRoleCount": 2,
  "engineRoles": [
    {
      "id": 21,
      "role": "Senior Accountant",
      "firm_id": 340,
      "deleted": 0,
      "primary_accountant": 1,
      "mc_manager": 0,
      "invoice_approver": 1
    },
    {
      "id": 22,
      "role": "Close Manager",
      "firm_id": 340,
      "deleted": 0,
      "primary_accountant": 0,
      "mc_manager": 1,
      "invoice_approver": 0
    }
  ],
  "companyServiceRoleUsers": [
    { "service_role_id": 21, "user_id": 512, "deleted": 0 },
    { "service_role_id": 22, "user_id": 488, "deleted": 0 }
  ],
  "companyOverrides": [
    {
      "service_role_id": 22,
      "override_primary_accountant": 0,
      "override_mc_manager": 1,
      "override_invoice_approver": 0,
      "deleted_at": null
    }
  ],
  "involvedRoles": [
    {
      "id": 21,
      "role": "Senior Accountant",
      "firm_id": 340,
      "deleted": 0,
      "primary_accountant": 1,
      "mc_manager": 0,
      "invoice_approver": 1
    },
    {
      "id": 22,
      "role": "Close Manager",
      "firm_id": 340,
      "deleted": 0,
      "primary_accountant": 0,
      "mc_manager": 1,
      "invoice_approver": 0
    }
  ]
}

Errors

Notes

• SELECT-only, no writes.
• A company id that matches no row returns companyFirmId: 0 and a firm block of nulls rather than a 404.
• Diagnostic/support endpoint, not part of any end-user screen.

↑ Back to Table of Contents

9. Admin

The Admin module is the administrative back office of Genie: it owns companies (create, edit, activate/deactivate/delete, logo, billing details, reporting-group definitions, chart-of-accounts mapping and industry verticals), the company-group hierarchy and the per-group user access matrices, the user directory (invite, roles, module/company access, impersonation, 2FA type, profile picture, and the "User Check" reassignment workflow), reporting groups, the global activity/audit log, and the QuickBooks Online sync-status board.

Every route in this module is served under the /api prefix. The caller is resolved from the session on every request: an established, authenticated session is required, otherwise the request fails with 401 { "message": "These credentials do not match our records." }. All role and scope checks are enforced server-side.

Request validation is applied globally, so request bodies and query strings are validated against the schemas documented below, unknown properties are stripped, and numeric fields are coerced from strings. A failed validation returns 400 { "message": [...], "error": "Bad Request", "statusCode": 400 }.

Many identifiers accept either a plain numeric id or the application's encrypted (base64) id: 123, 123_suffix and encrypted strings are all accepted, and an identifier that cannot be resolved is treated as 0. Responses that carry an id usually also carry an encryptId / encryptedId for use in subsequent calls.

9.1 Company

Company administration: the company pickers used across the app, the Admin > Company list, company creation (single and bulk Excel import), status changes, the company edit screen (details, billing, logo), the per-company reporting-group definitions, the chart-of-accounts to reporting-group mapping, and industry / business-model verticals.

Returns the company dropdown for the signed-in user, scoped by their role and by their access to the requested module.

Request body

Example request

curl -X POST https://api.example.com/api/company/list \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"module": 81}'

Success response — 200 OK

{
  "companies": [
    {
      "id": 412,
      "name": "Northwind Services",
      "encId": "3kan9eKI6bt+Qq1w==",
      "firmId": 27,
      "firmInternalCompany": 0,
      "deleted": 0
    }
  ]
}

Errors

Notes

• The module id drives an access-scope lookup, so the same user can see different companies for Tasks & Time than for Monthly Close.

Returns the "Account" (firm) dropdown shown above the Company dropdown for a Global Master System Administrator, who has no firm of their own to scope by.

Example request

curl https://api.example.com/api/firm/list \
  -b 'genie.sid=<session-cookie>'

Success response — 200 OK

{
  "accounts": [
    { "id": 27, "name": "Acme Accounting Partners" },
    { "id": 41, "name": "Beacon CPA Group" }
  ]
}

Errors

Notes

• Compatibility route: retained for compatibility with earlier clients.
• Schema-adaptive: returns { "accounts": [] } when neither a firms nor a firm table (or its id/name columns) exists.
• Non-deleted firms only, ordered by account name ascending.

Returns the Company dropdown for one specific firm — the second step after a Global Master System Administrator picks an Account from GET /api/firm/list.

Request body

Example request

curl -X POST https://api.example.com/api/firm/company/list \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"firmId": 27}'

Success response — 200 OK

{
  "companies": [
    { "id": 412, "name": "Northwind Services", "encId": "3kan9eKI6bt+Qq1w==", "firmId": 27 }
  ]
}

Errors

Notes

• Compatibility route: retained for compatibility with earlier clients.
• Results are not narrowed by the caller's own company access, because the caller has already chosen the firm to drill into. Ordered by company name ascending.
• firmId is required and must be an integer.

The Admin > Company list: a paged, searchable company table plus every page-level flag and dropdown source the screen needs.

Request body

Example request

curl -X POST https://api.example.com/api/company/view_all \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"content": "north", "selectCompany": "show_active", "offset": 0, "limit": 50}'

Success response — 200 OK

{
  "firms": [{ "user_id": 27, "account_name": "Acme Accounting Partners", "plan_type": 2 }],
  "canFilterAccounts": true,
  "canAddCompany": true,
  "canSelectAccountForAdd": true,
  "firmAdmin": false,
  "isGlobalAdmin": true,
  "userPlanTypes": [2, 3],
  "isMultiple": false,
  "defaultPlan": 0,
  "firmPlanType": 0,
  "runningQueue": false,
  "companyData": [
    {
      "id": 412,
      "encryptId": "3kan9eKI6bt+Qq1w==",
      "name": "Northwind Services",
      "total_tasks": 7,
      "firm_internal_company": 0,
      "qbo_connection": 1,
      "deleted": 0,
      "active": 1,
      "isCurrent": true,
      "last_used": "Aug 21, 2026"
    }
  ],
  "currentCompany": {
    "id": 412,
    "encryptId": "3kan9eKI6bt+Qq1w==",
    "name": "Northwind Services",
    "qbo_connection": 1
  },
  "total": 128
}

Errors

Notes

• show_all includes inactive and soft-deleted companies; show_active does not.
• When the caller has an empty access scope, the response still carries all page meta but companyData: [], currentCompany: null.

Search variant of the company list. Identical contract and behaviour to POST /api/company/view_all.

Request body — identical to POST /api/company/view_all.

Example request

curl -X POST https://api.example.com/api/company/search \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"content": "north"}'

Success response — 200 OK. Identical shape to POST /api/company/view_all.

Errors — identical to POST /api/company/view_all.

Notes

• Compatibility route: retained for compatibility with earlier clients; POST /api/company/view_all is the canonical route. Both routes share one implementation, so the search response carries the full page metadata as well as the matching rows.

Creates a company, seeds its accounting defaults and service roles, attaches it to a company group, and makes it the session's selected company.

Request body

Example request

curl -X POST https://api.example.com/api/company/newcompany \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_name": "Northwind Services", "plan_type": 3, "accUserId": 27, "domain": "northwind.example", "group_id": 88}'

Success response — 200 OK

{
  "error": false,
  "id": 412,
  "encryptId": "3kan9eKI6bt+Qq1w==",
  "name": "Northwind Services",
  "redirect": "/admin/company/3kan9eKI6bt%2BQq1w%3D%3D"
}

Business-rule failures return 200 with an error envelope instead of an HTTP error:

{ "error": true, "msg": "Company Name already Exist" }

Errors

Notes

• Company names are unique across the whole install, not per firm.
• Side effects: seeds the four per-company accounting config tables from accounting_default; attaches the company to the firm's group (or group_id when supplied); seeds service roles; writes session.login.company and session.login.carryOver, so the new company becomes the active one everywhere.
• The new company's firm_id is set to the selected account (or the caller's own firm when no account is selectable).

Live duplicate check for the company-name field in the add form.

Query parameters

Example request

curl -G https://api.example.com/api/company/check_company_exists \
  --data-urlencode 'company_name=Northwind Services' \
  -b 'genie.sid=<session-cookie>'

Success response — 200 OK

{ "is_company": "exists" }

Errors

Notes

• A blank name short-circuits to {"is_company": "add"}.
• The lookup is global (not firm-scoped) and matches only deleted = 0 rows — unlike POST /api/company/newcompany, which also blocks names held by inactive companies.

Builds the bulk-import Excel template for a firm and returns a one-shot download link.

Request body

Example request

curl -X POST https://api.example.com/api/company/import/template/download \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"firm_id": 27}'

Success response — 200 OK

{ "redirect": "/api/company/import/template/generated/1f0c2b1e-8a4a-4c1d-9a71-3ad0f1f9c2ab" }

Errors

Notes

• Generates a two-sheet .xlsx: Company Info (header row Company Name, Plan Type, Company Domain, Company Group, Industry Verticals, Business Model Verticals, plus one sample row) and Available Data (valid plan types, the firm's company groups, industry verticals, business-model verticals).
• The generated workbook is held as temporary server-side storage and referenced by a single-use token. The download itself is performed by GET /api/company/import/template/generated/:token, which must be served by the same application instance that produced the workbook; see Deployment & Operational Considerations.

Uploads a filled-in import workbook, validates every row, and queues the valid ones for background company creation.

Request body

Example request

curl -X POST https://api.example.com/api/company/import/template \
  -b 'genie.sid=<session-cookie>' \
  -F 'file=@Company Import Template.xlsx' \
  -F 'firm_id=27'

Success response — 200 OK

{
  "error": false,
  "message": "Data are Imported Successfully.",
  "createdCount": 14,
  "errorData": [],
  "runningQueue": true
}

Errors

Notes

• The header must match Company Name | Plan Type | Company Domain | Company Group | Industry Verticals | Business Model Verticals exactly.
• Valid rows are inserted asynchronously by a queue_manager job; the response returns before the import finishes. Poll GET /api/company/import/queue/status for completion.
• When the response contains error rows it carries no message, so the client shows only the error modal and no toast.
• Duplicate detection is scoped to the target firm and treats deleted IN (0, 1) names as taken.

Reports whether a bulk company-import job is currently running for the caller.

Example request

curl https://api.example.com/api/company/import/queue/status \
  -b 'genie.sid=<session-cookie>'

Success response — 200 OK

{ "runningQueue": true }

Errors

Notes

• Intended for polling after POST /api/company/import/template returns runningQueue: true.

Streams a previously generated import template workbook and then deletes it.

Path parameters

Example request

curl -OJ https://api.example.com/api/company/import/template/generated/1f0c2b1e-8a4a-4c1d-9a71-3ad0f1f9c2ab

Success response — 200 OK, binary body, with Content-Disposition: attachment; filename="Company Import Template.xlsx".

Response body: binary workbook — not JSON.

Errors

Notes

• Single use: the token is invalidated before the download starts and the temporary file is removed once the transfer completes. A second request for the same token returns 404.
• The download must be served by the same application instance that generated the workbook, so multi-instance deployments must preserve instance affinity for these routes. See Deployment & Operational Considerations.

Called on every company-row click: pins the company into the session, touches its "Last used" timestamp, and returns the edit URL plus registration state.

Request body

Example request

curl -X POST https://api.example.com/api/company/redirect \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w=="}'

Success response — 200 OK

{
  "error": false,
  "id": 412,
  "encryptId": "3kan9eKI6bt+Qq1w==",
  "qbo_connection": 1,
  "steps": 5,
  "no_register": 5,
  "company_logo": "company-412-1756700000000.png",
  "companyEditUrl": "/admin/company/3kan9eKI6bt%2BQq1w%3D%3D"
}

Errors

Notes

• The route is a POST because it mutates the session and updates the company row.
• Side effects: writes session.login.company and session.login.carryOver (resetting the as-on period) and updates company.updated_at, which is what the list's "Last used" column renders.
• The firm check is enforced server-side, so a firm admin cannot pin another firm's company into their session by posting a raw company id.

Reactivates, deactivates, or soft-deletes a company.

Request body

Example request

curl -X POST https://api.example.com/api/company/delete \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w==", "type": 1}'

Success response — 200 OK

{ "error": false }

Errors

Notes

• The company name is rewritten to carry the state: "<name>", "<name> (inactive)" or "<name> (deleted)", alongside deleted = 0/1/2 and active = 1/0/0.
• On delete the QuickBooks realm id is prefixed with D_ and qbo_connection is cleared.
• On every transition the company's company_group_companies memberships are removed, and saved Task List "Company" filters are rewritten to follow the rename.
• The open-task guard uses the same predicate as the list's total_tasks, so the client count and the server guard can never disagree.

Loads the company edit screen: core details, billing information, the edit permission flag and the QuickBooks reconnection warning.

Path parameters

Example request

curl https://api.example.com/api/company/details/3kan9eKI6bt%2BQq1w%3D%3D \
  -b 'genie.sid=<session-cookie>'

Success response — 200 OK

{
  "company": {
    "id": 412,
    "encryptId": "3kan9eKI6bt+Qq1w==",
    "name": "Northwind Services",
    "domain": "northwind.example",
    "budget": 1,
    "qbo_connection": 0,
    "logo": "company-412-1756700000000.png",
    "logo_url": "/api/company/logo/3kan9eKI6bt%2BQq1w%3D%3D"
  },
  "billing": {
    "id": 91,
    "company_id": 412,
    "billing_name": "Northwind Services LLC",
    "billing_email": "ap@northwind.example",
    "address": "1 Harbour Way, Portland OR"
  },
  "canEdit": true,
  "warning": "QuickBooks connection not found for Northwind Services. Please click here to reconnect."
}

Errors

Notes

• Both this endpoint and POST /api/company/save enforce the company scope check server-side, so an authenticated session cannot read or rename a company outside its scope by id.
• billing is read straight from user_billing_info and its exact columns depend on the deployment's schema.

Saves the company edit form (name, domain, budget flag).

Request body

Example request

curl -X POST https://api.example.com/api/company/save \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w==", "company_name": "Northwind Services", "company_domain": "northwind.example", "budget": 1}'

Success response — 200 OK

{ "error": false, "id": 412, "name": "Northwind Services" }

Errors

Notes

• The duplicate check here is firm-scoped and treats deleted IN (0, 1) as taken — narrower than the global check on POST /api/company/newcompany.
• Side effects on rename: saved Task List "Company" filters are rewritten, the companyToReplace placeholder in user_logs is substituted, the company is (re-)attached to the firm's first company group with the saver's mapping, and session.login.company.global_company_name is refreshed so the header repaints without a re-login.

Uploads a company logo image.

Request body

Example request

curl -X POST https://api.example.com/api/company/logo/upload \
  -b 'genie.sid=<session-cookie>' \
  -F 'file=@logo.png' \
  -F 'company_id=3kan9eKI6bt+Qq1w=='

Success response — 200 OK

{ "error": false, "logo_url": "/api/company/logo/3kan9eKI6bt%2BQq1w%3D%3D" }

Errors

Notes

• The image is kept as temporary server-side storage under a generated file name of the form company-<id>-<timestamp><ext>, and only that file name is stored in company.logo. Logo storage is local to the application instance that received the upload, so deployments must preserve instance affinity for the logo routes and must expect stored logos not to survive an instance restart. See Deployment & Operational Considerations.

Removes a company's logo file and clears company.logo.

Request body

Example request

curl -X POST https://api.example.com/api/company/logo/remove \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w=="}'

Success response — 200 OK

{ "error": false }

Errors

Notes

• Deleting the stored image file is best-effort; the company.logo column is cleared regardless.

Streams a company's logo image.

Path parameters

Example request

curl https://api.example.com/api/company/logo/3kan9eKI6bt%2BQq1w%3D%3D \
  -b 'genie.sid=<session-cookie>' --output logo.png

Success response — 200 OK, raw image bytes with Content-Type set from the stored file's extension.

Response body: binary image — not JSON.

Errors

Notes

• This is the URL returned as logo_url by GET /api/company/details/:id and POST /api/company/logo/upload.

Upserts the company's billing contact block.

Request body

Example request

curl -X POST https://api.example.com/api/company/billInfo/save \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w==", "billing_name": "Northwind Services LLC", "billing_email": "ap@northwind.example", "address": "1 Harbour Way, Portland OR"}'

Success response — 200 OK

{ "error": false }

Errors

Notes

• Writes to user_billing_info, inserting when no row exists for the company and updating otherwise. Every column is written only when present in the deployment's schema.
• Returns { "error": false } unchanged when the user_billing_info table is absent — the save silently no-ops.
• Unlike the other company-edit routes, this one performs no company-scope or canEdit check.

Loads the "Define Reporting Groups" screen for a company: the global groups, the company's custom groups and the Name/Number mode.

Path parameters

Example request

curl https://api.example.com/api/company/defineGroups/3kan9eKI6bt%2BQq1w%3D%3D \
  -b 'genie.sid=<session-cookie>'

Success response — 200 OK

{
  "canEdit": true,
  "define_group_type": 1,
  "global_groups": [
    { "id": 1, "report_name": "Revenue", "type": 1, "is_removable": 0 },
    { "id": 2, "report_name": "Cost of Goods Sold", "type": 1, "is_removable": 0 }
  ],
  "custom_groups": [
    { "id": 55, "name": "Owner Draws", "type": 2, "is_removable": 1 }
  ]
}

Errors

Notes

• Groups are ordered by id, not by name: id order is the P&L reading order accountants expect (Revenue, COGS, Cost of Service Delivery, Marketing and Sales, G&A, AR, AP, Other Income, Other Expense).

Creates a new reporting group — either a global one or a company-specific custom one.

Request body

Example request

curl -X POST https://api.example.com/api/company/defineGroups \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w==", "group_type": 2, "type": 1, "custom_name": "Owner Draws"}'

Success response — 200 OK

{ "error": false, "id": 55, "name": "Owner Draws" }

Errors

Notes

• The canEdit gate is enforced server-side, not only by hiding the Add Group button in the client.
• New global groups are created with is_removable = 1, so they can be deleted again; the nine seeded groups cannot.

Renames an existing reporting group.

Request body

Example request

curl -X POST https://api.example.com/api/company/defineGroups/edit \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"id": 55, "type": "custom", "name": "Owner Distributions"}'

Success response — 200 OK

{ "error": false, "msg": "Updated successfully." }

Errors

Notes

• Renaming enforces the same name-uniqueness rule as creation, using the same predicate, so a rename cannot introduce a duplicate name.
• Authorisation for a custom group is derived from the group's stored company_id, not from anything the caller sends.

Soft-deletes a reporting group, unless it is still referenced by Report Writer.

Request body

Example request

curl -X DELETE https://api.example.com/api/company/defineGroups \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"g_id": 55, "type": "custom"}'

Success response — 200 OK

{ "error": false }

Errors

Notes

• Soft delete only: sets deleted = 1 (plus active = 0 / deleted_at when those columns exist). Custom groups are additionally constrained by company_id in the UPDATE.
• The Report Writer usage check runs against report_writer_details and resolves its account/group-type columns defensively across schema variants.

Switches a company between mapping its chart of accounts by account Name and by account Number.

Request body

Example request

curl -X POST https://api.example.com/api/company/defineGroups/type/edit \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w==", "type": 2}'

Success response — 200 OK

{ "error": false }

Errors

Notes

• type is validated against the allowed values and the submitted company_id is checked for ownership before the update is applied.

Loads the chart-of-accounts to reporting-group mapping grid for one statement, in either by-name or by-number mode.

Request body

Example request

curl -X POST https://api.example.com/api/company/mapping/get \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w==", "type": 1, "group_mode": 1}'

Success response — 200 OK

{
  "canEdit": true,
  "type": 1,
  "group_mode": 1,
  "global_groups": [{ "id": 1, "report_name": "Revenue", "type": 1 }],
  "custom_groups": [{ "id": 55, "name": "Owner Draws", "type": 1 }],
  "accounts": [
    {
      "id": 9001,
      "qbo_id": "84",
      "account_name": "Consulting Income",
      "account_num": "4000",
      "account_type": "Income",
      "active": 1,
      "deleted": 0,
      "global_group_id": 1,
      "custom_group_ids": [55]
    }
  ],
  "ranges": [
    { "global_group_id": 1, "custom_group_id": 0, "from": "4000", "to": "4999" }
  ]
}

Errors

Notes

• The account-type filter is fixed per statement: type = 1 covers Income, Other Income, Cost of Goods Sold, Expense, Other Expense; type = 2 covers Accounts Payable, Accounts Receivable, Bank, Credit Card, Equity, Fixed Asset, Long Term Liability, Other Current Liability, Other Current Asset, Other Asset.
• Existing mappings come from accounting_group_config (by name) and accounting_group_config_by_number (ranges).

Saves the chart-of-accounts mapping for one statement and one mapping mode.

Request body

Example request

curl -X POST https://api.example.com/api/company/mapping/save \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{
        "company_id": "3kan9eKI6bt+Qq1w==",
        "type": 1,
        "group_mode": 1,
        "account_group_mode": 1,
        "data": [{ "qbo_id": "84", "global_group_id": 1, "custom_group_ids": [55] }]
      }'

Success response — 200 OK

{ "error": false }

Errors

Notes

• data is untyped: its element shape is whatever the mapping screen posts, and it is interpreted server-side according to group_mode.
• By-number ranges are cleaned up per company, statement and scope (Global or Custom), so saving one scope never affects the ranges saved for the other.
• Access is governed by the company-scoped canEdit check rather than by a global-admin/firm-admin-only gate, so roles such as Company Group Company Administrator can save mappings for companies they can reach.
• Returns { "error": false } unchanged when the required by-number columns are missing from the schema.

Loads the Industry Verticals and Business Model Verticals pickers for a company.

Request body

Example request

curl -X POST https://api.example.com/api/company/industry/get \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w=="}'

Success response — 200 OK

{
  "canEdit": true,
  "verticals": {
    "selected": [{ "vertical_id": 12, "name": "Professional Services", "vertical_type": 1 }],
    "available": [{ "id": 15, "name": "Retail", "vertical_type": 1 }]
  },
  "models": {
    "selected": [],
    "available": [{ "id": 31, "name": "Subscription", "vertical_type": 2 }]
  }
}

Errors

Notes

• selected rows come from the vertical_mapping join and therefore use the key vertical_id; available rows come from verticals and use id. Both lists are ordered by name.
• Returns empty lists rather than erroring when the verticals / vertical_mapping tables are absent.

Replaces a company's selected verticals for one vertical type.

Request body

Example request

curl -X POST https://api.example.com/api/company/industry/save \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_id": "3kan9eKI6bt+Qq1w==", "vertical_type": 1, "verticalArr": [12, 15]}'

Success response — 200 OK

{ "error": false }

Errors

Notes

• Ids whose stored vertical_type does not match the submitted vertical_type are silently dropped rather than rejected; the rest of the payload is still applied.
• The 500-item limit bounds the per-element database work each save performs.
• Returns { "error": false } unchanged when the vertical_mapping table is absent.

9.2 Company Groups

The company-group hierarchy: the group tree, group creation and editing, the placement preview, per-group user access matrices, and the "Manage Access to Internal Firm Accounting" screen.

Three role predicates recur across this subsection:

• View — users.global_admin = 1, or one of roles 1 (Global Master System Administrator), 4 (Global Company Group Administrator), 8 (Company Group Administrator). There is no firm-admin bypass.
• Manage — global_admin, firm_admin, or one of roles 1 / 4 / 8.
• Delete — global_admin or role 1 only. Firm admins and role 4 do not hold it.

A "role-8 scoped actor" (holds role 8, is not a firm admin and not a global admin) is further restricted: they see only the group trees containing a group they are mapped to, and cannot create or remove user access.

Returns the company-group tree, optionally filtered by a search term, plus the tree's action flags.

Request body

Example request

curl -X POST https://api.example.com/api/company-group/list \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"query": "north"}'

Success response — 200 OK

{
  "canEdit": true,
  "canDelete": true,
  "canDetachCompany": true,
  "tree": [
    {
      "id": 88,
      "encryptId": "Yk9wQmJ4TA==",
      "name": "Northwest Region",
      "type": "group",
      "firm_internal_group": 0,
      "children": [
        { "id": 412, "encryptId": "3kan9eKI6bt+Qq1w==", "name": "Northwind Services", "type": "company", "children": [] }
      ]
    }
  ],
  "totalGroups": 14
}

Errors

Notes

• The tree is not filtered by company_group.firm_id for a global admin, who has no firm of their own; such a caller sees every group.

Creates a company group.

Request body

Example request

curl -X POST https://api.example.com/api/company-group \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"group_name": "Northwest Region", "parent_id": 0}'

Success response — 200 OK

{
  "error": false,
  "id": 88,
  "encryptId": "Yk9wQmJ4TA==",
  "message": "Company Group Added Successfully",
  "msg": "Company Group Added Successfully"
}

Errors

Notes

• company_group.manager is NOT NULL with no default, so a new group is written with manager = 0; the Manager select is hidden in the UI.
• The parent column is resolved defensively across parent / parent_id / parent_group_id.

Loads the company-group detail screen: the group, its parent options, child-group and company checklists, the users with access, and the placement preview tree.

Path parameters

Example request

curl https://api.example.com/api/company-group/Yk9wQmJ4TA%3D%3D \
  -b 'genie.sid=<session-cookie>'

Success response — 200 OK

{
  "canEdit": true,
  "group": {
    "id": 88,
    "encryptId": "Yk9wQmJ4TA==",
    "group_name": "Northwest Region",
    "parent": 0,
    "firm_internal_group": 0,
    "manager": 0
  },
  "firmType": 2,
  "noCompanySelect": 0,
  "isFirmGroup": false,
  "parentOptions": [{ "id": 12, "encryptId": "MTI=", "group_name": "All Regions" }],
  "companyGroupOptions": [{ "id": 91, "group_name": "Portland Cluster", "checked": true }],
  "companyOptions": [],
  "usersWithAccess": [],
  "users": [],
  "viewerUserType": 2,
  "buttonDisable": false,
  "moduleRows": [{ "id": 81, "menu_name": "Tasks & Time" }],
  "placementTree": []
}

Errors

Notes

• companyOptions lists non-deleted companies that are not attached to any other group. Unchecking a box is what detaches a company — there is no separate remove control on this screen.
• companyGroupOptions and parentOptions both exclude firm-internal accounting groups, so those groups cannot be nested under another group.

Saves the company-group detail form: name, parent, child groups, member companies and the Manager select.

Request body

Example request

curl -X POST https://api.example.com/api/company-group/details/save \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{
        "company_group_id": "Yk9wQmJ4TA==",
        "group_name": "Northwest Region",
        "parent_id": 12,
        "companyGroupArr": [91],
        "companyArr": [412, 413],
        "userList": 0
      }'

Success response — 200 OK

{
  "error": false,
  "message": "Company group details saved successfully.",
  "msg": "Information saved successfully",
  "userAccessUpdated": true,
  "alertMsg": 1
}

Errors

Notes

• Attaching or detaching companies and child groups fans out into user_company_mapping / user_group_access so members' effective access follows the new membership; that fan-out is what sets userAccessUpdated.
• userList carries the Manager select value and is the field that maintains company_group.manager from this screen.

Renders a preview of where a group and its selected children/companies would sit in the tree, using unsaved checkbox state.

Request body

Example request

curl -X POST https://api.example.com/api/company-group/placement \
  -H 'Content-Type: application/json' \
  -b 'genie.sid=<session-cookie>' \
  -d '{"company_group_id": "Yk9wQmJ4TA==", "parent_id": 12, "companyGroupArr": [91], "companyArr": [412]}'

Success response — 200 OK

{
  "placementTree": [
    {
      "id": 12,
      "encryptId": "MTI=",
      "name": "All Regions",
      "type": "group",
      "isParent": true,
      "children": [
        {
          "id": 88,
          "encryptId": "Yk9wQmJ4TA==",
          "name": "Northwest Region",
          "type": "group",
          "isActive": true,
          "children": []
        }
      ]
    }
  ]
}

Errors

Notes

• Read-only: nothing is persisted.
• Companies are de-duplicated by id, and a ticked company that is not yet attached to any group is included in the preview.
• Unlike the list, this preview is always scoped to the caller's own firm.

Loads the per-group user-access editor: the assignable users, the module matrix, and the selected user's current grants.