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

# Data Model

> Understand the core entities and relationships in Trackly SMS

This page explains the core entities in Trackly SMS and how they relate to each other.

## Entity Overview

```
Account (root tenant)
├── SendingList (phone number + config)
│   └── ListContact (subscription state)
│       └── Contact (global phone record)
├── Audience (segment definition)
├── Schedule (campaign)
├── MessageCreative (template)
├── WelcomeJourney (automation)
├── Offer (affiliate offer)
└── User (team member)
```

## Account

The **Account** is your organization's workspace. It's the root container for all your data.

| Field       | Description                     |
| ----------- | ------------------------------- |
| Name        | Organization name               |
| Owner email | Primary contact                 |
| Status      | active, suspended, deleted      |
| Settings    | Messaging config, bot filtering |

One user can access multiple accounts with different roles.

## SendingList

A **SendingList** represents a phone number configuration.

| Field        | Description                                   |
| ------------ | --------------------------------------------- |
| Phone number | The "from" number                             |
| Provider     | The list's provider integration (`list_type`) |
| Brand name   | Display name                                  |
| Credentials  | Provider-specific config                      |
| Status       | active, inactive                              |

Contacts subscribe to lists. Messages are sent from lists.

## Contact

A **Contact** is a global phone number record. The same phone number exists once across the system.

| Field        | Description            |
| ------------ | ---------------------- |
| Phone number | E.164 format           |
| Carrier      | Detected carrier       |
| Line type    | cell, VOIP, landline   |
| Timezone     | Derived from area code |

## ListContact

A **ListContact** connects a Contact to a SendingList—the subscription relationship.

| Field          | Description          |
| -------------- | -------------------- |
| Status         | active, unsubscribed |
| Signup date    | When they joined     |
| Signup method  | API, import, form    |
| Custom fields  | Account-defined data |
| Activity stats | Denormalized metrics |

Activity stats include:

* `last_sent_at`, `last_clicked_at`
* `send_count`, `click_count`
* `revenue_total`, `conversion_count`

## Audience

An **Audience** defines a segment of contacts using filter conditions.

| Field       | Description          |
| ----------- | -------------------- |
| Name        | Display name         |
| Lists       | Which lists to query |
| Conditions  | Filter rules         |
| Cached size | Estimated count      |

Audiences contain **AudienceGroups** with **AudienceConditions** for AND/OR logic.

## Schedule

A **Schedule** is a campaign configuration.

| Field           | Description               |
| --------------- | ------------------------- |
| Name            | Campaign name             |
| Sending list    | Which number to send from |
| Audiences       | Who to target             |
| Send type       | blast, automated          |
| Schedule config | One-time, recurring       |

Schedules contain **ScheduleBlasts** (message variants with offers).

## MessageCreative

A **MessageCreative** is a reusable message template.

| Field          | Description                    |
| -------------- | ------------------------------ |
| Body           | Message text with placeholders |
| Offer bindings | Link → Offer mappings          |
| Type           | one\_time, automated, welcome  |
| Status         | active, paused, archived       |
| Performance    | Sends, clicks, revenue         |

## WelcomeJourney

A **WelcomeJourney** is an automated sequence.

| Field              | Description           |
| ------------------ | --------------------- |
| Name               | Journey name          |
| Trigger conditions | When to enroll        |
| Status             | draft, active, paused |

Journeys contain **JourneySteps** (send, wait, condition, exit).

**JourneyEnrollment** tracks each contact's progress through a journey.

## Offer

An **Offer** represents an affiliate offer.

| Field        | Description         |
| ------------ | ------------------- |
| Name         | Offer name          |
| Tracking URL | Destination         |
| Payout       | CPA/CPC amount      |
| Source       | TUNE, manual, etc.  |
| Performance  | Clicks, conversions |

## MessageSent

A **MessageSent** records each sent message.

| Field        | Description                     |
| ------------ | ------------------------------- |
| Contact      | Who received it                 |
| Creative     | What template                   |
| Sending list | From number                     |
| Schedule     | Campaign source                 |
| Status       | queued, sent, delivered, failed |

## MessageShortLink

A **MessageShortLink** is a tracked URL in a message.

| Field       | Description          |
| ----------- | -------------------- |
| Link ID     | Short code (7 chars) |
| Destination | Original URL         |
| Offer       | Associated offer     |

**MessageShortLinkClick** logs each click event.

## User

A **User** is a person with dashboard access.

| Field    | Description                 |
| -------- | --------------------------- |
| Email    | Login email                 |
| Status   | Active, pending             |
| Accounts | List of accessible accounts |

**AccountAccess** defines role per account (Owner, Member, Viewer).

## Relationships Diagram

```
                    ┌─────────────┐
                    │   Account   │
                    └──────┬──────┘
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                 ▼
   ┌───────────┐    ┌───────────┐    ┌───────────┐
   │SendingList│    │  Schedule │    │  Audience │
   └─────┬─────┘    └─────┬─────┘    └───────────┘
         │                │
         ▼                ▼
   ┌───────────┐    ┌───────────┐
   │ListContact│    │ScheduleBlast│
   └─────┬─────┘    └─────┬─────┘
         │                │
         ▼                ▼
   ┌───────────┐    ┌───────────┐
   │  Contact  │    │  Creative │
   └───────────┘    └─────┬─────┘
                          │
                          ▼
                    ┌───────────┐
                    │   Offer   │
                    └───────────┘
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Message Lifecycle" icon="arrows-spin" href="/concepts/message-lifecycle">
    How messages flow through the system
  </Card>

  <Card title="Compliance" icon="shield" href="/concepts/compliance">
    Opt-out and regulations
  </Card>
</CardGroup>