Skip to main content
POST
/
v1
/
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));

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

​
Headers

​
x-api-key
string
required
API key for authentication.
​
x-organization-id
string
required
Organization UUID that owns the file and facilities.

​
Body

​
file_readings
object[]
required
Array of file reading references. Each item must include an id.
​
file_readings[].id
string
required
File reading UUID returned in reading.id from GET /v1/files/readings.
​
facilities
object[]
required
Facilities to link to the created records.
​
facilities[].id
string
required
Facility UUID.
​
facilities[].percentage
number
required
Allocation percentage as a decimal between 0 and 1. The total must be less than or equal to 1.0.
​
project_id
string
Optional project UUID. When present, created invoices are also linked to that project.
​
supplier_id
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.

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

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

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