TRANXACT.AI Help

CRM · Utility Field Service

Utility Settings

The company's own numbers: grace and notice days, the late fee, the reconnect fee, deposits, read checks, the ledger accounts, and whether the public forms are open. One row; the shipped defaults apply until it is saved.

Type REST8 operationsBase path /api/crm/util-settingsPublished as /api/v1/util-settings

Download specification (OpenAPI 3.1) Screen: Utility Settings

Overview

PackageCRM
AuthenticationBearer token: a service account's token (POST /api/auth/service-token) or, for the published path, an API key
AuthorizationThe caller's roles must hold CRM › Utility Settings on the Roles screen: display for GET, add for POST, change for PUT, delete for DELETE; an action needs the grant of the button that runs it on the screen.
Tablecrm.util_settings · kept per company (and organisational unit where it has one)
RecordCreated, changed and (where the screen allows) deleted; key id
RulesThe same as the screen: validation, numbering, approvals, posting, the company the caller belongs to, and the audit trail.

API reference

8 operations. Open one for its parameters, bodies, responses and a sample request.

GET/api/crm/util-settingsList utility settings

Query parameters

NameDescriptionExample
limitRows per page (50 by default, at most 200)limit=100
offsetRows to skipoffset=200
qFree-text search over the search columnsq=acme
sortcolumn:asc or column:desc, several separated by commassort=created_at:desc
filterA JSON condition or group (see the filter language), URL-encoded; any field below can be filtered and sortedfilter={"col":"status","op":"eq","value":"open"}
<field>=<value>Shorthand for "field is value" 

Response 200

{
  "rows": [
    {
      "id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
      "org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
      "grace_days": 10,
      "notice_days": 10,
      "final_notice_days": 10,
      "disconnect_days": 10,
      "late_fee_flat": "1250.00",
      "late_fee_pct": "1250.00",
      "late_fee_min_balance": "1250.00",
      "reconnect_fee": "1250.00",
      "deposit_residential": "1250.00",
      "deposit_commercial": "1250.00",
      "high_usage_pct": 10,
      "low_usage_pct": 10
    }
  ],
  "count": 1
}

Sample request

curl "https://demo.tranxact.ai/api/crm/util-settings?limit=20" \
  -H "Authorization: Bearer $TOKEN"
GET/api/crm/util-settings/{id}Read one utility settings

Path parameters

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Response 200

{
  "id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "grace_days": 10,
  "notice_days": 10,
  "final_notice_days": 10,
  "disconnect_days": 10,
  "late_fee_flat": "1250.00",
  "late_fee_pct": "1250.00",
  "late_fee_min_balance": "1250.00",
  "reconnect_fee": "1250.00",
  "deposit_residential": "1250.00",
  "deposit_commercial": "1250.00",
  "high_usage_pct": 10,
  "low_usage_pct": 10
}

404 when no record with that id is visible to the caller.

Sample request

curl "https://demo.tranxact.ai/api/crm/util-settings/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
  -H "Authorization: Bearer $TOKEN"
POST/api/crm/util-settingsCreate a utility settings

Request body

The record as JSON. Fields marked Yes are required.

FieldTypeRequiredDescription
grace_daysintegerNoGrace days before a late fee
notice_daysintegerNoPast-due notice after (days)
final_notice_daysintegerNoFinal notice after (days)
disconnect_daysintegerNoPropose disconnection after (days)
late_fee_flatnumericNoLate fee (flat)
late_fee_pctnumericNoLate fee (% of past due) — The greater of the two is charged.
late_fee_min_balancenumericNoNo late fee below
reconnect_feenumericNoReconnect fee
deposit_residentialnumericNoDeposit, residential
deposit_commercialnumericNoDeposit, commercial
high_usage_pctintegerNoHigh-use exception above (% of average)
low_usage_pctintegerNoLow-use exception below (% of average)
bill_due_daysintegerNoBills due in (days)
revenue_account_notextNoUtility revenue account
deposit_account_notextNoCustomer deposits account
credit_account_notextNoCustomer credit balances account
bad_debt_account_notextNoBad debt account
public_forms_enabledbooleanNoTake start-service and problem reports from the public
portal_link_factortextNoPortal sign-up proves the bill by
Allowed: either last_bill_amount postal_code
receivable_account_notextNoUtility receivable account — e.g. 1170 Utility Billings Receivable. Blank: the company's accounts receivable.
cash_account_notextNoUtility cash / lockbox account — Where payments, deposits and refunds go, e.g. 1040. Blank: the company's cash account.
service_charge_account_notextNoService (customer) charge account — e.g. 4410. Blank: the customer charge posts with the usage, to the revenue account.
late_fee_account_notextNoLate fee account — Blank: the utility revenue account.
reconnect_fee_account_notextNoConnection and reconnection fee account — e.g. 4450. Blank: the utility revenue account.
leak_adjustment_account_notextNoLeak adjustment account — Blank: the leak credit reduces the revenue account the use was billed to.
cost_center_iduuidNoUtility cost center — What payments, deposits and fees post under, and any plan with none of its own -- so a fund-accounting company derives the fund.
leak_max_per_yearintegerNoLeak adjustments per account in 12 months — 0: none are made.
leak_methodtextNoLeak credit method — excess_lowest_tier: use above normal at the lowest block rate. excess_waived: use above normal not billed.
Allowed: excess_lowest_tier excess_waived
leak_requires_approvalbooleanNoA second person approves each leak adjustment
leak_history_billsintegerNoNormal use: average of the last (bills)

