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.
| Method | Path | Purpose |
|---|---|---|
| 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.
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_state | Meaning |
|---|---|
normal | Usage is below the warning threshold |
warning | Usage has reached the configured warning threshold |
reached_blocked | Allowance is exhausted and another property cannot be paid for |
reached_billing | Allowance is exhausted and Auto Use can pay for additional properties |
low_balance | Allowance 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.
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.
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.
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:
| Header | Meaning |
|---|---|
X-Credits-Consumed | Dollars consumed by the request |
X-Credits-Remaining | Credit balance after the request |
X-Usage-Consumed | Properties added to the usage counter |
X-Usage-Used | Usage counter after the request |
X-Usage-Limit | Period limit; omitted when the plan has no limit |
X-Usage-State | Usage 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.