# Custom Records

> Model custom object types beyond contacts and companies — accounts, opportunities, territories, products, or anything specific to your business.

Source: https://docs.graph8.com/studio/custom-records/

Custom Records let you model your own object types in graph8 — beyond the built-in contacts, companies, and deals. If your sales motion tracks things like territories, partners, opportunities, or vertical-specific entities, Custom Records give you a structured place to store them with relationships, attributes, and AI access.

## When to Use Custom Records

Use custom records when:

- You need to track something that doesn't fit contacts, companies, or deals
- You want to reference the object from campaigns, sequences, or skills
- You need to sync the object to/from your CRM as a custom object
- The object has structured fields and relationships to other records

Common examples:

| Object Type | Use Case |
|-------------|----------|
| **Territories** | Sales region with assigned reps and target accounts |
| **Partners** | Channel partners with their own contacts and deals |
| **Products** | SKUs with pricing tiers and configurations |
| **Events** | Conferences, trade shows with attendee contacts |
| **Support Tickets** | Customer issues tied to contacts |
| **Properties** | Real estate listings with locations and attributes |
| **Policies** | Insurance products with contract terms |
| **Vehicles** | Auto sales inventory with specs |

## Creating a Custom Record Type

1. Go to **Studio → Custom Records → New Type**
2. Name the record type (singular and plural, e.g., "Territory" / "Territories")
3. Pick an icon for sidebar navigation
4. Define attributes (see below)
5. Define relationships to other records (see below)
6. Set permissions
7. Click **Create**

Once created, a new menu entry appears in the sidebar for that record type.

## Attributes (Fields)

Each custom record type has its own fields. Add as many as needed.

### Field Types

| Type | Example Use |
|------|-------------|
| **Text (short)** | Name, code, label |
| **Text (long)** | Description, notes |
| **Number** | Target revenue, rank |
| **Currency** | Price, quota |
| **Date** | Start date, end date |
| **Datetime** | Event start time |
| **Boolean** | Active / inactive flag |
| **Dropdown** | Single-select from predefined options |
| **Multi-select** | Multiple options |
| **URL** | External link |
| **Email** | Contact email |
| **Phone** | Phone number with validation |
| **Reference** | Points to another record (contact, company, deal, or custom record) |
| **Formula** | Computed from other fields |
| **AI Field** | Generated by an AI skill when the record is created or updated |

### Field Configuration

For each field:

- **Label** — display name
- **Key** — internal identifier (auto-generated from label, immutable after creation)
- **Required** — must have a value to save the record
- **Unique** — values must be unique across all records of this type
- **Default value** — optional starting value
- **Help text** — shown in the UI when creating/editing records
- **Validation rules** — regex patterns, min/max, etc.

> **Caution:**
> Field **keys** cannot be renamed once created — only labels. If you need a different key, create a new field and migrate data. This keeps formulas, workflows, and API integrations stable.

## Relationships

Custom records can reference other records to model how your data connects.

### Relationship Types

| Type | Example |
|------|---------|
| **One-to-one** | A Territory has one assigned Rep (User) |
| **Many-to-one** | Many Opportunities belong to one Company |
| **One-to-many** | One Territory has many target Companies |
| **Many-to-many** | Partners can sell many Products; Products are sold by many Partners |

### Defining a Relationship

1. In the record type editor, click **Add Relationship**
2. Pick the target record type (contact, company, deal, or custom)
3. Set the cardinality (1:1, many:1, etc.)
4. Name the relationship (e.g., "Assigned Rep", "Parent Territory")
5. Choose cascade behavior:
   - **Cascade delete** — deleting parent deletes children
   - **Restrict delete** — can't delete parent if children exist
   - **Nullify** — deleting parent sets children's reference to null

## Views and Filters

Each record type gets its own list view with AG Grid — same grid engine as Contacts and Companies.

### Default Columns

Configure default columns at **Record Type → Views → Default**. Users can add or hide columns per session.

### Saved Views

Create named views with specific filters and column sets:

- "Active Territories" — filter by `Status = Active`
- "Q1 Opportunities" — filter by close date range
- "Enterprise Partners" — filter by tier

Share views with the team or keep them private.

### Bulk Operations

Like contacts and companies, you can:
- Bulk edit fields
- Bulk delete
- Run skills against every record in a filtered view
- Export to CSV or JSON

## AI Integration

Custom records are first-class citizens for AI actions.

### Skills

Create skills that target a custom record type (see [Skills →](https://docs.graph8.com/studio/skills/)). Variables follow the pattern `{{record.field_key}}`.

Example skill for a "Territory" record:

```
Using the territory {{record.name}} with {{record.account_count}} target accounts and revenue goal of {{record.revenue_target | currency}}, draft a Q1 plan including:
1. Top 5 priority accounts
2. Key campaigns to run
3. Expected pipeline contribution
```

### Agent Access

Voice agents, Copilot, and workflows can all read and write custom records. Grant agent access at **Record Type → Permissions → AI Access**.

### Workflow Triggers

Workflows can trigger on custom record events:

- Created, updated, deleted
- Field changed (specific field transitions)
- Relationship added or removed

## CRM Sync

If your CRM supports custom objects (Salesforce, HubSpot, Pipedrive custom objects), map them to graph8 custom records.

1. Go to **Settings → Integrations → [CRM] → Custom Objects**
2. Select your graph8 record type
3. Map to the CRM's corresponding custom object
4. Map fields (source ↔ destination)
5. Choose sync direction (one-way, two-way)
6. Enable — syncs run on the normal schedule

### Sync Behavior

| Scenario | Behavior |
|----------|----------|
| Record created in graph8 | Pushed to CRM on next sync |
| Record updated in graph8 | Pushed to CRM on next sync |
| Record created in CRM | Pulled into graph8 |
| Simultaneous edits | Conflict resolution per field — configure at the field level |
| Record deleted | Configurable (cascade or soft-delete) |

## Permissions

| Role | Capabilities |
|------|-------------|
| **Admin** | Create/edit/delete record types, all records |
| **Member** | Create/edit/delete records within types they have access to |
| **Viewer** | Read-only access |

Per-record-type permissions can further restrict access. For example, only the Sales team sees Opportunities; everyone sees Territories.

## Limits

| Limit | Default | Upgradable |
|-------|---------|-----------|
| **Custom record types** | 10 | Yes, up to 100 on Enterprise |
| **Fields per type** | 50 | Yes, up to 500 |
| **Records per type** | 100,000 | Yes, up to 10M |
| **Relationships per type** | 20 | Yes |

Check current limits at **Settings → Billing → Plan**.

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Can't delete a record type | Records still exist — delete all records first, or archive the type |
| Field validation failing on import | Check regex patterns and required fields; export sample CSV from the UI for the exact format |
| CRM sync not working for custom object | Verify the CRM user has permissions to the custom object; re-auth the integration |
| AI skill can't find the record | Check that AI Access is enabled for the record type |
| Relationship shows "broken reference" | Target record was deleted with cascade=nullify; re-link manually |

## Related

- [Global Context →](https://docs.graph8.com/studio/global/) — Custom records can feed Global Context
- [Skills →](https://docs.graph8.com/studio/skills/) — Target custom record types in skills
- [Workflows →](https://docs.graph8.com/ai-features/workflows/) — Trigger on custom record events
- [CRM Integrations →](https://docs.graph8.com/settings/integrations/) — Sync custom records to your CRM