Skip to content

Property Usage and Credits

Property Usage tracks properties delivered to an account during its billing period. When credits are enabled, the monthly allowance is used first; Auto Use can pay for eligible properties after the allowance is exhausted. Auto Add can replenish the credit balance automatically.

All /api/internal/ endpoints below use the DataSift API authentication described in Authentication. The API reference lists the request and response schemas.

Endpoints

MethodPathPurpose
GET/api/internal/credits/settings/Read Auto Use and Auto Add settings (billing_read)
PATCH/api/internal/credits/settings/Update Auto Use and Auto Add settings (credits_write)
POST/api/internal/property-usage/view/Meter a SiftMap property detail view
GET/api/internal/credits/history/List credit transactions (billing_read)
GET/api/internal/credits/history/{uuid}/receipt/Get a card transaction's Stripe receipt (billing_read)
GET/api/internal/property-usage/history/List property usage events
GET/api/internal/property-usage/history/{uuid}/fetched-properties/List the properties delivered by a usage event
GET/api/internal/account/details/Read account details, including property_usage
POST/api/internal/upload/usage/Read upload usage and property_usage

Credit settings and credit history require a valid account. Credit history and receipts additionally require billing_read; changing settings requires credits_write. For property usage history, callers with billing_read see all account events; other callers see only their own events.

Usage summary

Account details and upload usage include a property_usage object. When credits are disabled for the account, it is:

{"credits_enabled": false}

When enabled, the object includes the billing period and renewal date, properties used and allowance remaining, overage rate and balance, Auto Use/Auto Add state, and usage_state. Its values are:

usage_stateMeaning
normalUsage is below the warning threshold
warningUsage has reached the configured warning threshold
reached_blockedAllowance is exhausted and another property cannot be paid for
reached_billingAllowance is exhausted and Auto Use can pay for additional properties
low_balanceAllowance is exhausted, Auto Use is active, and balance is low

limit and allowance_left are null when the account's plan has no allowance limit. Monetary values are returned as decimal strings.

POST /api/internal/upload/usage/ accepts an optional storage_key. When supplied, the response also includes line_count for that CSV.

Credit settings

Read settings with GET /api/internal/credits/settings/. If settings have never been saved, the endpoint returns defaults without creating a database record.

Use PATCH /api/internal/credits/settings/ to change only the supplied fields:

{
  "auto_use_enabled": true,
  "auto_add_enabled": true,
  "auto_add_threshold": "5.00",
  "auto_add_amount": "25.00",
  "auto_add_payment_method_id": "pm_example"
}

Enabling Auto Add requires a threshold, a top-up amount at or above the configured credit minimum, and an account-owned Stripe payment method. Disabling Auto Add clears its saved payment method. auto_add_failed_at is read-only.

Metering a SiftMap detail view

Before returning full SiftMap property details, call POST /api/internal/property-usage/view/ with the property's dataflik_id:

{"dataflik_id": 123456}

The response reports out_of_usage, auto_use_required, credit amounts, usage consumed/used/limit, and the resulting usage_state. Already-owned properties and properties fetched earlier in the current period do not incur another charge. When out_of_usage is true, the SiftMap client should return basic details only. If credits are disabled, the credit and usage figures are null.

The history endpoints accept inclusive start_date and end_date filters. Date-only values cover the full US Central calendar day; offset-free datetimes are interpreted as US Central. Both history lists are paginated. Usage event rows identify the actor and API-key type when available; the fetched-properties endpoint lists each property first delivered by that event, with its Dataflik ID, address, APN, and timestamp.

Property creation and metering responses

The metered public POST /property/ route is a separate integration endpoint protected by a Zapier-specific API key; it is not an OpenAPI-key endpoint. When Property Usage Credits are enabled, successful metered responses include:

HeaderMeaning
X-Credits-ConsumedDollars consumed by the request
X-Credits-RemainingCredit balance after the request
X-Usage-ConsumedProperties added to the usage counter
X-Usage-UsedUsage counter after the request
X-Usage-LimitPeriod limit; omitted when the plan has no limit
X-Usage-StateUsage state after the request

When the allowance is exhausted and the request cannot be met, the endpoint returns HTTP 402. Its JSON code is auto_use_required when Auto Use is off, or insufficient_credits when the available credit balance cannot pay. The legacy upload-limit response remains in effect for accounts without Property Usage Credits.

These headers and 402 behavior apply to metered create requests, not to the read-only usage summary or the SiftMap view-metering endpoint.