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

# Data Validation

> Validate person and company data format and get suggestions before sending to search or enrich endpoints.

## How It Works

Pass any combination of person or company fields and receive errors, warnings, and cleaning suggestions. Use this before enrichment or search to catch formatting issues and improve match rates.

## Supported Fields

### Person Fields

`email`, `phone`, `first_name`, `last_name`, `full_name`, `birth_date`, `social_url`, `school`, `address`, `state`, `country`

### Company Fields

`company`, `domain`, `ticker_symbol`, `linkedin_company_url`

## Response

The response includes three sections:

| Section       | Description                                                |
| ------------- | ---------------------------------------------------------- |
| `errors`      | Fields with invalid format that will likely fail matching  |
| `warnings`    | Fields with potential issues that may reduce match quality |
| `suggestions` | Cleaned versions of fields that could improve matching     |


## OpenAPI

````yaml POST /utility/validate
openapi: 3.1.0
info:
  title: Data Legion API
  description: API for enriching, searching, and discovering person and company data
  version: 1.0.0
servers:
  - url: https://api.datalegion.ai
security:
  - APIKeyHeader: []
paths:
  /utility/validate:
    post:
      tags:
        - utility
      summary: Validate person or company data
      description: >-
        Validate person or company data format and provide suggestions before
        sending to search/enrich endpoints. Supports person fields (email,
        phone, name, birth_date, address, state, country, social_url, school)
        and company fields (company, domain, ticker_symbol,
        linkedin_company_url). Rate limited to 100 validations per minute.
      operationId: validate_person_data_utility_validate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationRequest'
        required: true
      responses:
        '200':
          description: Success - validation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
              example:
                valid: true
                errors: []
                warnings:
                  - field: phone
                    value: '+15551234567'
                    warning: Phone number uses reserved 555 prefix
                    suggestion: null
                suggestions:
                  - field: company
                    cleaned:
                      name: google
                      type: name
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required - insufficient credits or expired contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - API key not authorized for this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ValidationRequest:
      properties:
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
        full_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Full Name
        social_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Social Url
        address:
          anyOf:
            - type: string
            - type: 'null'
          title: Address
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
        school:
          anyOf:
            - type: string
            - type: 'null'
          title: School
        birth_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Birth Date
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        ticker_symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Ticker Symbol
        linkedin_company_url:
          anyOf:
            - type: string
            - type: 'null'
          title: LinkedIn Company URL
      type: object
      title: ValidationRequest
      description: Request model for data validation.
      example:
        email: john.doe@example.com
        phone: '+15551234567'
        first_name: John
        last_name: Doe
        domain: google.com
        company: Google LLC
    ValidationResponse:
      properties:
        valid:
          type: boolean
          title: Valid
          description: Whether all data is valid
        errors:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Errors
          description: List of validation errors
        warnings:
          items:
            $ref: '#/components/schemas/ValidationWarning'
          type: array
          title: Warnings
          description: List of validation warnings
        suggestions:
          items:
            $ref: '#/components/schemas/ValidationSuggestion'
          type: array
          title: Suggestions
          description: List of cleaning suggestions
      type: object
      required:
        - valid
      title: ValidationResponse
      description: Response model for data validation.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: Error type/code
        message:
          type: string
          title: Message
          description: Human-readable error message
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - items: {}
              type: array
            - type: 'null'
          title: Details
          description: Additional error details (for validation errors)
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Error response model for customer-facing API.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ValidationWarning:
      properties:
        field:
          type: string
          title: Field
          description: Field name with warning
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
          description: Value that triggered warning
        warning:
          type: string
          title: Warning
          description: Warning message
        suggestion:
          anyOf:
            - type: string
            - type: 'null'
          title: Suggestion
          description: Suggestion for improvement
      type: object
      required:
        - field
        - warning
      title: ValidationWarning
      description: Validation warning detail.
    ValidationSuggestion:
      properties:
        field:
          type: string
          title: Field
          description: Field name
        cleaned:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Cleaned
          description: Suggested cleaned value
      type: object
      required:
        - field
        - cleaned
      title: ValidationSuggestion
      description: Validation suggestion detail.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: API-Key

````