Telecom Roaming Audit API Documentation

POSThttps://www.brainiac.software/api/v1/telecom-billing/roaming-charge-audit$0.04 USDC

Audit roaming charges

Recalculate international roaming charges from caller-supplied usage, tariff rules, packages, country zones, and billed charges. A usage row is priced only when exactly one tariff matches. Missing or ambiguous tariffs are reported and never assumed. Daily-pass packages zero incremental usage. Positive actual-minus-expected deltas form estimated overbilling by currency. No FX conversion is applied.

Body

Field	Required	Notes
`usage`	Yes	array; Array
`tariffs`	No	array; Array
`packages`	No	array; Array
`zones`	No	array; Array
`billed_charges`	Yes	array; Array

Request exampleJSON

{
  "usage": [
    {
      "id": "u1",
      "type": "data",
      "country": "FR",
      "started_at": "2026-11-05T10:00:00.000Z",
      "units": 5000000,
      "unit_kind": "bytes"
    },
    {
      "id": "u2",
      "type": "call",
      "country": "DE",
      "started_at": "2026-11-05T11:00:00.000Z",
      "units": 120,
      "unit_kind": "seconds"
    },
    {
      "id": "u3",
      "type": "sms",
      "country": "FR",
      "started_at": "2026-11-05T12:00:00.000Z",
      "units": 2,
      "unit_kind": "messages"
    }
  ],
  "zones": [
    {
      "zone": "eu",
      "country": "FR"
    },
    {
      "zone": "eu",
      "country": "DE"
    }
  ],
  "tariffs": [
    {
      "id": "tf-data",
      "type": "data",
      "zone": "eu",
      "currency": "EUR",
      "rate_per_unit": 1,
      "unit_kind": "bytes",
      "effective_from": "2026-01-01",
      "daily_cap": 2000000
    },
    {
      "id": "tf-call",
      "type": "call",
      "country": "DE",
      "currency": "EUR",
      "rate_per_unit": 5,
      "unit_kind": "seconds",
      "effective_from": "2026-01-01"
    }
  ],
  "packages": [
    {
      "id": "pass-fr",
      "type": "daily_pass",
      "country": "FR",
      "currency": "EUR",
      "price": 500,
      "effective_from": "2026-01-01"
    }
  ],
  "billed_charges": [
    {
      "id": "b1",
      "usage_id": "u1",
      "type": "data",
      "country": "FR",
      "currency": "EUR",
      "amount": 1000,
      "billed_at": "2026-11-06T00:00:00.000Z"
    },
    {
      "id": "b2",
      "usage_id": "u2",
      "type": "call",
      "country": "DE",
      "currency": "EUR",
      "amount": 900,
      "billed_at": "2026-11-06T00:00:00.000Z"
    },
    {
      "id": "b3",
      "usage_id": "u2",
      "type": "call",
      "country": "DE",
      "currency": "EUR",
      "amount": 900,
      "billed_at": "2026-11-06T00:01:00.000Z"
    },
    {
      "id": "b4",
      "package_id": "pass-fr",
      "type": "daily_pass",
      "country": "FR",
      "currency": "EUR",
      "amount": 500,
      "billed_at": "2026-11-05T23:00:00.000Z"
    }
  ]
}

Response exampleJSON

