> ## 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.

# Account mapping

> Understanding how Thena automatically links tickets to customer accounts during creation

When a new ticket is created in Thena, the platform automatically attempts to identify and link it to the appropriate customer account. This intelligent mapping process ensures every ticket is properly associated with the right customer for better organization and relationship management.

<Note>
  Account mapping happens automatically during ticket creation using a priority-based resolution system. No manual intervention is required in most cases, though the results can be reviewed and adjusted if needed.
</Note>

## How account mapping works

Thena follows a priority-based approach to determine the best account match for each incoming ticket:

<CardGroup cols={2}>
  <Card title="High priority sources" icon="bolt">
    • Direct account ID <br />
    • Slack channel association <br />
    • Explicit customer reference
  </Card>

  <Card title="Fallback methods" icon="arrows-turn-right">
    • Email domain matching <br />
    • Customer contact lookup <br />
    • Automatic account creation
  </Card>
</CardGroup>

## Mapping scenarios

### Scenario 1: Direct account reference

**When it happens:** The ticket creation request explicitly includes an account ID.

**Process:**

<Steps>
  <Step title="Account lookup">
    Thena immediately searches for the specified account ID
  </Step>

  <Step title="Validation">
    If the account exists, the ticket is linked immediately
  </Step>

  <Step title="Fallback">
    If the account doesn't exist, the system continues with other mapping methods
  </Step>
</Steps>

**Result:** Highest success rate when the account ID is valid.

**Example:** API calls or form submissions that include the account identifier like `"accountId": "acc_123456"`.

***

### Scenario 2: Slack channel mapping

**When it happens:** A ticket is created from a Slack channel that's associated with a customer account.

**Process:**

<Steps>
  <Step title="Channel lookup">
    System searches for accounts linked to the specific Slack channel
  </Step>

  <Step title="Single match">
    If exactly one account is found, ticket is automatically linked
  </Step>

  <Step title="Multiple matches">
    If multiple accounts match, proceed to email-based resolution
  </Step>

  <Step title="No matches">
    If no accounts match, continue with email domain resolution
  </Step>
</Steps>

**Example:** Customer support requests in dedicated Slack channels like `#customer-acme-corp`.

***

### Scenario 3: Email domain resolution

**When it happens:** Thena uses the requester's email domain to find matching accounts.

**Process:**

<Steps>
  <Step title="Domain extraction">
    Extract domain from email (e.g., `support@company.com` → `company.com`)
  </Step>

  <Step title="Public domain check">
    Skip resolution for public domains like gmail.com, yahoo.com
  </Step>

  <Step title="Primary domain search">
    Search accounts with matching primary domains
  </Step>

  <Step title="Secondary domain search">
    If no primary matches, check secondary domains
  </Step>

  <Step title="Conflict resolution">
    If multiple matches found, ticket created without account
  </Step>
</Steps>

**Results:**

* **Single match:** Ticket linked to matching account
* **Multiple matches:** Conflict prevents automatic linking
* **No matches:** Proceeds to account creation logic

**Example:** A ticket from `john@acmecorp.com` gets linked to the "Acme Corporation" account.

<Warning>
  Public email domains (gmail.com, yahoo.com, etc.) are automatically excluded from domain-based account mapping to prevent incorrect associations.
</Warning>

***

### Scenario 4: Customer contact resolution

**When it happens:** Multiple accounts match a Slack channel, so Thena checks if the requester is a known contact.

**Process:**

<Steps>
  <Step title="Contact lookup">
    Search for the requester's email in existing customer contacts
  </Step>

  <Step title="Account association">
    Check which accounts the contact is associated with
  </Step>

  <Step title="Cross-reference">
    Match contact's accounts with potential candidates
  </Step>

  <Step title="Resolution">
    Link ticket if exactly one account matches
  </Step>
</Steps>

**Result:** Helps resolve conflicts when multiple accounts could potentially match.

***

### Scenario 5: Automatic account creation

**When it happens:** No existing account matches are found and automatic account creation is enabled.

**Conditions:**

<AccordionGroup>
  <Accordion title="Prerequisites for account creation">
    * No account ID provided
    * No Slack channel matches
    * No domain matches found
    * Email domain is not public (gmail.com, yahoo.com, etc.)
    * Team settings allow automatic account creation
  </Accordion>

  <Accordion title="Account creation process">
    * New account created using the email domain as the primary domain
    * Ticket automatically linked to the new account
    * Customer contact created for the requester
    * Account name derived from domain (e.g., "acmecorp.com" → "Acmecorp")
  </Accordion>
