API docs by Redocly

Fram API (1.0.0)

Download OpenAPI specification:

All endpoints are available at https://api.framenergy.com/api/v1. For example, to list organizations, use GET https://api.framenergy.com/api/v1/organizations.

Authentication

To access the API, obtain an access token using:

curl --request POST \
  --url https://auth.framenergy.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":"<your_client_id>",
    "client_secret":"<your_client_secret>",
    "audience":"https://api.framenergy.com", 
    "grant_type":"client_credentials"
  }'

You can retrieve your client_id and client_secret from Fram.

The response will be:

{"access_token":"<access_token>","expires_in":86400,"token_type":"Bearer"}

Pass the token in the Authorization header for all requests:

Authorization: Bearer <access_token>

Rate Limiting

The Fram API has no rate limiting. You may call it as frequently as your integration requires without throttling.

List organizations

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number (1-indexed).

limit
integer
Default: 300

Maximum number of results to return. Max 300 for non-admin callers.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get organization by ID

Authorizations:
bearerAuth
path Parameters
organization_id
required
string <uuid>

UUID of the organization.

Responses

Response samples

Content type
application/json
{
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List projects

Non-admin callers must supply organization_id — omitting it returns a 403.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number (1-indexed).

limit
integer
Default: 300

Maximum number of results to return. Max 300 for non-admin callers.

organization_id
string <uuid>

Filter by organization UUID. Required for non-admin callers.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get project by ID

Authorizations:
bearerAuth
path Parameters
project_id
required
string <uuid>

UUID of the project.

Responses

Response samples

Content type
application/json
{
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  • "name": "string",
  • "address": "string",
  • "city": "string",
  • "state": "string",
  • "zip_code": "string",
  • "utility": "string",
  • "vendor_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List users

Returns tenants (residents). Non-admin callers must supply project_id — omitting it returns a 403. Each user includes a leases array of their unit assignments.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number (1-indexed).

limit
integer
Default: 300

Maximum number of results to return. Max 300 for non-admin callers.

project_id
string <uuid>

Filter by project UUID. Required for non-admin callers.

organization_id
string <uuid>

Filter by organization UUID.

search
string

Free-text search across user fields.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get user by ID

Authorizations:
bearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the user.

Responses

Response samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "first_name": "string",
  • "last_name": "string",
  • "email_address": "user@example.com",
  • "phone_number": "string",
  • "role": "string",
  • "language_preference": "string",
  • "leases": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List units

Non-admin callers must supply project_id — omitting it returns a 403.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number (1-indexed).

limit
integer
Default: 300

Maximum number of results to return. Max 300 for non-admin callers.

project_id
string <uuid>

Filter by project UUID. Required for non-admin callers.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get unit by ID

Authorizations:
bearerAuth
path Parameters
unit_id
required
string <uuid>

UUID of the unit.

Responses

Response samples

Content type
application/json
{
  • "unit_id": "5becc822-b69e-4e66-a762-ad8e868dcab6",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "unit_number": "string",
  • "bedrooms": 0,
  • "sqft": 0,
  • "vendor_id": "string",
  • "pto_date": "2019-08-24",
  • "meter_number": "string",
  • "address_line1": "string",
  • "address_line2": "string",
  • "current_tenant_user_id": "721c2477-84bd-4c5f-92be-517b69fe56d2",
  • "current_tenant_name": "string",
  • "current_tenant_email": "string",
  • "current_tenant_move_in_date": "2019-08-24",
  • "current_tenant_move_out_date": "2019-08-24",
  • "current_tenant_utility_authorized": true,
  • "current_tenant_utility_authorized_date": "2019-08-24",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List invoices

Non-admin callers must supply at least one of organization_id or project_id — omitting both returns a 403.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number (1-indexed).

limit
integer
Default: 300

Maximum number of results to return. Max 300 for non-admin callers.

organization_id
string <uuid>

Filter by organization UUID. Non-admin callers must supply organization_id or project_id (or both).

project_id
string <uuid>

Filter by project UUID. Non-admin callers must supply project_id or organization_id (or both).

user_id
string <uuid>

Filter by user (tenant) UUID.

unit_id
string <uuid>

Filter by unit UUID.

status
string

Filter by invoice status (e.g. draft, sent, paid).

start_date
string <date>

Include only invoices with an invoice_date on or after this date (YYYY-MM-DD).

end_date
string <date>

Include only invoices with an invoice_date on or before this date (YYYY-MM-DD).

sort_by
string

Field to sort by.

sort_order
string

Sort direction: asc or desc.

search
string

Free-text search across invoice fields.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

List transactions

Non-admin callers must supply at least one of organization_id or project_id — omitting both returns a 403.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number (1-indexed).

limit
integer
Default: 300

Maximum number of results to return. Max 300 for non-admin callers.

user_id
string <uuid>

Filter by user (tenant) UUID.

organization_id
string <uuid>

Filter by organization UUID. Non-admin callers must supply organization_id or project_id (or both).

project_id
string <uuid>

Filter by project UUID. Non-admin callers must supply project_id or organization_id (or both).

exclude_fully_applied
boolean
Default: false

When true, exclude transactions that have been fully applied to invoices.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

List open balances

Returns open balances for a project with an as_of_date strictly after the supplied date. Admin callers can query any project; non-admin callers must belong to the project's organization.

Authorizations:
bearerAuth
query Parameters
project_id
required
string <uuid>

Project UUID to return open balances for.

after_date
required
string <date>

Return balances with an as_of_date strictly after this date.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create open balance

Creates an open balance for the active tenant/unit assignment on as_of_date. Admin only. Provide exactly one of unit_id or user_id; amount may be used as an alias for balance.

Authorizations:
bearerAuth
Request Body schema: application/json
required
One of
unit_id
required
string or null <uuid>

Unit UUID to resolve the tenant/unit assignment. Mutually exclusive with user_id.

user_id
string or null <uuid>

User UUID to resolve the tenant/unit assignment. Mutually exclusive with unit_id.

balance
number decimal places <= 2

Open balance amount in dollars.

amount
number decimal places <= 2
Deprecated

Alias for balance.

as_of_date
required
string <date>

Date the open balance is effective as of.

Responses

Request samples

Content type
application/json
Example
{
  • "unit_id": "5becc822-b69e-4e66-a762-ad8e868dcab6",
  • "balance": "125.50",
  • "as_of_date": "2026-02-01"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete open balance

Deletes an open balance by ID. Admin only.

Authorizations:
bearerAuth
path Parameters
open_balance_id
required
string <uuid>

Open balance UUID.

Responses

List transaction applications

Non-admin callers must supply at least one of invoice_id, transaction_id, or invoice_ids — omitting all three returns a 403.

Authorizations:
bearerAuth
query Parameters
invoice_id
string <uuid>

Filter by invoice UUID. Non-admin callers must supply at least one of invoice_id, transaction_id, or invoice_ids.

transaction_id
string <uuid>

Filter by transaction UUID. Non-admin callers must supply at least one of invoice_id, transaction_id, or invoice_ids.

invoice_ids
Array of strings <uuid> [ items <uuid > ]

Filter by multiple invoice UUIDs. Non-admin callers must supply at least one of invoice_id, transaction_id, or invoice_ids.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List billing payloads

Returns billing payloads — the calculated energy and billing data for each unit per billing period. Each payload contains metered energy maps (import, export, usage), billing amounts, and the associated invoice once one has been generated. Non-admin callers must supply project_id — omitting it returns a 403.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number (1-indexed).

limit
integer
Default: 300

Maximum number of results to return. Max 300 for non-admin callers.

user_id
string <uuid>

Filter by user (tenant) UUID.

users_only
boolean
Default: false

When true, return only payloads that have an associated user (exclude project-level payloads).

start_date
string <date>

Filter by billing period start date (YYYY-MM-DD).

project_id
string <uuid>

Filter by project UUID. Required for non-admin callers.

unit_id
string <uuid>

Filter by unit UUID.

sort
string

Sort expression (e.g. start_date:desc).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

List aggregated utility rates

Returns pre-aggregated utility rate schedules. All parameters are optional and this endpoint has no caller-role restrictions.

Authorizations:
bearerAuth
query Parameters
page
integer
Default: 1

Page number (1-indexed).

limit
integer
Default: 10

Maximum number of results to return.

billing_code
string

Filter by tariff billing code.

generation_supplier
string

Filter by generation supplier (e.g. MCE, SVCE).

bypass_limit
boolean
Default: false

When true, return all matching records ignoring the limit parameter.

target_date
string <date>

Return only rates effective on this date (YYYY-MM-DD).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get aggregated utility rate by ID

Authorizations:
bearerAuth
path Parameters
aggregated_utility_rate_id
required
string <uuid>

UUID of the aggregated utility rate.

Responses

Response samples

Content type
application/json
{
  • "aggregated_utility_rate_id": "72a1d190-c3ac-405c-98c5-ebaab356583c",
  • "utility": "string",
  • "billing_code": "string",
  • "generation_supplier": "string",
  • "effective_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "total_rate_map": { },
  • "references": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}