Create Records From File Reading

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    file_readings: [{}],
    'file_readings[].id': '<string>',
    facilities: [{}],
    'facilities[].id': '<string>',
    'facilities[].percentage': 123,
    project_id: '<string>',
    supplier_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/files/readings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/files/readings"

payload = {
    "file_readings": [{}],
    "file_readings[].id": "<string>",
    "facilities": [{}],
    "facilities[].id": "<string>",
    "facilities[].percentage": 123,
    "project_id": "<string>",
    "supplier_id": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/files/readings \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "file_readings": [
    {}
  ],
  "file_readings[].id": "<string>",
  "facilities": [
    {}
  ],
  "facilities[].id": "<string>",
  "facilities[].percentage": 123,
  "project_id": "<string>",
  "supplier_id": "<string>"
}
'

POST

files

readings

Create Records From File Reading

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    file_readings: [{}],
    'file_readings[].id': '<string>',
    facilities: [{}],
    'facilities[].id': '<string>',
    'facilities[].percentage': 123,
    project_id: '<string>',
    supplier_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/files/readings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/files/readings"

payload = {
    "file_readings": [{}],
    "file_readings[].id": "<string>",
    "facilities": [{}],
    "facilities[].id": "<string>",
    "facilities[].percentage": 123,
    "project_id": "<string>",
    "supplier_id": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/files/readings \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "file_readings": [
    {}
  ],
  "file_readings[].id": "<string>",
  "facilities": [
    {}
  ],
  "facilities[].id": "<string>",
  "facilities[].percentage": 123,
  "project_id": "<string>",
  "supplier_id": "<string>"
}
'

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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body

object[]

required

Array of file reading references. Each item must include an id.

string

required

File reading UUID returned in reading.id from GET /v1/files/readings.

object[]

required

Facilities to link to the created records.

string

required

Facility UUID.

number

required

Allocation percentage as a decimal between 0 and 1. The total must be less than or equal to 1.0.

string

Optional project UUID. When present, created invoices are also linked to that project.

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.

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

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.

Example

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
      }
    ]
  }'

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())

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));

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

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

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

{"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

{
  "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.

List File Readings

Retrieve readings to get file reading IDs

Update Reading

Edit extracted content before creating records

Upload Files

Upload new files via presigned S3 URLs

List Invoices

View invoices created from file readings

Update File Reading Facilities API

​Create Records From File Reading

​Request

​Headers

​Body

​Response

​Current Limitation

​Example

​Behavior by Category

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Notes

​Related Endpoints

List File Readings

Update Reading

Upload Files

List Invoices

Create Records From File Reading

Request

Headers

Body

Response

Current Limitation

Example

Behavior by Category

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Notes

Related Endpoints