Last updated: Sep 11, 2025, 03:42 PM UTC

Entity Verification Implementation Guide

Overview

This guide documents the implementation of entity verification for organization research after onboarding. The system now uses a template-based approach to first verify the organization's identity before conducting full research.

Problem Solved

Previously, the system would:

  • Use whatever company name/URL was provided without verification
  • Risk researching the wrong organization
  • Not handle ambiguous company names
  • Generate prompts programmatically with hardcoded strings

Solution Implemented

1. Template-Based Prompt System

Created /docs/prompts/organization-entity-verification-prompt.md which provides:

  • Phase 1: Entity identification and verification
  • Phase 2: Comprehensive research after confirmation
  • Handles multiple match scenarios with disambiguation

2. Updated Backend Logic

Modified /server/routes/profile.js:

  • generateOrganizationResearchPrompt() now reads from MD template
  • Replaces template variables based on available data
  • Handles cases with:
    • Only company name
    • Only website URL
    • Both name and URL
    • Neither (asks for input)

3. Entity Verification Flow

graph TD A[User provides company info] --> B{What's provided?} B -->|Name only| C[Search by name] B -->|URL only| D[Identify by URL] B -->|Both| E[Verify name+URL] B -->|Neither| F[Request info] C --> G[Present organization profile] D --> G E --> G G --> H{Multiple matches?} H -->|Yes| I[Show numbered options] H -->|No| J[Single profile] I --> K[User selects] J --> L[User confirms] K --> L L --> M{Confirmed?} M -->|Yes| N[Proceed with full research] M -->|No| O[Search again]

Key Features

Entity Profile Format

**Organization Profile:**
- **Full Name**: Knowcode Ltd
- **Type**: Technology consultancy
- **Location**: London, United Kingdom
- **Founded**: 2021
- **Website**: knowcode.tech
- **Description**: AI-powered business solutions consultancy
- **Size**: 10-50 employees
- **Key Services**: AI integration, process automation

Disambiguation Handling

When multiple organizations match, the system presents:

1. **Company A** - Industry, Location
2. **Company B** - Industry, Location
3. **Company C** - Industry, Location

Which organization would you like me to research?

Testing

Test Scenarios

  1. Only company name provided
  2. Only website URL provided
  3. Both name and URL provided
  4. With uploaded documents
  5. No information provided

Test Command

node test-entity-verification-prompt.js

Benefits

  1. Accuracy: Ensures correct organization is researched
  2. User Confidence: Clear verification step builds trust
  3. Flexibility: Handles various input scenarios gracefully
  4. Maintainability: Template-based approach easier to update
  5. Professional: Business-friendly presentation of findings

Usage

Frontend

Users can provide:

  • Just company name: "Knowcode"
  • Just website: "knowcode.tech"
  • Both: Name and URL
  • Documents: Optional uploads for context

Backend API

POST /api/profile/organization/complete
Body: {
  companyName: "Knowcode",    // Optional
  website: "knowcode.tech",   // Optional
  industry: "Technology",     // Optional
  documents: [files]          // Optional
}

Generated Prompt

The system generates a prompt that:

  1. First identifies/verifies the entity
  2. Asks for user confirmation
  3. Proceeds with full research after confirmation

Future Enhancements

  1. API Integration: Could integrate with company data APIs for richer profiles
  2. Caching: Store verified entities to avoid repeated searches
  3. Confidence Scoring: Add confidence levels to matches
  4. International Support: Handle companies in different regions/languages
  5. Industry Classification: Auto-detect industry from company data

Files Modified

  • /docs/prompts/organization-entity-verification-prompt.md - New template
  • /server/routes/profile.js - Updated to use template
  • /docs/prompts/entity-verification-implementation-guide.md - This guide

Related Documentation