--- updatedAt: 2026-05-27T19:28:36.000Z agentTools: projectIndex: https://docs.bayou.energy/llms.txt --- # Upload New Bill Uploads a new bill to parse it Via documentation for more details: # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "version": "2.0", "title": "Bayou Energy API Reference", "x-logo": { "url": "https://images.squarespace-cdn.com/content/v1/6193d0f96f0d901cf36109c2/fdce87d5-4ac6-4b5e-a16d-29bd1228edda/BayouEnergy_final-02.png?format=1500w", "altText": "Bayou Energy" }, "description": "# Introduction\nThis is the documentation page for Bayou Energy's Utility Data API. This API allows you to manage your connected utility accounts and retrieve utility data for those accounts. Learn more about Bayou Energy at [www.bayou.energy](https://bayou.energy).\n\n# Authentication\nWe use API keys to authenticate requests. You can find your API keys in the [Bayou Dashboard](https://bayou.energy/dashboard).\nAuthentication is provided through HTTP Basic Authentication. Use your API key as the username value in the Basic Authentication scheme. The password value does not need to be filled.\n\n# Utility support\nThe list of supported utilities with support details for each specific utility, as well as their API codes, can be found on our [Utility Support documentation page](https://docs.bayou.energy/reference/utility-support).\n\nIn addition to those utilities, you can also use Speculoos Power (code: `speculoos_power`), which is a fictional utility, to be used for testing purposes only.\n\n# External IDs\nTo avoid the need to add a new field in your database as part of your Bayou implementation, all API models come with an `external_id` field that can be used to save your identifier.\nThe `external_id` can be used to retrieve, update or delete any object and can be a string of any format.\n\nIf the object is created in your environment, just pass this identifier as an argument when you create it using Bayou's API. Objects created within Bayou's environment can be updated using the Bayou identifier to attach your `external_id` to them.\n\nThe use of external IDs is totally optional.\n" }, "servers": [ { "url": "https://bayou.energy/api/v2", "description": "Bayou's v2 APIs" } ], "paths": { "/bills": { "post": { "summary": "Upload New Bill", "description": "Uploads a new bill to parse it", "tags": [ "Bills" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": 12345, "description": "Can be either Bayou's numeric ID for the bill's customer or your own [identifier](https://docs.bayou.energy/reference/external-ids) preceded with `external_id:`. This field is optional." }, "file": { "type": "string", "format": "binary", "description": "The PDF file of the bill to parse" } }, "required": [ "file" ] }, "encoding": { "file": { "contentType": "application/pdf" } } } } }, "responses": { "200": { "description": "Successfully uploaded the bill", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345, "description": "The ID of this bill" }, "external_id": { "type": "string", "example": "BILL_123", "description": "Your own [identifier](https://docs.bayou.energy/reference/external-ids) for this bill (this field must be unique)" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "$ref": "#/components/examples/no_file_provided" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "customer_id_invalid": { "$ref": "#/components/examples/customer_id_invalid" } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "$ref": "#/components/examples/external_id_not_unique" } } } }, "415": { "description": "Unsupported Media Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "$ref": "#/components/examples/unsupported_file_format" } } } } } } } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "properties": { "error_type": { "type": "string", "description": "The type of error" }, "error_code": { "type": "string", "description": "The error code" }, "error_message": { "type": "string", "description": "The error message" }, "docs_url": { "type": "string", "description": "A link to documentation providing more details about the error" } } } }, "examples": { "customer_id_invalid": { "value": { "error_type": "invalid_request", "error_code": "customer_id_invalid", "error_message": "The customer_id you provided in the request does not exist.", "docs_url": "https://docs.bayou.energy/docs/error-codes#customer_id_invalid" } }, "external_id_not_unique": { "value": { "error_type": "invalid_input", "error_code": "external_id_not_unique", "error_message": "The external_id you provided in the request isn't unique and belongs to .", "docs_url": "https://docs.bayou.energy/docs/error-codes#external_id_not_unique" } }, "no_file_provided": { "value": { "error_type": "invalid_input", "error_code": "no_file_provided", "error_message": "No file was provided in your request to post a bill.", "docs_url": "https://docs.bayou.energy/docs/error-codes#no_file_provided" } }, "unsupported_file_format": { "value": { "error_type": "invalid_input", "error_code": "unsupported_file_format", "error_message": "The file you provided is not in a format we support. PDF’s are the only format supported right now.", "docs_url": "https://docs.bayou.energy/docs/error-codes#unsupported_file_format" } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } }, "security": [ { "basicAuth": [] } ], "tags": [ { "name": "Bills", "description": "The following section defines requests that allow you to manage the utility bills of your customer accounts." } ] } ```