{
  "expected_charges": [
    {
      "usage_id": "u1",
      "type": "data",
      "country": "FR",
      "currency": "EUR",
      "expected_amount": 0,
      "tariff_id": "pass-fr",
      "status": "priced",
      "evidence": [
        "Covered by daily_pass package pass-fr on 2026-11-05; incremental usage charge is 0 under that package."
      ]
    },
    {
      "usage_id": "u2",
      "type": "call",
      "country": "DE",
      "currency": "EUR",
      "expected_amount": 600,
      "tariff_id": "tf-call",
      "status": "priced",
      "evidence": [
        "expected_amount = units 120 * rate_per_unit 5 under tariff tf-call."
      ]
    },
    {
      "usage_id": "u3",
      "type": "sms",
      "country": "FR",
      "currency": "EUR",
      "expected_amount": 0,
      "tariff_id": "pass-fr",
      "status": "priced",
      "evidence": [
        "Covered by daily_pass package pass-fr on 2026-11-05; incremental usage charge is 0 under that package."
      ]
    }
  ],
  "differences": [
    {
      "usage_id": "u1",
      "billed_id": "b1",
      "kind": "amount_difference",
      "currency": "EUR",
      "expected_amount": 0,
      "actual_amount": 1000,
      "delta": 1000,
      "evidence": [
        "actual 1000 - expected 0 = 1000."
      ]
    },
    {
      "usage_id": "u2",
      "billed_id": "b2",
      "kind": "amount_difference",
      "currency": "EUR",
      "expected_amount": 600,
      "actual_amount": 900,
      "delta": 300,
      "evidence": [
        "actual 900 - expected 600 = 300."
      ]
    }
  ],
  "incorrectly_applied_rules": [],
  "duplicate_charges": [
    {
      "usage_id": "u2",
      "billed_ids": [
        "b2",
        "b3"
      ],
      "detail": "Multiple billed charges reference the same usage_id."
    }
  ],
  "allowance_violations": [],
  "estimated_overbilling": [
    {
      "currency": "EUR",
      "amount": 1300
    }
  ],
  "summary": {
    "usage_records": 3,
    "billed_charges": 4,
    "priced_usage": 3,
    "unpriced_usage": 0,
    "differences": 2,
    "duplicate_charges": 1,
    "allowance_violations": 0
  },
  "explanations": [
    "A usage row is priced only when exactly one tariff matches its type, country/zone, and effective dates. Missing or ambiguous tariffs are reported and never assumed.",
    "expected_amount = usage.units * tariff.rate_per_unit, optionally capped by tariff.daily_cap.",
    "Daily-pass packages zero incremental usage charges for covered country/zone days; package price itself is compared when billed.",
    "delta = actual_amount - expected_amount. Positive delta contributes to estimated_overbilling by currency.",
    "No FX conversion is performed across currencies."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/telecom-billing/roaming-charge-audit" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "usage": [
    {
      "id": "u1",
      "type": "data",
      "country": "FR",
      "started_at": "2026-11-05T10:00:00.000Z",
      "units": 5000000,
      "unit_kind": "bytes"
    },
    {
      "id": "u2",
      "type": "call",
      "country": "DE",
      "started_at": "2026-11-05T11:00:00.000Z",
      "units": 120,
      "unit_kind": "seconds"
    },
    {
      "id": "u3",
      "type": "sms",
      "country": "FR",
      "started_at": "2026-11-05T12:00:00.000Z",
      "units": 2,
      "unit_kind": "messages"
    }
  ],
  "zones": [
    {
      "zone": "eu",
      "country": "FR"
    },
    {
      "zone": "eu",
      "country": "DE"
    }
  ],
  "tariffs": [
    {
      "id": "tf-data",
      "type": "data",
      "zone": "eu",
      "currency": "EUR",
      "rate_per_unit": 1,
      "unit_kind": "bytes",
      "effective_from": "2026-01-01",
      "daily_cap": 2000000
    },
    {
      "id": "tf-call",
      "type": "call",
      "country": "DE",
      "currency": "EUR",
      "rate_per_unit": 5,
      "unit_kind": "seconds",
      "effective_from": "2026-01-01"
    }
  ],
  "packages": [
    {
      "id": "pass-fr",
      "type": "daily_pass",
      "country": "FR",
      "currency": "EUR",
      "price": 500,
      "effective_from": "2026-01-01"
    }
  ],
  "billed_charges": [
    {
      "id": "b1",
      "usage_id": "u1",
      "type": "data",
      "country": "FR",
      "currency": "EUR",
      "amount": 1000,
      "billed_at": "2026-11-06T00:00:00.000Z"
    },
    {
      "id": "b2",
      "usage_id": "u2",
      "type": "call",
      "country": "DE",
      "currency": "EUR",
      "amount": 900,
      "billed_at": "2026-11-06T00:00:00.000Z"
    },
    {
      "id": "b3",
      "usage_id": "u2",
      "type": "call",
      "country": "DE",
      "currency": "EUR",
      "amount": 900,
      "billed_at": "2026-11-06T00:01:00.000Z"
    },
    {
      "id": "b4",
      "package_id": "pass-fr",
      "type": "daily_pass",
      "country": "FR",
      "currency": "EUR",
      "amount": 500,
      "billed_at": "2026-11-05T23:00:00.000Z"
    }
  ]
}
JSON