OptiMiser API Documentation

All API methods can be reached by sending a request to https://app.optimiserenergy.com/api/v0/<method>. Unless otherwise noted, all methods accept parameters either in the form of URL query parameters or as JSON objects.

All API methods return JSON-encoded responses. All responses include the properties "ERROR" and "ERRORCODE", which provide details about any error that occurred; these are present but empty for non-error responses.

All API methods other than get_session_token require a session token to be included in the request. This must be included in the form of an Authorization header like "Authorization: Session-Token 1234|abcd..."

[POST] get_session_token

The login method for the API - returns a session token that is used to authenticate later requests. See note above for how to include the returned token in an authentication header.

Example request

Example response

[GET] user_list

Retrieve a list of users. Remember, you must include an Authorization header in all calls expect for the get_session_token call itself.

[GET] company_list

[GET] project_list

Retrieve data about all projects that the user has permission to access.

NOTE: The canonical data for a single project are stored in a json-formatted file name [project_id].zs (e.g., 2346.zs). These files are not listed in the project_list results, but exist for every project and can be retrieved by the project_file call. For example, you could retrieve one for project with ID 4426 by making a GET request to {base_url}/project_file?project_id=4426&file_name=4426.zs

The project_list endpoint supports optional sorting and filtering so API clients can retrieve a focused, ordered project set without post-processing the full list.

Sort (sort_order, default ModifiedAt DESC):

• Fields: ModifiedAt, CreatedAt, ScheduleDate, id
• Directions: ASC or DESC
• Examples: "ModifiedAt DESC", "CreatedAt ASC", "id:ASC"

Filters (all optional):

• Company or company_id — company ID
• ProgramId or program_id — program ID
• ProjectState — state abbreviation (e.g. AZ)
• stage_id — workflow stage ID
• CreatedAtBegin / CreatedAtEnd — created date range (date-only uses start/end of day)
• ModifiedAtBegin / ModifiedAtEnd — modified date range

Example request

Example response

[POST] create_project

Create a new project

Parameters:

• project_name - The name to assign the project
  
• assign_to - email address of the user to whom to assign the project
  
• program_id - ID of the program for which to create the project
  
• company_id - ID of the company for which to create the project
  
• template_id (optional) - If this project should be based on a template project, then this is the ID of the template project
  
• stage_id - ID of the initial stage to assign the project. Legal values are
• 1 - Lead
• 2 - Audit
• 3 - Bid Proposed
• 4 - Bid Approved
• 5 - Retrofit in Progress
• 6 - Retrofit Complete
• 7 - QA
• project_schedule_date - Date on which the project is scheduled
• project_schedule_time - Time at which the project is scheduled
• FirstName - First name of the customer
• LastName - Last name of the customer
• HomePhone - Home phone number of the customer
• City - Address of the home: City
• State - Address of the home: State (two-character abbreviation)
• Zip - Address of the home: ZIP code (five digits)
• AptNumber (optional) - Address of the home: Apartment number 
• HouseNumber - Address of the home: House number
• Street - Address of the home: Street
• project_values[whatever_key]=whatever_value

User Roles and Project Creation

API user permissions follow the same role system that regular users follow. A table of roles and permissions can be found here.

Note that for programs with trade ally management (i.e., separate contractor companies participating in a program) a user with the "Program Manager role can be used to create projects for all participating companies in the program. 

Example request

Example response

[GET] project_file

Download a file associated with some project. URLs pointing to this method are included in the response from project_list.

NOTE: The canonical data for a single project are stored in a json-formatted file name [project_id].zs (e.g., 2346.zs). These files are not listed in the project_list results, but exist for every project and can be retrieved by the project_file call. For example, you could retrieve one for project with ID 4426 by making a GET request to {base_url}/project_file?project_id=4426&file_name=4426.zs

Parameters:

project_id - ID of the project whose file should be downloaded

file_name - Name of the file to be downloaded

Example request

Example response

The response returned by the method is the requested file.

• Extract a specific section from an HTML report
• Pull selected nodes from an XML file
• Return matched content as plain text, HTML/XML markup, or both

• For HTML files, you can use either CSS selectors or XPath.

• For XML files, only XPath is supported.
• Multiple matching elements may be returned.
• Each matched element includes its zero-based index in the result set.

[GET|POST] project_metadata

Retrieve or update a project's metadata. The requesting user must have permission to view the project.

Parameters:

project_id - ID of the project whose file should be downloaded

Request/Response Object:

A GET request will return this object for the requested project, and a POST should include such an object as its request body, where any values that are

present will be used to update the project.

Values marked below as "Read-only" cannot be modified with this method, and should not be included in POST requests.

Example Request

Example Response

• How do I accurately identify if a measure is included?
  
  Do not rely on the anymeasures flag. Instead, check the ImpPhase[MeasureName] control for the specific section. If the value is greater than 0, the measure is included (e.g., ImpPhaseVentilation > 0 indicates ventilation is included).

• Why are some values different between the UI and the data file?
  
  Data points like insulation may differ based on the building state. For example, insulation on crawl spaces will differ depending on whether the space is defined as "Conditioned" (insulation on wall/rim joist) or "Unconditioned" (insulation on the floor above).

• Why are some base sections (like idattic1) missing or renamed?
  
  This occurs if a second instance of a card was created and the original was deleted. When a card is duplicated and the original is removed, the subsequent instances receive unique object IDs. Use the banner_ attribute (e.g., "Attic 1") to identify the card rather than relying on the object ID.

• How should I locate specific objects like HVAC 2 or Attic 2?
  
  Always use the banner_ attribute to identify specific instances of repeated sections (e.g., look for "banner_": "HVAC 2").

• Why are my utility bill dates and numbers not aligning after import?
  
  Ensure all dates are provided in ascending order. Only the first period requires a full start date; end dates function as the start of the next period. Additionally, ensure date values are padded (e.g., "2026-05-14" instead of "2026-5-14").

• How do I clear out old data in a project?
  
  If you have set invalid data and need to reset it to null, try sending a blank string in your API call.

• Why aren't my changes reflecting on the UI after a push?
  
  Currently, you must reload the project after a successful push to see the changes. We are working on a system to automate this via the autosync system (websockets), but for now, a manual reload is required.

• Are there issues with specific API payload styles?
  
  If you encounter issues during modify_project calls, try omitting the use_zeus_names parameter.

• What causes "No such variable" errors?
  
  These errors often occur when sending numbered controls (e.g., ChkWindows1) when the system only recognizes the master variable without the number (e.g., ChkWindows). Avoid sending the numbered variants unless specifically required.