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

# Create Records From File Reading

> Create invoices or wastes from a file reading and link the created records to facilities

# Create Records From File Reading

This endpoint converts a parsed file reading into downstream business records:

* water, electricity, gas, fuel delivery, or recharge invoices
* waste records

Facility linking happens here. You provide the target facilities and allocation percentages, and the created
invoices or wastes are stored with those facility IDs.

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Body

<ParamField body="file_readings" type="object[]" required>
  Array of file reading references. Each item must include an `id`.
</ParamField>

<ParamField body="file_readings[].id" type="string" required>
  File reading UUID returned in `reading.id` from `GET /v1/files/readings`.
</ParamField>

<ParamField body="facilities" type="object[]" required>
  Facilities to link to the created records.
</ParamField>

<ParamField body="facilities[].id" type="string" required>
  Facility UUID.
</ParamField>

<ParamField body="facilities[].percentage" type="number" required>
  Allocation percentage as a decimal between `0` and `1`. The total must be less than or equal to `1.0`.
</ParamField>

<ParamField body="project_id" type="string">
  Optional project UUID. When present, created invoices are also linked to that project.
</ParamField>

<ParamField body="supplier_id" type="string">
  Optional supplier UUID. Only used for electricity readings. When provided, it overrides the
  supplier\_id extracted from the file reading content. Required when any target facility is
  located in Spain and the reading did not resolve a supplier automatically.
</ParamField>

## Response

Returns an array of the created records (HTTP 200). The exact shape depends on the file reading category — invoices for energy categories, waste records for `document::wastes`.

## Current Limitation

<Warning>
  This endpoint currently supports exactly one file reading per request. If you send more than one
  `file_readings` item, the API returns `MULTIPLE_FILES_NOT_SUPPORTED`.
</Warning>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v1/files/readings" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Content-Type: application/json" \
    -d '{
      "file_readings": [
        {
          "id": "22222222-2222-2222-2222-222222222222"
        }
      ],
      "facilities": [
        {
          "id": "33333333-3333-3333-3333-333333333333",
          "percentage": 1.0
        }
      ]
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      "https://api.dcycle.io/v1/files/readings",
      headers={
          "x-api-key": os.environ["DCYCLE_API_KEY"],
          "x-organization-id": os.environ["DCYCLE_ORG_ID"],
          "Content-Type": "application/json",
      },
      json={
          "file_readings": [
              {
                  "id": "22222222-2222-2222-2222-222222222222",
              }
          ],
          "facilities": [
              {
                  "id": "33333333-3333-3333-3333-333333333333",
                  "percentage": 1.0,
              }
          ],
      },
      timeout=30,
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  axios.post('https://api.dcycle.io/v1/files/readings', {
    file_readings: [
      { id: '22222222-2222-2222-2222-222222222222' },
    ],
    facilities: [
      { id: '33333333-3333-3333-3333-333333333333', percentage: 1.0 },
    ],
  }, {
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
      'Content-Type': 'application/json',
    },
  }).then(response => console.log(response.data));
  ```
</CodeGroup>

## Behavior by Category

* `invoice::water` creates water invoices
* `invoice::electricity` creates electricity invoices
* `invoice::gas` and `invoice::fuel_delivery` create combustion invoices
* `invoice::recharges` creates recharge invoices
* `document::wastes` creates waste records

The endpoint determines the category from the file tags, not from the request body.

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

**Cause:** The authenticated user is not a member of the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
```

### 422 Unprocessable Entity

**Cause:** Missing required fields (`file_readings`, `facilities`) or invalid allocation percentages

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["body", "file_readings"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Notes

* This endpoint requires a successful file reading with `content.items`.
* For Spain electricity facilities, supplier information may still be required depending on the extracted reading.
* After records are created, the file will appear as `linked=true` in `GET /v1/files/readings`.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List File Readings" icon="file-lines" href="/api-reference/files/readings">
    Retrieve readings to get file reading IDs
  </Card>

  <Card title="Update Reading" icon="pencil" href="/api-reference/files/update-reading">
    Edit extracted content before creating records
  </Card>

  <Card title="Upload Files" icon="upload" href="/api-reference/files/upload">
    Upload new files via presigned S3 URLs
  </Card>

  <Card title="List Invoices" icon="list" href="/api-reference/invoices/list">
    View invoices created from file readings
  </Card>
</CardGroup>