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

# Companies

> Understanding company records in Roulette

# Companies

Companies are the core entity in Roulette, representing potential investment opportunities in your deal flow pipeline.

## Company Properties

Each company record contains the following key properties:

| Property            | Type      | Description                                                |
| ------------------- | --------- | ---------------------------------------------------------- |
| `id`                | UUID      | Unique identifier                                          |
| `account_id`        | UUID      | The team/account this company belongs to                   |
| `name`              | string    | Company name                                               |
| `deck_link`         | string    | URL to external pitch deck                                 |
| `deck_storage_path` | string    | Internal path to uploaded deck                             |
| `notes`             | string    | Internal notes (not visible to company)                    |
| `company_status_id` | UUID      | Current pipeline stage                                     |
| `company_status`    | object    | Embedded status object with `status_text`, `color`, `rank` |
| `visibility`        | enum      | Access control level (`private`, `shared`, `team`)         |
| `source`            | enum      | How the company was added                                  |
| `source_content`    | string    | Raw source content (e.g., form submission data)            |
| `metadata`          | object    | Custom fields, AI analysis, and founder data               |
| `assignees`         | array     | Team members assigned to this company                      |
| `created_at`        | timestamp | When the record was created                                |
| `updated_at`        | timestamp | When last modified                                         |
| `created_by`        | UUID      | User who created the record                                |
| `updated_by`        | UUID      | User who last updated the record                           |

## Visibility Levels

Companies can have different visibility settings to control who can access them:

<CardGroup cols={3}>
  <Card title="Private" icon="lock">
    Only visible to the user who created it
  </Card>

  <Card title="Shared" icon="user-group">
    Visible to specific users you choose
  </Card>

  <Card title="Team" icon="users">
    Visible to all team members
  </Card>
</CardGroup>

```javascript theme={null}
// Create a private company
const company = await createCompany({
  name: "Stealth Startup",
  visibility: "private",
  // ...
});

// Share with specific users
await addCompanyShare(company.id, { user_id: "user-uuid" });
```

## Sources

Track how companies enter your pipeline:

| Source     | Description                          |
| ---------- | ------------------------------------ |
| `manual`   | Manually added through the UI or API |
| `email`    | Imported from an email               |
| `form`     | Submitted through an integrated form |
| `referral` | Referred by another contact          |
| `website`  | Applied through your website         |
| `event`    | Met at an event or conference        |
| `other`    | Other sources                        |

## Pitch Decks

Roulette supports two ways to attach pitch decks to companies:

### External Links

Link to decks hosted on DocSend, Google Drive, or other platforms:

```json theme={null}
{
  "deck_link": "https://docsend.com/view/abc123"
}
```

### AI-Powered Upload

Use the intelligent upload endpoint to process emails, forms, or any text with deck URLs:

```bash theme={null}
curl -X POST "https://www.useroulette.com/api/v1/companies/upload/ai" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "account_id=YOUR_ACCOUNT_ID" \
  -F "text=Here's our deck: https://docsend.com/view/abc123" \
  -F "name=Acme Corp"
```

You can also upload files directly:

```bash theme={null}
curl -X POST "https://www.useroulette.com/api/v1/companies/upload/ai" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "account_id=YOUR_ACCOUNT_ID" \
  -F "text=Meeting notes from coffee chat" \
  -F "name=Acme Corp" \
  -F "file_0=@pitch-deck.pdf"
```

<Tip>
  The AI endpoint automatically extracts URLs from text, prioritizes deck platforms (DocSend, Papermark, etc.),
  and can analyze content to auto-detect the source and suggest a pipeline status.
</Tip>

## Metadata

The `metadata` field contains structured data including AI-extracted information and custom fields:

```json theme={null}
{
  "metadata": {
    "founders": [
      {
        "name": "Jane Smith",
        "title": "CEO/Co-Founder",
        "email": "jane@example.com",
        "linkedin_profile": "https://linkedin.com/in/janesmith",
        "background": "Former engineer at Google"
      }
    ],
    "ai_analysis": "B2B SaaS platform for enterprise workflow automation...",
    "analyzed_at": "2024-01-15T12:45:00Z",
    "user_preferences": [
      {
        "type": "select",
        "field": "Industry",
        "value": "SaaS",
        "options": ["SaaS", "Fintech", "AI/ML", "Developer Tools"],
        "show_in_table": true
      },
      {
        "type": "text",
        "field": "Check Size",
        "value": "$2M",
        "show_in_table": false
      }
    ]
  }
}
```

### Metadata Structure

| Field              | Description                                                                   |
| ------------------ | ----------------------------------------------------------------------------- |
| `founders`         | Array of founder/team member objects (typically AI-extracted from pitch deck) |
| `ai_analysis`      | AI-generated company summary                                                  |
| `analyzed_at`      | Timestamp of last AI analysis                                                 |
| `user_preferences` | Custom fields configured by your account                                      |

<Note>
  Custom fields (`user_preferences`) are configured at the account level and can include text, boolean, or select types.
</Note>

## Related Resources

<CardGroup cols={2}>
  <Card title="Pipeline Stages" icon="diagram-project" href="/concepts/pipeline">
    Learn about managing deal flow statuses
  </Card>

  <Card title="Companies API" icon="code" href="/api-reference/companies/list">
    View all company endpoints
  </Card>
</CardGroup>