Integrations

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
namestring · required
categorystring · required

one of payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · required
configuration_referencestring · required

Opaque secret/configuration reference; never a secret value.

statusstring · required

one of active, suspended, disabled

healthstring · required

one of unknown, healthy, degraded, unavailable

last_health_check_atstring · optional · nullable
The object
{
  "id": "int_2s0jH8wLbKi9jSO5lWaRJWCPxso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "name": "Ana Matsinhe",
  "category": "payment",
  "provider_key": "provider key",
  "configuration_reference": "CON-2026-000142",
  "status": "active",
  "health": "unknown",
  "last_health_check_at": "2026-11-19T09:30:00Z"
}

List utility integrations

Logs

GET /integrations

List external integrations configured for this utility tenant

Returns the integrations registered for the tenant, newest first, with category, provider key, secret configuration reference (never the secret itself), status and last reported health. Results are cursor-paginated (default 20, maximum 100) and the q parameter matches the name case-insensitively; a negative limit returns 400. Requires the business:integrations:read permission.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

qstring · query · optional

Resource-specific text search.

categorystring · query · optional

Return only integrations of this category: payment, identity, notification, smart_meter, gis, scada, document_store, accounting or erp.

one of payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

statusstring · query · optional

Return only integrations in this status: active, suspended or disabled.

one of active, suspended, disabled

healthstring · query · optional

Return only integrations whose last reported health is unknown, healthy, degraded or unavailable.

one of unknown, healthy, degraded, unavailable

Returns

200 Tenant-scoped integration registrations

Show attributes
dataarray of Integration · required
Show child attributes
idstring · required
tenant_idstring · required
namestring · required
categorystring · required

one of payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · required
configuration_referencestring · required

Opaque secret/configuration reference; never a secret value.

statusstring · required

one of active, suspended, disabled

healthstring · required

one of unknown, healthy, degraded, unavailable

last_health_check_atstring · optional · nullable
has_moreboolean · required
next_cursorstring · optional

Permissions business:integrations:read · Roles: admin, operations, owner

curl -X GET "$BUSINESS_API/integrations" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "int_2s0jH8wLbKi9jSO5lWaRJWCPxso",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "name": "Ana Matsinhe",
      "category": "payment",
      "provider_key": "provider key",
      "configuration_reference": "CON-2026-000142",
      "status": "active",
      "health": "unknown",
      "last_health_check_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Register utility integration

Logs

POST /integrations

Register utility-scoped integration metadata and a config reference

Secret values are kept by the configured secret provider, not stored in this resource.

Body application/json

namestring · required
categorystring · required

one of payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · required
configuration_referencestring · required

Returns

201 Integration registered

Show attributes
idstring · required
tenant_idstring · required
namestring · required
categorystring · required

one of payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · required
configuration_referencestring · required

Opaque secret/configuration reference; never a secret value.

statusstring · required

one of active, suspended, disabled

healthstring · required

one of unknown, healthy, degraded, unavailable

last_health_check_atstring · optional · nullable

Permissions business:integrations:create · Roles: admin, owner

curl -X POST "$BUSINESS_API/integrations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "category": "payment",
  "provider_key": "provider key",
  "configuration_reference": "CON-2026-000142"
}'
Response 201
{
  "id": "int_2s0jH8wLbKi9jSO5lWaRJWCPxso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "name": "Ana Matsinhe",
  "category": "payment",
  "provider_key": "provider key",
  "configuration_reference": "CON-2026-000142",
  "status": "active",
  "health": "unknown",
  "last_health_check_at": "2026-11-19T09:30:00Z"
}

Get integration registration metadata

Logs

GET /integrations/{id}

Returns one integration registration with its category, provider key, secret configuration reference, status, health and last health check time. Returns 404 when it is not registered in the tenant. Requires the business:integrations:read permission.

Parameters

idstring · path · required

Identifier of the integration within the current tenant.

Returns

200 Integration metadata without provider secrets

Show attributes
idstring · required
tenant_idstring · required
namestring · required
categorystring · required

one of payment, identity, notification, smart_meter, gis, scada, document_store, accounting, erp

provider_keystring · required
configuration_referencestring · required

Opaque secret/configuration reference; never a secret value.

statusstring · required

one of active, suspended, disabled

healthstring · required

one of unknown, healthy, degraded, unavailable

last_health_check_atstring · optional · nullable

Permissions business:integrations:read · Roles: admin, operations, owner

curl -X GET "$BUSINESS_API/integrations/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "int_2s0jH8wLbKi9jSO5lWaRJWCPxso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "name": "Ana Matsinhe",
  "category": "payment",
  "provider_key": "provider key",
  "configuration_reference": "CON-2026-000142",
  "status": "active",
  "health": "unknown",
  "last_health_check_at": "2026-11-19T09:30:00Z"
}

Activate, suspend, or disable a utility integration

Logs

PATCH /integrations/{id}

Sets the integration's status to active, suspended or disabled. Activating requires a configuration reference to be set, otherwise 400, and any other status value also returns 400; 404 for an unknown integration. The handler answers 204 with no body on success. Requires the business:integrations:manage permission.

Parameters

idstring · path · required

Identifier of the integration whose status changes.

Body application/json

statusstring · required

one of active, suspended, disabled

Returns

200 Integration status updated

Permissions business:integrations:manage · Roles: admin, owner

curl -X PATCH "$BUSINESS_API/integrations/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'
Response 200

Integration status updated

Update utility integration configuration

Logs

PUT /integrations/{id}/configuration

Replace an integration's secret reference and disable it until re-enabled

The secret value is never accepted or returned; only a reference to the configured secret provider is stored.

Parameters

idstring · path · required

Identifier of the integration whose secret configuration reference is replaced; after the change it stays disabled until its status is set back to active.

Body application/json

configuration_referencestring · required

Returns

204 Configuration updated; integration is disabled until explicitly enabled

Permissions business:integrations:manage · Roles: admin, owner

curl -X PUT "$BUSINESS_API/integrations/{id}/configuration" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "configuration_reference": "CON-2026-000142"
}'
Response 204

Configuration updated; integration is disabled until explicitly enabled