--- updatedAt: 2026-05-27T19:28:36.000Z agentTools: projectIndex: https://docs.bayou.energy/llms.txt --- # Get Customer by ID Retrieves a customer account # 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": { "/customers/{id}": { "get": { "summary": "Get Customer by ID", "description": "Retrieves a customer account", "tags": [ "Customers" ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "example": 12345, "required": true, "description": "Can be either Bayou's numeric ID or your own [identifier](https://docs.bayou.energy/reference/external-ids) for this customer preceded with `external_id:`" } ], "responses": { "200": { "description": "Returns the customer account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExistingCustomer" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "customer_id_invalid": { "$ref": "#/components/examples/customer_id_invalid" } } } } } } } } }, "components": { "schemas": { "Customer": { "type": "object", "properties": { "external_id": { "type": "string", "example": "MSCOTT123", "description": "Your own [identifier](https://docs.bayou.energy/reference/external-ids) for this customer (this field must be unique)" }, "email": { "type": "string", "example": "michael.scott@dunder-mifflin.com", "description": "This customer's email address" }, "first_name": { "type": "string", "example": "Michael", "description": "This customer's first name" }, "last_name": { "type": "string", "example": "Scott", "description": "This customer's last name" }, "phone_number": { "type": "string", "example": "212-465-6741", "description": "This customer's phone number" }, "address_line_1": { "type": "string", "example": "4 Pennsylvania Plaza", "description": "This customer's address (first line)" }, "address_line_2": { "type": "string", "example": null, "description": "This customer's address (second line)" }, "city": { "type": "string", "example": "New York", "description": "This customer's city" }, "state": { "type": "string", "nullable": true, "example": "NY", "description": "This customer's state", "enum": [ null, "AL", "AK", "AS", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FM", "FL", "GA", "GU", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MH", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "MP", "OH", "OK", "OR", "PW", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VI", "VA", "WA", "WV", "WI", "WY" ] }, "zipcode": { "type": "string", "example": 10001, "description": "This customer's zipcode" }, "utility": { "type": "string", "example": "con_edison", "description": "This customer's utility. See [Utility support](https://docs.bayou.energy/reference/utility-support) for more information" } } }, "ExistingCustomer": { "allOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "object", "properties": { "id": { "type": "integer", "example": 12345, "description": "The ID of this customer" }, "onboarding_link": { "type": "string", "example": "https://bayou.energy/companies/12345/sign_up?key=ABCDEF0123456", "description": "The URL at which customers can update their billing and utility account data" }, "onboarding_token": { "type": "string", "example": "ABCDEF0123456_ABCDEF0123456_ABCDEF0123456", "description": "The token to use when embedding the onboarding component in your website, using the Bayou JS library" }, "tags": { "type": "array", "items": { "type": "string", "description": "The tags for this customer" }, "example": [] }, "has_accepted_terms_on": { "type": "string", "format": "date-time", "example": "2022-07-01T14:05:00Z", "description": "The date and time at which this customer accepted Bayou's terms and conditions" }, "has_filled_credentials": { "type": "boolean", "example": true, "description": "Whether or not the customer has filled credentials using their onboarding link" }, "is_currently_authenticated": { "type": "boolean", "example": true, "description": "Whether the customer's utility account credentials are currently valid and usable for authentication. If the customer has MFA, this also indicates whether the MFA factor has expired." }, "auth_status": { "type": "string", "nullable": true, "enum": [ "authenticated", "onboarding_credentials_needed", "onboarding_mfa_needed", "onboarding_reauth_needed", "onboarding_customer_action_required", "onboarding_auth_issue", "refresh_mfa_needed", "refresh_reauth_needed", "refresh_customer_action_required", "refresh_auth_issue" ], "example": "authenticated", "description": "The customer's authentication verdict, the same one shown on the Bayou dashboard. `authenticated` means Bayou can sign in to the customer's utility account. Every other value names a problem and the lifecycle stage it occurred in — `onboarding_*` for customers who never finished connecting, `refresh_*` for customers who were working and then broke. `*_credentials_needed` means no credentials are on file yet; `*_mfa_needed` means the customer must complete multi-factor authentication; `*_reauth_needed` means the stored credentials were rejected and the customer must re-authenticate; `*_customer_action_required` means the utility is waiting on the customer to act on its own website (for example, finishing their online account setup) before Bayou can connect; `*_auth_issue` means Bayou hit an unexpected problem — Bayou is notified and no action is needed from you. `null` means nothing has run yet for this customer." }, "bills_are_ready": { "type": "boolean", "example": true, "description": "Whether or not the initial fetching of bills for this customer has completed" }, "utility_has_intervals": { "type": "boolean", "example": true, "description": "Whether or not this customer's utility supports interval data" }, "account_has_intervals": { "type": "boolean", "example": true, "description": "Whether or not this customer's has existing interval data" }, "intervals_are_ready": { "type": "boolean", "example": true, "description": "Whether or not the initial fetching of intervals for this customer has completed" }, "first_interval_discovered": { "type": "string", "format": "date-time", "example": "2021-11-01T00:00:00Z", "description": "The start time of the first interval discovered for this customer" }, "last_interval_discovered": { "type": "string", "format": "date-time", "example": "2022-11-01T00:00:00Z", "description": "The start time of the last interval discovered for this customer" }, "account_numbers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": 123456, "description": "The utility identifier for this account number" }, "meters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "XYZ12345", "description": "The ID of this meter" }, "type": { "type": "string", "enum": [ "gas", "electric" ], "description": "The type of this meter", "example": "gas" }, "tariffs": { "type": "array", "items": { "type": "object", "properties": { "tariff": { "type": "string", "example": "123 Residential", "description": "The name of this tariff" }, "period_from": { "type": "string", "format": "date", "example": "2022-07-01", "description": "The start of the period this tariff was used for this meter" }, "period_to": { "type": "string", "format": "date", "example": "2022-07-31", "description": "The end of the period this tariff was used for this meter" } } } }, "tags": { "type": "array", "items": { "type": "string", "description": "The tags for this meter" }, "example": [] }, "address": { "type": "object", "properties": { "line_1": { "type": "string", "example": "123 Main St", "description": "The full street address for this meter" }, "line_2": { "type": "string", "example": "Apt 1", "description": "The second line of the street address for this meter" }, "city": { "type": "string", "example": "New York", "description": "The city for this meter" }, "state": { "type": "string", "example": "NY", "description": "The state for this meter" }, "postal_code": { "type": "string", "example": 10001, "description": "The zip code for this meter" }, "postal_code_suffix": { "type": "string", "example": 1234, "description": "The zip code suffix for this meter" }, "country": { "type": "string", "example": "US", "description": "The country for this meter" } } }, "additional_attributes": { "type": "object", "description": "Additional attributes for this meter", "properties": { "gas_choice_id": { "type": "string", "example": 123456789, "description": "The gas choice id for a meter, if provided" } } } }, "example": [ { "id": "XYZ12345", "status": "unlocked", "type": "gas", "billing_period_from": "2022-07-01", "billing_period_to": "2022-07-31", "consumption": 90, "address": { "line_1": "123 Main St", "line_2": "Apt 1", "city": "New York", "state": "NY", "postal_code": 10001, "postal_code_suffix": 1234, "country": "US" }, "tariff": "123 Residential", "additional_attributes": { "gas_choice_id": 123456789 } }, { "id": "XYZ98765", "status": "unlocked", "type": "electric", "billing_period_from": "2022-07-01", "billing_period_to": "2022-07-31", "consumption": 900, "address": { "line_1": "123 Main St", "line_2": "Apt 1", "city": "New York", "state": "NY", "postal_code": 10001, "postal_code_suffix": 1234, "country": "US" }, "tariff": "456 Residential", "additional_attributes": { "electric_choice_id": 987654321 } } ] } }, "tags": { "type": "array", "items": { "type": "string", "description": "The tags for this account number" }, "example": [] } } } } } } ] }, "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" } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } }, "security": [ { "basicAuth": [] } ], "tags": [ { "name": "Customers", "description": "The following section defines requests that allow you to manage your customer accounts." } ] } ```