Authorizations

This document provides detailed information about the /authorizations endpoints, including request bodies, response formats, and data types. These endpoints manage authorizations, which represent user-submitted credentials (website, username, password) for accessing utility accounts. After creating an authorization, users can retrieve its status. When the status becomes “Inventory Complete,” associated utility_accounts are available, and users can activate specific accounts by setting their status to “Active” and specifying a data_start_date to indicate how far back to retrieve data.

Endpoints Overview

• POST /authorizations: Create a new authorization with online access credentials.
• GET /authorizations: List all authorizations for the user’s company.
• GET /authorizations/formlink: Get a link to a sharable authorizations form. Each time this form is submitted, a new authorization is created and queued for inventory processing.
• GET /authorizations/:id: Retrieve a specific authorization by ID, including its accounts.
• PUT /authorizations/:id/update_account_status: Update the status or data start date of a utility account.

POST /authorizations

Creates a new authorization with the provided online access credentials.

Endpoint

POST /authorizations

Request Body

{
  "online_access_username": "string",
  "online_access_password": "string",
  "online_access_url": "string"
}

Example Response

{
  "message": "Credential transfer was successful.",
  "success": true
}

Data Types

• online_access_username: string - The username for online access.
• online_access_password: string - The password for online access.
• online_access_url: string - The URL for online access.

GET /authorizations

Retrieves a list of authorizations for the company associated with the JWT. Admin users retrieve all authorizations across companies.

Endpoint

GET /authorizations

Example Response

{
  "authorizations": [
    {
      "id": 1,
      "online_access_username": "user123",
      "online_access_password": "*********",
      "online_access_url": "https://utility.example.com",
      "status": "Pending",
      "errors": null,
      "company_id": 1,
      "created_at": "2023-10-01T12:00:00Z",
      "updated_at": "2023-10-01T12:00:00Z"
    }
  ],
  "companyUuid": "550e8400-e29b-41d4-a716-446655440000"
}

Data Types

• authorizations: array of objects - List of authorization records.
  • id: integer - Unique identifier for the authorization.
  • online_access_username: string - The username for online access.
  • online_access_password: string - The password (masked as “*****” for security).
  • online_access_url: string - The URL for online access.
  • status: string - Current status of the authorization (e.g., “Pending”, “Inventory Complete”).

  • errors: string

    null - Any error messages, or null if none.

  • company_id: integer - The ID of the company owning the authorization.
  • created_at: timestamp - When the authorization was created.
  • updated_at: timestamp - When the authorization was last updated.
• companyUuid: string - UUID of the company associated with the JWT.

GET /authorizations/formlink

Retrieves a unique link to an authorization form that can be shared with external users. The form allows users to submit their online access credentials (username, password, and URL) for utility accounts. This link can be shared with external users to allow them to submit their own authorization credentials securely. The link is specific to the company associated with the authenticated user’s JWT.

Endpoint

GET /authorizations/formlink

Request

• Method: GET
• Authentication: Requires JWT
• Parameters: None

Example Response

{
  "authorizationFormLink": "http://localhost:3000/credentials-transfer/04894071-5256-4e5d-9467-1144e6229589"
}

Data Types

• authorizationFormLink: string - The full URL to the authorization form.

GET /authorizations/:id

Retrieves a specific authorization by ID, including its associated utility accounts and utility company details. The password is masked unless the user is an admin.

Endpoint

GET /authorizations/:id

Example Response

{
  "id": 1,
  "online_access_username": "user123",
  "online_access_password": "*********",
  "online_access_url": "https://utility.example.com",
  "status": "Inventory Complete",
  "errors": null,
  "company_id": 1,
  "created_at": "2023-10-01T12:00:00Z",
  "updated_at": "2023-10-01T12:00:00Z",
  "accounts": [
    {
      "id": 1,
      "acct_num": "ACC12345",
      "status": "Active",
      "utility_company_id": 1,
      "delivery_method": "Invoiage Online",
      "created_at": "2023-10-01T12:05:00Z",
      "updated_at": "2023-10-01T12:05:00Z",
      "utility_company": {
        "id": 1,
        "name": "Example Utility Co"
      }
    }
  ]
}

Data Types

• id: integer - Unique identifier for the authorization.
• online_access_username: string - The username for online access.
• online_access_password: string - The password (masked unless admin).
• online_access_url: string - The URL for online access.
• status: string - Current status of the authorization.

• errors: string

  null - Any error messages, or null if none.

• company_id: integer - The ID of the company owning the authorization.
• created_at: timestamp - When the authorization was created.
• updated_at: timestamp - When the authorization was last updated.
• accounts: array of objects - List of utility accounts linked to the authorization.
  • id: integer - Unique identifier for the account.
  • acct_num: string - Account number.
  • status: string - Account status (“Active” or “Inactive”).
  • utility_company_id: integer - ID of the associated utility company.
  • delivery_method: string - Method of data delivery (e.g., “Invoiage Online”).
  • created_at: timestamp - When the account was created.
  • updated_at: timestamp - When the account was last updated.
  • utility_company: object - Details of the utility company.
    • id: integer - Unique identifier for the utility company.
    • name: string - Name of the utility company.

PUT /authorizations/:id/update_account_status

Updates the status and/or data start date of a utility account associated with the authorization.

Endpoint

PUT /authorizations/:id/update_account_status

Request Body

{
  "utility_account_id": 1,
  "status": "Active",
  "data_start_date": "YYYY-MM-DD"
}

Example Response

{
  "id": 1,
  "acct_num": "ACC12345",
  "status": "Active",
  "utility_company_id": 1,
  "delivery_method": "Invoiage Online",
  "data_start_date": "2023-01-01",
  "created_at": "2023-10-01T12:05:00Z",
  "updated_at": "2023-10-01T12:15:00Z"
}

Data Types

• utility_account_id: integer - ID of the utility account to update.
• status: string - New status (“Active” or “Inactive”).
• data_start_date: string (optional) - Date (YYYY-MM-DD) indicating how far back to retrieve data.

Notes

• Password Masking: The online_access_password is masked in responses.
• Flow: After creating an authorization via POST /authorizations, monitor its status using GET /authorizations/:id. When the status is “Inventory Complete,” review the accounts array and activate desired accounts using PUT /authorizations/:id/update_account_status by setting status to “Active” and optionally providing a data_start_date.