Sample body

{
  "grace_days": 10,
  "notice_days": 10,
  "final_notice_days": 10,
  "disconnect_days": 10
}

Response 201

{
  "id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "grace_days": 10,
  "notice_days": 10,
  "final_notice_days": 10,
  "disconnect_days": 10,
  "late_fee_flat": "1250.00",
  "late_fee_pct": "1250.00",
  "late_fee_min_balance": "1250.00",
  "reconnect_fee": "1250.00",
  "deposit_residential": "1250.00",
  "deposit_commercial": "1250.00",
  "high_usage_pct": 10,
  "low_usage_pct": 10
}

Sample request

curl -X POST "https://demo.tranxact.ai/api/crm/util-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grace_days":10,"notice_days":10,"final_notice_days":10,"disconnect_days":10}'
PUT/api/crm/util-settings/{id}Change a utility settings

Path parameters

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Request body

Only the fields to change; fields left out keep their value.

FieldTypeRequiredDescription
grace_daysintegerNoGrace days before a late fee
notice_daysintegerNoPast-due notice after (days)
final_notice_daysintegerNoFinal notice after (days)
disconnect_daysintegerNoPropose disconnection after (days)
late_fee_flatnumericNoLate fee (flat)
late_fee_pctnumericNoLate fee (% of past due) — The greater of the two is charged.
late_fee_min_balancenumericNoNo late fee below
reconnect_feenumericNoReconnect fee
deposit_residentialnumericNoDeposit, residential
deposit_commercialnumericNoDeposit, commercial
high_usage_pctintegerNoHigh-use exception above (% of average)
low_usage_pctintegerNoLow-use exception below (% of average)
bill_due_daysintegerNoBills due in (days)
revenue_account_notextNoUtility revenue account
deposit_account_notextNoCustomer deposits account
credit_account_notextNoCustomer credit balances account
bad_debt_account_notextNoBad debt account
public_forms_enabledbooleanNoTake start-service and problem reports from the public
portal_link_factortextNoPortal sign-up proves the bill by
Allowed: either last_bill_amount postal_code
receivable_account_notextNoUtility receivable account — e.g. 1170 Utility Billings Receivable. Blank: the company's accounts receivable.
cash_account_notextNoUtility cash / lockbox account — Where payments, deposits and refunds go, e.g. 1040. Blank: the company's cash account.
service_charge_account_notextNoService (customer) charge account — e.g. 4410. Blank: the customer charge posts with the usage, to the revenue account.
late_fee_account_notextNoLate fee account — Blank: the utility revenue account.
reconnect_fee_account_notextNoConnection and reconnection fee account — e.g. 4450. Blank: the utility revenue account.
leak_adjustment_account_notextNoLeak adjustment account — Blank: the leak credit reduces the revenue account the use was billed to.
cost_center_iduuidNoUtility cost center — What payments, deposits and fees post under, and any plan with none of its own -- so a fund-accounting company derives the fund.
leak_max_per_yearintegerNoLeak adjustments per account in 12 months — 0: none are made.
leak_methodtextNoLeak credit method — excess_lowest_tier: use above normal at the lowest block rate. excess_waived: use above normal not billed.
Allowed: excess_lowest_tier excess_waived
leak_requires_approvalbooleanNoA second person approves each leak adjustment
leak_history_billsintegerNoNormal use: average of the last (bills)

Sample body

{
  "grace_days": 10,
  "notice_days": 10
}

Response 200

{
  "id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
  "grace_days": 10,
  "notice_days": 10,
  "final_notice_days": 10,
  "disconnect_days": 10,
  "late_fee_flat": "1250.00",
  "late_fee_pct": "1250.00",
  "late_fee_min_balance": "1250.00",
  "reconnect_fee": "1250.00",
  "deposit_residential": "1250.00",
  "deposit_commercial": "1250.00",
  "high_usage_pct": 10,
  "low_usage_pct": 10
}

Sample request

curl -X PUT "https://demo.tranxact.ai/api/crm/util-settings/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grace_days":10,"notice_days":10}'
DELETE/api/crm/util-settings/{id}Delete a utility settings

Path parameters

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Response 200

{ "deleted": true }

Many documents are cancelled or reversed instead; the API refuses a delete the screen would refuse.

Sample request

curl -X DELETE "https://demo.tranxact.ai/api/crm/util-settings/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
  -H "Authorization: Bearer $TOKEN"
