> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Understanding accounts and their implementation in the Thena platform

Accounts are the foundational entities that represent customer organizations in the Thena platform. They serve as a central hub for managing customer relationships, hierarchies, and associated business data across all platform services.

## Understanding accounts

<CardGroup cols={1}>
  <Card title="Core purpose" icon="bullseye">
    A central system for managing customer organizations, their relationships, and business operations across the platform. Accounts serve as the foundation for all customer-related activities and data management.
  </Card>

  <Card title="Key features" icon="stars">
    • Complex organizational hierarchies <br />
    • Parent-subsidiary relationships <br />
    • Multi-level account management <br />
    • Comprehensive data tracking <br />
    • Flexible classification system <br />
  </Card>

  <Card title="Integration capabilities" icon="plug">
    • Seamless tickets integration <br />
    • Workflow automation <br />
    • Custom field support <br />
    • API-first architecture <br />
  </Card>
</CardGroup>

<Note>
  Accounts form the backbone of customer relationship management in the Thena platform, providing context for tickets, teams, workflows, and other platform features.
</Note>

### Core capabilities

<CardGroup cols={2}>
  <Card title="Organization management" icon="building-user">
    • Company profiles <br />
    • Business identifiers <br />
    • Industry classification <br />
    • Account health tracking <br />
    • Territory management <br />
  </Card>

  <Card title="Relationship management" icon="diagram-project">
    • Parent-subsidiary links <br />
    • Partner relationships <br />
    • Contact management <br />
    • Team associations <br />
    • Access controls <br />
  </Card>
</CardGroup>

## Standard fields

<Tip>
  All fields support custom validation rules and can be extended with custom fields based on your business needs.
</Tip>

<Note>
  The following fields can be customized with your own values based on your business requirements:

  * `account_status`: Account lifecycle states
  * `account_classification`: Business segmentation
  * `account_health`: Health indicators
  * `account_industry`: Industry categories
  * `contact_type`: Contact role types
  * `activity_type`: Types of activities
  * `activity_status`: Activity states
  * `note_type`: Note categories
  * `task_type`: Task categories
  * `task_status`: Task states
  * `task_priority`: Priority levels
</Note>

### Required fields

| Name           | Type        | Options         | Mandatory for API Creation | Comments                                    |
| -------------- | ----------- | --------------- | -------------------------- | ------------------------------------------- |
| Account ID     | Auto Number | N/A             | No (Auto-generated)        | Unique identifier for each account          |
| Account Name   | Text        | Max length: 255 | Yes                        | Legal/Trading name of the company           |
| Primary Domain | Text        | Max length: 255 | Yes                        | Company's email domain (e.g., @company.com) |

### Optional fields

| Name               | Type      | Options                                       | Mandatory for API Creation | Comments                                        |
| ------------------ | --------- | --------------------------------------------- | -------------------------- | ----------------------------------------------- |
| Secondary Domain   | Text      | Max length: 255                               | No                         | Company's secondary domain                      |
| Logo               | URL       | N/A                                           | No                         | Logo of the company                             |
| Industry           | Picklist  | Technology, Healthcare, Finance, Retail, etc. | No                         | Primary industry of the account                 |
| Description        | Long Text | Max length: 32,768                            | No                         | Additional notes about the account              |
| Annual Revenue     | Currency  | N/A                                           | No                         | Company's reported annual revenue               |
| Employees          | Number    | N/A                                           | No                         | Total number of employees                       |
| Website            | URL       | N/A                                           | No                         | Company's official website                      |
| Billing Address    | Address   | Street, City, State, Country, ZIP             | No                         | Primary address for invoicing                   |
| Shipping Address   | Address   | Street, City, State, Country, ZIP             | No                         | Address for product deliveries                  |
| Status             | Picklist  | PROSPECT, TRIAL, ACTIVE, CHURNED, ACQUIRED    | No                         | Current state of the relationship               |
| Classification     | Picklist  | ENTERPRISE, MID\_MARKET, SMB, STRATEGIC       | No                         | Classification of the account                   |
| Health             | Picklist  | RED, YELLOW, GREEN                            | No                         | Health of the account                           |
| Account Owner      | Lookup    | Active Vendor Users                           | No                         | CRM user responsible for the account            |
| Organization ID    | Lookup    | Organization ID                               | No                         | The platform's Organization ID                  |
| Source             | Text      | Max length: 255                               | No                         | Source of the account (e.g., Slack, Custom App) |
| Created Date       | DateTime  | N/A                                           | No (Auto-generated)        | Timestamp of account creation                   |
| Last Modified Date | DateTime  | N/A                                           | No (Auto-generated)        | Timestamp of last update                        |

## Associated entities

