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

# Extract data from a file

> Create a new schema extraction job for a file based on predefined schema

## Document schema structure

The `document_schema` object should conform to the following structure.

```json theme={null}
{
  "name": "Invoice",
  "description": "Schema for extracting invoice details",
  "fields": [
    {
      "name": "invoice_number",
      "description": "The unique identifier for the invoice",
      "type": "string"
    },
    {
      "name": "issue_date",
      "description": "The date when the invoice was issued",
      "type": "date"
    },
    {
      "name": "customer",
      "description": "Customer information",
      "type": "object",
      "fields": [
        {
          "name": "name",
          "description": "Customer's full name",
          "type": "string"
        },
        {
          "name": "email",
          "description": "Customer's email address",
          "type": "email"
        }
      ]
    },
    {
      "name": "line_items",
      "description": "List of items in the invoice",
      "type": "array",
      "fields": [
        {
          "name": "description",
          "description": "Item description",
          "type": "string"
        },
        {
          "name": "amount",
          "description": "Item cost",
          "type": "number"
        }
      ]
    }
  ]
}
```

## Primitive fields

* `string`: Generic text data
* `number`: Numeric values
* `email`: Email addresses
* `phone`: Phone numbers
* `date`: Date values

## Objects and arrays

* `object`: Nested object containing additional fields where each field is a primitive field.
* `array`: List of items where each element is an object. As above, fields within each object can be any one of the primitive fields.

## Best Practices

<CardGroup>
  <Card title="Field names" icon="signature">
    Use clear, descriptive names and avoid special characters. We recommend using snake case.
  </Card>

  {" "}

  <Card title="Descriptions" icon="comment">
    Descriptions are critical for accuracy. If you want to consistent formatting,
    include this in the description.
  </Card>

  {" "}

  <Card title="Nested structures" icon="layer-group">
    We support 3 levels of nesting for objects. Where possible, we recommend
    avoiding deeply nested objects as this reduces accuracy.
  </Card>

  <Card title="Nested objects within arrays" icon="layer-group">
    We do not currently support nested objects within arrays. This is on our roadmap.
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /extract
openapi: 3.0.1
info:
  title: tile.run API
  description: API to extract structured data from unstructured files.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tile.run/v1
security: []
paths:
  /extract:
    post:
      summary: Create schema extraction job
      description: Create a new schema extraction job for a file based on predefined schema
      operationId: createSchemaExtraction
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            format: bearer
          description: Bearer token for authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaExtractionRequest'
        required: true
      responses:
        '201':
          description: Schema extraction job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaExtractionResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: cca34f95-95a3-401b-8b33-89eb24fdcc2a
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: cca34f95-95a3-401b-8b33-89eb24fdcc2a
      externalDocs:
        description: Learn more about schema extraction
        url: https://docs.tile.run/api-reference/schema_definition
components:
  schemas:
    SchemaExtractionRequest:
      type: object
      required:
        - file_id
        - document_schema
      properties:
        file_id:
          type: string
          description: ID of the uploaded file to process
        document_schema:
          type: object
          description: Schema definition for extraction
    SchemaExtractionResponse:
      type: object
      required:
        - extraction_id
        - status
        - created_at
      properties:
        extraction_id:
          type: string
          description: ID of the created extraction job
        status:
          type: string
          description: Current status of the job
        created_at:
          type: string
          format: date-time
          description: When the job was created

````