> ## 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.

# Report a Data Issue

> Report an inaccuracy in a person or company record so the Data Legion team can review and correct it. No credit cost; available to any API key.

## How It Works

Found something wrong in a record we returned? Report it against the record's `legion_id` and our team will review it. Reporting has **no credit cost**, is available to any valid API key, and is rate limited to 50 requests per minute.

* **People:** `POST /utility/report/person`
* **Companies:** `POST /utility/report/company`

The request body is identical for both — the path selects the entity. We capture the record's current data version at submit time, so the reviewer sees exactly what you saw.

## What to Report

Set `issue_type` to *what* is wrong and `issue_level` to *how broad* the problem is.

### issue\_type

| Value               | Meaning                                                   |
| ------------------- | --------------------------------------------------------- |
| `incorrect`         | A value is wrong                                          |
| `outdated`          | A value was right but is now stale                        |
| `misattributed`     | A value belongs to a different person or company          |
| `frankenstein`      | The record appears to merge multiple real people          |
| `not_a_real_person` | The record is not a real individual (person reports only) |
| `duplicate`         | A duplicated value or record                              |

### issue\_level

| Value    | Meaning                           | `field`                         |
| -------- | --------------------------------- | ------------------------------- |
| `record` | The whole record                  | omit                            |
| `group`  | A field group (e.g. work history) | a group name                    |
| `field`  | A single field                    | a field name (e.g. `job_title`) |

Not every combination is valid — for example, `frankenstein` and `not_a_real_person` are always `record`-level. The API returns `422` with an explanation when:

* the `issue_type` / `issue_level` combination doesn't apply
* the `legion_id` doesn't match an existing record of that type
* the `field` isn't a real group or response field
* the target is a metadata or provenance field (e.g. `confidence`, `last_seen`, `build_version`, hashes) — report the underlying data instead

### Field Groups (for `issue_level: group`)

These are the keys you see in the response. The "current" flat fields fold into their collection — a wrong current job title is `group: experience` (or `field: job_title`), current city is `group: locations`, and so on.

**Person:** `identity`, `experience`, `education`, `emails`, `phones`, `locations`, `socials`, `skills`, `languages`, `certifications`

**Company:** `firmographics`, `domains`, `socials`, `tickers`, `metrics`

Each report must include at least one of `correct_value` or `comment`.

## Examples

A single wrong field:

```bash theme={null}
curl -X POST https://api.datalegion.ai/utility/report/person \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legion_id": "abc123",
    "issue_type": "incorrect",
    "issue_level": "field",
    "field": "job_title",
    "observed_value": "CEO",
    "correct_value": "CTO"
  }'
```

A whole record that looks like two different people:

```bash theme={null}
curl -X POST https://api.datalegion.ai/utility/report/person \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legion_id": "abc123",
    "issue_type": "frankenstein",
    "issue_level": "record",
    "comment": "Work history and education appear to belong to two different people."
  }'
```

Each report returns a `report_id` for your reference.


## OpenAPI

````yaml POST /utility/report/person
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/report/person:
    post:
      tags:
        - report
      summary: Report a data-quality issue with a person record
      description: >-
        Report an issue with a person record identified by legion_id. No credit
        cost; available to any valid API key. Rate limited to 50 requests per
        minute.
      operationId: report_person_utility_report_person_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataIssueReportRequest'
        required: true
      responses:
        '201':
          description: Report recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataIssueReportResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API key is not attributed to a team
          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:
    DataIssueReportRequest:
      properties:
        legion_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Legion Id
          description: The legion_id of the record being reported.
        issue_type:
          type: string
          enum:
            - incorrect
            - outdated
            - misattributed
            - frankenstein
            - not_a_real_person
            - duplicate
          title: Issue Type
          description: >-
            What is wrong. 'frankenstein' = the record appears to merge multiple
            real people; 'not_a_real_person' = not a real individual (person
            reports only); 'misattributed' = a value belongs to a different
            person; 'incorrect' = a value is wrong; 'outdated' = a value is
            stale; 'duplicate' = a duplicated value or record.
        issue_level:
          type: string
          enum:
            - record
            - group
            - field
          title: Issue Level
          description: >-
            Scope of the issue. 'record' = the whole record; 'group' = a field
            group (e.g. experience); 'field' = a single field (e.g. job_title).
        field:
          anyOf:
            - type: string
              maxLength: 128
            - type: 'null'
          title: Field
          description: >-
            Target of the issue. Omit for 'record'. For 'group', a field-group
            slug (e.g. 'experience'). For 'field', a response field name (e.g.
            'job_title').
        observed_value:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Observed Value
          description: The value currently returned that is being disputed.
        correct_value:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Correct Value
          description: The value that would be correct, if known.
        comment:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Comment
          description: Free-text detail about the issue.
      type: object
      required:
        - legion_id
        - issue_type
        - issue_level
      title: DataIssueReportRequest
      description: >-
        Request body for POST /utility/report/{person|company}.


        The entity (person vs company) comes from the path, so it is not in the
        body.
    DataIssueReportResponse:
      properties:
        report_id:
          type: integer
          title: Report Id
        status:
          type: string
          title: Status
        subject_type:
          type: string
          title: Subject Type
        legion_id:
          type: string
          title: Legion Id
        issue_type:
          type: string
          title: Issue Type
        issue_level:
          type: string
          title: Issue Level
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - report_id
        - status
        - subject_type
        - legion_id
        - issue_type
        - issue_level
        - created_at
      title: DataIssueReportResponse
      description: Confirmation returned after a report is recorded.
    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.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: API-Key

````