<AccordionGroup>
  <Accordion title="Contacts" icon="address-book" href="/platform/core-concepts/accounts/contacts">
    Customer contacts with roles:

    * Primary contact: Main point of contact
    * Billing contact: Handles financial matters
    * Legal contact: For contractual communications
    * Executive contact: Senior management contact

    [Learn more about Contacts →](/platform/core-concepts/accounts/contacts)
  </Accordion>

  <Accordion title="Activities" icon="calendar-days" href="/platform/core-concepts/accounts/activities">
    Track interactions:

    * Meetings: In-person or virtual discussions
    * Calls: Phone or video conversations
    * Emails: Email communications
    * Site visits: On-premise interactions

    [Learn more about Activities →](/platform/core-concepts/accounts/activities)
  </Accordion>

  <Accordion title="Notes" icon="note-sticky" href="/platform/core-concepts/accounts/notes">
    Document management:

    * General notes: Day-to-day updates
    * Meeting notes: Discussion summaries
    * Call summaries: Call interaction records
    * Email records: Important email documentation

    [Learn more about Notes →](/platform/core-concepts/accounts/notes)
  </Accordion>

  <Accordion title="Tasks" icon="list-check" href="/platform/core-concepts/accounts/tasks">
    Action items:

    * Follow-ups: Scheduled check-ins
    * Reviews: Regular assessments
    * Approvals: Authorization workflows
    * Custom tasks: Business-specific actions

    [Learn more about Tasks →](/platform/core-concepts/accounts/tasks)
  </Accordion>
</AccordionGroup>

### Account relationships

```mermaid theme={null}
flowchart TD
    subgraph Valid Hierarchy
        A[Parent Corp] --> B[Subsidiary 1]
        A --> C[Subsidiary 2]
        B --> D[Sub-subsidiary 1.1]
        B --> E[Sub-subsidiary 1.2]
    end

    subgraph Invalid Cyclic
        X[Company X] --> Y[Company Y]
        Y --> Z[Company Z]
        Z -.->|Not Allowed| X
    end

    style X fill:#f96,stroke:#333
    style Y fill:#f96,stroke:#333
    style Z fill:#f96,stroke:#333
```

<Note>
  The platform enforces relationship rules to prevent cyclic dependencies:

  * Maximum hierarchy depth: No limit
  * No circular relationships allowed
  * Each account can have only one parent
  * Child accounts inherit certain properties from parent
</Note>

## Custom fields

<CardGroup cols={1}>
  <Card title="Extend account capabilities" icon="puzzle-piece">
    The Thena platform allows you to extend account entities with custom fields to capture business-specific data. Common use cases include: <br />
    • Industry-specific metrics <br />
    • Custom scoring models <br />
    • Compliance requirements <br />
    • Integration mappings <br />
    • Business unit specific data <br />
  </Card>
</CardGroup>

<Note>
  Custom fields support various data types including text, number, date, picklist, multi-select, and more. For detailed information about implementing custom fields, refer to our [Custom Fields documentation](/platform/core-concepts/custom-fields/overview).
</Note>

## Best practices

<Steps>
  <Step title="Data quality management">
    * Maintain accurate company information
    * Regular data validation
    * Consistent naming conventions
    * Complete required fields
  </Step>

  <Step title="Relationship management">
    * Document hierarchy changes
    * Track key contacts
    * Monitor account health
    * Regular engagement tracking
  </Step>

  <Step title="Process automation">
    * Set up health scoring rules
    * Configure automated alerts
    * Define workflow triggers
    * Enable team notifications
  </Step>
</Steps>

## API endpoints

### Sample account

```json theme={null}
{
  "name": "Acme Corporation",
  "primaryDomain": "acme.com",
  "description": "Global technology company specializing in cloud infrastructure and AI solutions",
  "source": "hubspot",
  "accountOwnerId": "USER123",
  "logo": "https://acme.com/brand/logo.png",
  "status": "ACTIVE",
  "classification": "ENTERPRISE",
  "health": "GREEN",
  "industry": "TECHNOLOGY",
  "secondaryDomain": "acme.io",
  "annualRevenue": 50000000,
  "employees": 500,
  "website": "https://acme.com",
  "billingAddress": "100 Technology Park, Suite 200, San Francisco, CA 94105, USA",
  "shippingAddress": "100 Technology Park, Suite 200, San Francisco, CA 94105, USA",
  "customFieldValues": [
    {
      "fieldId": "customer_success_tier",
      "value": "premium"
    }
  ],
  "addExistingUsersToAccountContacts": true,
  "metadata": {
    "preferredContactMethod": "email",
    "timezone": "America/Los_Angeles",
    "customerSince": "2023-01-01"
  }
}
```

<Note>
  When creating an account, the system will add additional fields in the response such as `uid`, `createdAt`, `updatedAt`, `isActive`, `memberCount`, and `createdBy`. Only `name` and `primaryDomain` are required fields.
</Note>

### Available operations

<Accordion title="Account management" icon="building">
  ```bash theme={null}
  # List all accounts
  GET /v1/accounts

  # Create account
  POST /v1/accounts
  Content-Type: application/json

  # Get account by ID
  GET /v1/accounts/{id}

  # Update account
  PATCH /v1/accounts/{id}
  Content-Type: application/json

  # Delete account
  DELETE /v1/accounts/{id}
  ```

  <Note>
    All endpoints require authentication and appropriate permissions.
  </Note>

  For detailed API specifications, see <a href="/api-reference/platform/accounts" target="_blank">Account Management</a>
</Accordion>

## Related resources

<CardGroup cols={2}>
  <Card title="Custom fields" icon="rectangle-list" href="/platform/core-concepts/custom-fields/overview">
    Extending accounts with custom fields
  </Card>

  <Card title="Teams" icon="users" href="/platform/core-concepts/teams/overview">
    Managing team access and permissions
  </Card>
</CardGroup>