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

# Start an ownership search

Submit up to 500 physical business locations for asynchronous operator resolution. Every accepted submission creates a new batch and returns `202 Accepted`.

Every location must include `name` and `address`. You may optionally provide `phone`, `email`, and `website` to improve matching.

```bash theme={null}
curl -s -X POST 'https://api.govfiles.dev/v2/local-businesses/batches' \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $GOVFILES_API_KEY" \
  -d '{
    "locations": [{
      "customer_record_id": "location-123",
      "name": "Example Kitchen",
      "address": "105 Paramount Park Drive, Gaithersburg, MD 20879"
    }]
  }'
```

Save the returned `batch_id`. Use it to [poll the batch](/api-reference/endpoints/get-local-business-batch); the succeeded response includes the complete result JSON.

`customer_record_id` may be omitted or set to `null`. The API generates a unique value
and returns it with that location's result.

See [Local-business batches](/guides/local-business-batches) for input rules, states, result semantics, and billing.


## OpenAPI

````yaml POST /v2/local-businesses/batches
openapi: 3.1.0
info:
  title: govfiles Corporate Entity API
  version: 0.2.0
  description: >-
    Search US business entity records and resolve physical local businesses to
    their legal operators and published principals.
servers:
  - url: https://api.govfiles.dev
security: []
tags:
  - name: Health
    description: Service health checks.
  - name: Companies
    description: Corporate entity search and lookup endpoints.
  - name: Officers
    description: Officer, director, and agent search endpoints.
  - name: Local Businesses
    description: >-
      Asynchronous matching of physical businesses to their legal operators and
      published principals.
  - name: Account
    description: Account and billing endpoints.
