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 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"
}