GET/api/crm/util-settings/{id}/ledger-changesLedger changes

Path parameters

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Response

200 with the data as JSON.

Sample request

curl "https://demo.tranxact.ai/api/crm/util-settings/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/ledger-changes" \
  -H "Authorization: Bearer $TOKEN"
POST/api/crm/util-settings/{id}/ledger-changeLedger change

Path parameters

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Request body

The keys this action reads (* = required; "one of" lists the only values):

changeId, decision

Response

200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.

Sample request

curl -X POST "https://demo.tranxact.ai/api/crm/util-settings/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/ledger-change" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"changeId":"value","decision":"value"}'
POST/api/crm/util-settings/{id}/copyCopy

Path parameters

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Request body

The keys this action reads (* = required; "one of" lists the only values):

overrides, preview, withLines

Response

200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.

Sample request

curl -X POST "https://demo.tranxact.ai/api/crm/util-settings/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"overrides":"value","preview":"value","withLines":"value"}'

Data model

Every field of a utility settings, as the API returns it. Field names are the JSON keys; any of them can be filtered and sorted on a list.

FieldTypeAccessDescription
iduuidread onlyId
org_iduuidread onlyOrg id
org_unit_iduuidread onlyOrg unit id
grace_daysintegerread, writeGrace days before a late fee
notice_daysintegerread, writePast-due notice after (days)
final_notice_daysintegerread, writeFinal notice after (days)
disconnect_daysintegerread, writePropose disconnection after (days)
late_fee_flatnumericread, writeLate fee (flat)
late_fee_pctnumericread, writeLate fee (% of past due) — The greater of the two is charged.
late_fee_min_balancenumericread, writeNo late fee below
reconnect_feenumericread, writeReconnect fee
deposit_residentialnumericread, writeDeposit, residential
deposit_commercialnumericread, writeDeposit, commercial
high_usage_pctintegerread, writeHigh-use exception above (% of average)
low_usage_pctintegerread, writeLow-use exception below (% of average)
bill_due_daysintegerread, writeBills due in (days)
revenue_account_notextread, writeUtility revenue account
deposit_account_notextread, writeCustomer deposits account
credit_account_notextread, writeCustomer credit balances account
bad_debt_account_notextread, writeBad debt account
public_forms_enabledbooleanread, writeTake start-service and problem reports from the public
portal_link_factortextread, writePortal sign-up proves the bill by
Allowed: either last_bill_amount postal_code
created_attimestamp with time zoneread onlyCreated at
created_byuuidread onlyCreated by
updated_attimestamp with time zoneread onlyUpdated at
updated_byuuidread onlyUpdated by
receivable_account_notextread, writeUtility receivable account — e.g. 1170 Utility Billings Receivable. Blank: the company's accounts receivable.
cash_account_notextread, writeUtility cash / lockbox account — Where payments, deposits and refunds go, e.g. 1040. Blank: the company's cash account.
service_charge_account_notextread, writeService (customer) charge account — e.g. 4410. Blank: the customer charge posts with the usage, to the revenue account.
late_fee_account_notextread, writeLate fee account — Blank: the utility revenue account.
reconnect_fee_account_notextread, writeConnection and reconnection fee account — e.g. 4450. Blank: the utility revenue account.
leak_adjustment_account_notextread, writeLeak adjustment account — Blank: the leak credit reduces the revenue account the use was billed to.
cost_center_iduuidread, writeUtility cost center — What payments, deposits and fees post under, and any plan with none of its own -- so a fund-accounting company derives the fund.
leak_max_per_yearintegerread, writeLeak adjustments per account in 12 months — 0: none are made.
leak_methodtextread, writeLeak credit method — excess_lowest_tier: use above normal at the lowest block rate. excess_waived: use above normal not billed.
Allowed: excess_lowest_tier excess_waived
leak_requires_approvalbooleanread, writeA second person approves each leak adjustment
leak_history_billsintegerread, writeNormal use: average of the last (bills)
xf_text_1textread onlyXf text 1
xf_text_2textread onlyXf text 2
xf_text_3textread onlyXf text 3
xf_text_4textread onlyXf text 4
xf_text_5textread onlyXf text 5
xf_num_1numericread onlyXf num 1
xf_num_2numericread onlyXf num 2
xf_num_3numericread onlyXf num 3
xf_date_1dateread onlyXf date 1
xf_date_2dateread onlyXf date 2

Errors

StatusMeaning
400The request could not be read: a filter that is not JSON, a bad parameter
401No credential, or it is wrong, revoked or expired
403The caller's roles do not hold CRM › Utility Settings for this verb, or the address or origin is not allowed
404No record with that id is visible to the caller
409A conflict: a duplicate number, a document in a state that does not allow it, or a record changed or locked by someone else
422Refused by the same validation as the screen; the error names the field and why

Every error is JSON: {"error": "a sentence saying what was wrong"}, with field where it applies.