</AccordionGroup>

**Result:**

* ✅ New account created and linked to ticket
* ✅ Customer contact established
* ✅ Future tickets from same domain will link automatically

<Info>
  Automatic account creation is disabled for public email domains to prevent creating accounts for personal email addresses like gmail.com or yahoo.com.
</Info>

### Organization-wide policies

<CardGroup cols={2}>
  <Card title="Domain policies" icon="globe">
    **Primary domains:** Main email domain for the organization <br />
    **Secondary domains:** Additional domains (acquisitions, subsidiaries) <br />
    **Public domains:** Excluded from automatic mapping
  </Card>

  <Card title="Audit settings" icon="list-check">
    **Activity logging:** Track all mapping decisions <br />
    **Success tracking:** Monitor mapping accuracy <br />
    **Conflict reporting:** Identify mapping issues
  </Card>
</CardGroup>

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="Tickets not linking to accounts" icon="unlink">
    **Symptoms:** Tickets consistently created without account attachments

    **Potential causes:**

    * Email domain doesn't match account's primary or secondary domains
    * Slack channel is not properly mapped to the account
    * Automatic account creation is disabled when needed
    * Public domain restrictions are blocking legitimate domains

    **Solutions:**

    * Verify domain assignments across accounts
    * Check Slack channel mappings in account settings
    * Review team configuration for account creation settings
    * Update public domain exclusion list if needed
  </Accordion>

  <Accordion title="Multiple account conflicts" icon="triangle-exclamation">
    **Symptoms:** Tickets created without accounts due to multiple matches

    **Potential causes:**

    * Overlapping domain assignments across accounts
    * Multiple accounts for the same organization
    * Inconsistent domain configuration

    **Solutions:**

    * Review domain assignments across accounts
    * Consolidate duplicate accounts where appropriate
    * Use more specific secondary domains
    * Manually resolve conflicts when they occur
  </Accordion>

  <Accordion title="Unexpected account associations" icon="file-x">
    **Symptoms:** Tickets getting linked to incorrect accounts

    **Potential causes:**

    * Broad domain assignments causing incorrect matches
    * Shared email domains across multiple organizations
    * Incorrect Slack channel mappings

    **Solutions:**

    * Review and refine domain assignments for precision
    * Use more specific secondary domains for disambiguation
    * Verify Slack channel mappings are accurate
    * Consider manual account assignment for ambiguous cases
  </Accordion>
</AccordionGroup>

### When to manually intervene

<CardGroup cols={2}>
  <Card title="Complex scenarios" icon="puzzle-piece">
    • Organizations with overlapping domains <br />
    • Temporary email addresses <br />
    • Unusual domain configurations <br />
    • Legacy data migration issues
  </Card>

  <Card title="High-value situations" icon="star">
    • Enterprise customer accounts <br />
    • Strategic partnership tickets <br />
    • Escalated support cases <br />
    • Compliance-sensitive situations
  </Card>
</CardGroup>

### Manual override procedures

<Steps>
  <Step title="Immediate correction">
    * Account mapping decisions can be reviewed immediately after ticket creation
    * Use the ticket edit function to manually assign the correct account
  </Step>

  <Step title="Process improvement">
    * Analyze patterns in manual overrides to identify system improvements
    * Update domain configurations based on override patterns
  </Step>
</Steps>

<Info>
  All account mapping decisions can be reviewed and manually adjusted after ticket creation if needed. The system maintains a full audit trail of both automatic and manual account associations.
</Info>

## The account mapping flow