paths:
  /v2/local-businesses/batches:
    post:
      tags:
        - Local Businesses
      summary: Start an ownership search
      operationId: createLocalBusinessBatch
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocalBusinessBatchRequest'
        required: true
      responses:
        '202':
          description: Batch accepted and queued for asynchronous processing.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/QueuedLocalBusinessBatch'
                    title: Queued
                  - $ref: '#/components/schemas/RunningLocalBusinessBatch'
                    title: Running
                  - $ref: '#/components/schemas/SucceededLocalBusinessBatch'
                    title: Succeeded
                  - $ref: '#/components/schemas/FailedLocalBusinessBatch'
                    title: Failed
                discriminator:
                  propertyName: status
                  mapping:
                    queued:
                      $ref: '#/components/schemas/QueuedLocalBusinessBatch'
                    running:
                      $ref: '#/components/schemas/RunningLocalBusinessBatch'
                    succeeded:
                      $ref: '#/components/schemas/SucceededLocalBusinessBatch'
                    failed:
                      $ref: '#/components/schemas/FailedLocalBusinessBatch'
        '401':
          description: Missing or invalid API key.
        '402':
          description: Insufficient credits.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '503':
          description: The batch request could not be stored or queued.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    LocalBusinessBatchRequest:
      properties:
        locations:
          items:
            $ref: '#/components/schemas/LocalBusinessInput'
          type: array
          maxItems: 500
          minItems: 1
      additionalProperties: false
      type: object
      required:
        - locations
    QueuedLocalBusinessBatch:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        type:
          type: string
          const: local_business_batch
          default: local_business_batch
        location_count:
          type: integer
          maximum: 500
          minimum: 1
        created_at:
          type: string
          format: date-time
        status:
          type: string
          const: queued
      additionalProperties: false
      type: object
      required:
        - batch_id
        - location_count
        - created_at
        - status
    RunningLocalBusinessBatch:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        type:
          type: string
          const: local_business_batch
          default: local_business_batch
        location_count:
          type: integer
          maximum: 500
          minimum: 1
        created_at:
          type: string
          format: date-time
        status:
          type: string
          const: running
        started_at:
          type: string
          format: date-time
      additionalProperties: false
      type: object
      required:
        - batch_id
        - location_count
        - created_at
        - status
        - started_at
    SucceededLocalBusinessBatch:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        type:
          type: string
          const: local_business_batch
          default: local_business_batch
        location_count:
          type: integer
          maximum: 500
          minimum: 1
        created_at:
          type: string
          format: date-time
        status:
          type: string
          const: succeeded
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        result:
          $ref: '#/components/schemas/LocalBusinessBatchResultDocument'
      additionalProperties: false
      type: object
      required:
        - batch_id
        - location_count
        - created_at
        - status
        - started_at
        - completed_at
        - result
    FailedLocalBusinessBatch:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        type:
          type: string
          const: local_business_batch
          default: local_business_batch
        location_count:
          type: integer
          maximum: 500
          minimum: 1
        created_at:
          type: string
          format: date-time
        status:
          type: string
          const: failed
        started_at:
          type:
            - string
            - 'null'
          format: date-time
        completed_at:
          type: string
          format: date-time
      additionalProperties: false
      type: object
      required:
        - batch_id
        - location_count
        - created_at
        - status
        - completed_at
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
      type: object
    LocalBusinessInput:
      properties:
        customer_record_id:
          type:
            - string
            - 'null'
          maxLength: 200
          minLength: 1
        name:
          type: string
          maxLength: 300
          minLength: 1
        address:
          type: string
          maxLength: 1000
          minLength: 1
        phone:
          type:
            - string
            - 'null'
          maxLength: 50
          minLength: 1
        email:
          type:
            - string
            - 'null'
          maxLength: 320
          minLength: 3
        website:
          type:
            - string
            - 'null'
          maxLength: 2048
          minLength: 1
      additionalProperties: false
      type: object
      required:
        - name
        - address
    LocalBusinessBatchResultDocument:
      properties:
        batch_id:
          type: string
          maxLength: 200
          minLength: 7
          pattern: ^batch_[0-9A-Za-z]+$
        status:
          type: string
          const: completed
        summary:
          $ref: '#/components/schemas/LocalBusinessBatchSummary'
        credits_charged:
          type: integer
          minimum: 0
        results:
          items:
            oneOf:
              - $ref: '#/components/schemas/MatchedLocalBusinessResult'
              - $ref: '#/components/schemas/UnmatchedLocalBusinessResult'
          type: array
      additionalProperties: false
      type: object
      required:
        - batch_id
        - status
        - summary
        - credits_charged
        - results
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
        msg:
          type: string
        type:
          type: string
        input: {}
        ctx:
          type: object
      type: object
      required:
        - loc
        - msg
        - type
    LocalBusinessBatchSummary:
      properties:
        submitted:
          type: integer
          minimum: 1
        matched:
          type: integer
          minimum: 0
        unmatched:
          type: integer
          minimum: 0
      additionalProperties: false
      type: object
      required:
        - submitted
        - matched
        - unmatched
    MatchedLocalBusinessResult:
      properties:
        customer_record_id:
          type: string
          maxLength: 200
          minLength: 1
        enriched_at:
          type: string
          format: date
        match:
          $ref: '#/components/schemas/MatchedMatch'
        restaurant:
          $ref: '#/components/schemas/Restaurant'
        operator:
          $ref: '#/components/schemas/Operator'
        people:
          items:
            $ref: '#/components/schemas/Person'
          type: array
      additionalProperties: false
      type: object
      required:
        - customer_record_id
        - enriched_at
        - match
        - restaurant
        - operator
    UnmatchedLocalBusinessResult:
      properties:
        customer_record_id:
          type: string
          maxLength: 200
          minLength: 1
        enriched_at:
          type: string
          format: date
        match:
          $ref: '#/components/schemas/UnmatchedMatch'
        restaurant:
          $ref: '#/components/schemas/Restaurant'
        operator:
          type: 'null'
        people:
          items:
            $ref: '#/components/schemas/Person'
          type: array
          maxItems: 0
      additionalProperties: false
      type: object
      required:
        - customer_record_id
        - enriched_at
        - match
        - restaurant
    MatchedMatch:
      properties:
        status:
          type: string
          const: matched
        relationship_status:
          $ref: '#/components/schemas/RelationshipStatus'
          default: current
      additionalProperties: false
      type: object
      required:
        - status
    Restaurant:
      properties:
        name:
          type: string
          maxLength: 500
          minLength: 1
        phone:
          type:
            - string
            - 'null'
          maxLength: 16
          minLength: 3
          pattern: ^\+[1-9][0-9]{1,14}$
          description: Phone number normalized to E.164 format.
        email:
          type:
            - string
            - 'null'
          maxLength: 320
        website:
          type:
            - string
            - 'null'
          maxLength: 2048
        address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - name
    Operator:
      properties:
        legal_name:
          type: string
          maxLength: 500
          minLength: 1
        entity_type:
          type:
            - string
            - 'null'
          maxLength: 200
        business_registration:
          anyOf:
            - $ref: '#/components/schemas/BusinessRegistration'
            - type: 'null'
        addresses:
          items:
            $ref: '#/components/schemas/LabeledAddress'
          type: array
        last_updated_at:
          type:
            - string
            - 'null'
          format: date
        corporate_parent:
          anyOf:
            - $ref: '#/components/schemas/CorporateParent'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - legal_name
    Person:
      properties:
        name:
          type: string
          maxLength: 500
          minLength: 1
        title:
          type:
            - string
            - 'null'
          maxLength: 200
        role:
          type:
            - string
            - 'null'
          maxLength: 200
        address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - name
      description: A human party published for the matched operator.
    UnmatchedMatch:
      properties:
        status:
          type: string
          const: unmatched
      additionalProperties: false
      type: object
      required:
        - status
    RelationshipStatus:
      type: string
      enum:
        - current
        - historical
    Address:
      properties:
        line1:
          type: string
          maxLength: 300
          minLength: 1
        line2:
          type:
            - string
            - 'null'
          maxLength: 300
        city:
          type: string
          maxLength: 150
          minLength: 1
        state:
          type: string
          pattern: ^[A-Z]{2}$
        postal_code:
          type: string
          maxLength: 20
          minLength: 1
        country:
          type: string
          pattern: ^[A-Z]{2}$
          default: US
      additionalProperties: false
      type: object
      required:
        - line1
        - city
        - state
        - postal_code
    BusinessRegistration:
      properties:
        jurisdiction:
          type: string
          maxLength: 100
          minLength: 1
        registration_number:
          type:
            - string
            - 'null'
          maxLength: 200
        status:
          type:
            - string
            - 'null'
          maxLength: 100
        incorporated_on:
          type:
            - string
            - 'null'
          format: date
        dissolved_on:
          type:
            - string
            - 'null'
          format: date
      additionalProperties: false
      type: object
      required:
        - jurisdiction
    LabeledAddress:
      properties:
        line1:
          type: string
          maxLength: 300
          minLength: 1
        line2:
          type:
            - string
            - 'null'
          maxLength: 300
        city:
          type: string
          maxLength: 150
          minLength: 1
        state:
          type: string
          pattern: ^[A-Z]{2}$
        postal_code:
          type: string
          maxLength: 20
          minLength: 1
        country:
          type: string
          pattern: ^[A-Z]{2}$
          default: US
        type:
          type: string
          maxLength: 100
          minLength: 1
      additionalProperties: false
      type: object
      required:
        - line1
        - city
        - state
        - postal_code
        - type
    CorporateParent:
      properties:
        legal_name:
          type: string
          maxLength: 500
          minLength: 1
      additionalProperties: false
      type: object
      required:
        - legal_name
      description: The legal name of a company principal associated with the operator.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````