```mermaid theme={null}
flowchart TD
    A["New Ticket Created"] --> B{"Account ID<br>Provided?"}
    
    %% Step 1: Account ID with Fallback Logic
    B -- Yes --> C["Find Account<br>by ID"]
    C --> D{"Account<br>Found?"}
    D -- Yes --> E["✅ Account<br>Successfully<br>Linked"]
    D -- No --> F["⚠️ Account ID<br>Not Found<br>Continue Fallback"]
    
    E --> G{"Has Slack<br>Channel Info?"}
    G -- Yes --> H["Check Metadata<br>Update Needed"]
    G -- No --> AUDIT["Create<br>Activity Logs"]
    H -- Updated --> H1["✅ Account<br>Updated"]
    H -- No Update --> AUDIT
    H1 --> AUDIT
    
    %% Step 2: Slack Channel ID Lookup (including fallback cases)
    B -- No --> I{"Slack Channel<br>Provided?"}
    F --> I
    I -- No --> J["Skip Account<br>Resolution"]
    I -- Yes --> K["Search Accounts<br>by Slack Channel"]
    
    K --> L{"How Many<br>Accounts Found?"}
    L -- 0 --> M["❌ No Account<br>Found"]
    L -- 1 --> N{"Is This<br>Fallback?"}
    N -- Yes --> N1["✅ Account Found<br>via Fallback"]
    N -- No --> N2["✅ Account<br>Found"]
    L -- Multiple --> O["Try Email<br>Resolution"]
    
    %% Enhanced Email Resolution with Public Domain Check
    O --> P["Extract Email<br>Domain"]
    P --> Q{"Is Email<br>Domain Public?"}
    Q -- Yes --> R["🛡️ Skip Email<br>Resolution"]
    Q -- No --> S{"Customer<br>Contact Exists?"}
    
    R --> T["❌ No Account<br>Attached"]
    
    S -- Yes --> U["Check Contact's<br>Accounts"]
    U --> V{"Contact Account<br>Matches?"}
    V -- 1 Match --> W{"Is This<br>Fallback?"}
    W -- Yes --> W1["✅ Account<br>Resolved via<br>Fallback"]
    W -- No --> W2["✅ Account<br>Resolved"]
    V -- No Match --> X["Try Domain<br>Resolution"]
    
    S -- No --> X
    
    %% Domain Resolution (Primary & Secondary)
    X --> Y["Check Primary<br>Domain Matches"]
    Y --> Z{"Primary Domain<br>Matches?"}
    Z -- 1 Match --> AA["✅ Account<br>Found"]
    Z -- No Match --> BB["Check Secondary<br>Domains"]
    Z -- Multiple --> CC["❌ Multiple<br>Conflicts"]
    
    BB --> DD{"Secondary<br>Domain Matches?"}
    DD -- 1 Match --> EE["✅ Account<br>Found"]
    DD -- No Match --> FF["❌ No Domain<br>Matches"]
    DD -- Multiple --> GG["❌ Multiple<br>Conflicts"]
    
    %% Unresolved Conflicts Flow to No Account
    CC --> T
    FF --> T
    GG --> T
    
    %% Customer Contact Creation Flow
    J --> HH["Create Customer<br>Contact"]
    M --> HH
    N1 --> HH
    N2 --> HH
    W1 --> HH
    W2 --> HH
    AA --> HH
    EE --> HH
    T --> HH
    
    HH --> II["Process Customer<br>Contact"]
    II --> JJ{"Existing Contact<br>Found?"}
    
    %% Existing Contact Path
    JJ -- Yes --> KK{"Contact Has<br>Accounts?"}
    KK -- Yes --> LL["Use Existing<br>Contact with<br>Accounts"]
    KK -- No --> MM{"Auto-Create<br>Accounts<br>Enabled?"}
    MM -- No --> NN["Contact Remains<br>Without Account"]
    MM -- Yes --> OO{"Email Domain<br>Public?"}
    OO -- Yes --> PP["❌ Skip Account<br>Creation"]
    OO -- No --> QQ["Create Account<br>for Contact"]
    
    %% New Contact Path
    JJ -- No --> RR{"Auto-Create<br>Accounts<br>Enabled?"}
    RR -- No --> SS["Create Contact<br>Only"]
    RR -- Yes --> TT{"Email Domain<br>Public?"}
    TT -- Yes --> UU["❌ Skip Account<br>Creation"]
    TT -- No --> VV["Create Account<br>from Domain"]
    
    %% Account Creation with Flag Detection
    QQ --> WW["Process Account<br>Creation"]
    VV --> WW
    WW --> XX{"Account Creation<br>Result?"}
    XX -- Failed --> YY["❌ Multiple<br>Accounts Conflict"]
    XX -- Existing Found --> ZZ["✅ Existing<br>Account Found"]
    XX -- New Created --> AAA["✅ New Account<br>Created"]
    
    %% Final Account Status Check
    LL --> BBB{"Final Account<br>Status?"}
    NN --> CCC{"Final Account<br>Status?"}
    PP --> CCC
    SS --> CCC
    UU --> CCC
    YY --> CCC
    ZZ --> BBB
    AAA --> BBB
    
    CCC -- No Account --> DDD["❌ Ticket Created<br>Without Account"]
    BBB -- Has Account --> EEE["✅ Ticket Created<br>With Account"]
    
    %% Enhanced Audit Log Creation
    DDD --> FFF["📋 Create<br>No-Attachment<br>Logs"]
    EEE --> GGG{"New Account<br>Created?"}
    GGG -- Yes --> HHH["Create Account<br>Creation Log"]
    GGG -- No --> III["Skip Account<br>Creation Log"]
    HHH --> JJJ["Create Ticket<br>Attachment Log"]
    III --> JJJ
    JJJ --> KKK{"Account Info<br>Updated?"}
    KKK -- Yes --> LLL["Create<br>Update Log"]
    KKK -- No --> FFF
    LLL --> FFF
    
    FFF --> MMM["🎯 Ticket<br>Successfully<br>Created"]
    
    %% Enhanced Styling with New Categories
    classDef successNode fill:#e8f5e8,stroke:#2d5a2d,color:#1a4a1a,stroke-width:3px,font-weight:bold
    classDef errorNode fill:#ffeaea,stroke:#8b2a2a,color:#6b1f1f,stroke-width:3px,font-weight:bold
    classDef processNode fill:#f0f4f8,stroke:#4a5d6b,color:#2c3e50,stroke-width:2px,font-weight:bold
    classDef decisionNode fill:#fff8e1,stroke:#b8860b,color:#8b6914,stroke-width:2px,font-weight:bold
    classDef auditNode fill:#e3f2fd,stroke:#1565c0,color:#0d47a1,stroke-width:2px,font-weight:bold
    classDef fallbackNode fill:#fff0e6,stroke:#cc7a00,color:#cc7a00,stroke-width:2px,font-weight:bold
    classDef securityNode fill:#e6f3ff,stroke:#0066cc,color:#0066cc,stroke-width:2px,font-weight:bold
    classDef startEndNode fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c,stroke-width:3px,font-weight:bold
    
    A:::startEndNode
    MMM:::startEndNode
    E:::successNode
    N1:::successNode
    N2:::successNode
    W1:::successNode
    W2:::successNode
    AA:::successNode
    EE:::successNode
    LL:::successNode
    ZZ:::successNode
    AAA:::successNode
    EEE:::successNode
    M:::errorNode
    T:::errorNode
    PP:::errorNode
    YY:::errorNode
    DDD:::errorNode
    CC:::errorNode
    FF:::errorNode
    GG:::errorNode
    HH:::processNode
    II:::processNode
    WW:::processNode
    FFF:::processNode
    III:::processNode
    JJJ:::processNode
    B:::decisionNode
    D:::decisionNode
    G:::decisionNode
    I:::decisionNode
    L:::decisionNode
    N:::decisionNode
    Q:::decisionNode
    S:::decisionNode
    V:::decisionNode
    W:::decisionNode
    Z:::decisionNode
    DD:::decisionNode
    JJ:::decisionNode
    KK:::decisionNode
    MM:::decisionNode
    OO:::decisionNode
    RR:::decisionNode
    TT:::decisionNode
    XX:::decisionNode
    BBB:::decisionNode
    CCC:::decisionNode
    GGG:::decisionNode
    KKK:::decisionNode
    AUDIT:::auditNode
    H1:::auditNode
    HHH:::auditNode
    LLL:::auditNode
    F:::fallbackNode
    R:::securityNode
    UU:::securityNode
```

This comprehensive flow shows how Thena systematically attempts to link every ticket to an appropriate account through multiple resolution strategies.

## Related resources

<CardGroup cols={2}>
  <Card title="Account management" icon="building" href="/platform/core-concepts/accounts/overview">
    Learn about managing customer accounts
  </Card>

  <Card title="Ticket creation" icon="ticket" href="/platform/core-concepts/tickets/overview">
    Understanding the ticket creation process
  </Card>

  <Card title="Team configuration" icon="users-gear" href="/platform/core-concepts/teams/overview">
    Configure team settings and behaviors
  </Card>

  <Card title="Moving tickets" icon="arrow-right-arrow-left" href="/platform/core-concepts/tickets/team-migration">
    Learn about moving tickets between teams
  </Card>
</CardGroup>