DID Health Monitoring

Trunx continuously monitors every DID in your pool. Health scores drive automatic rotation, cooldown, and burning decisions so you don't have to manage phone number reputation manually.

How Health Scores Work

Each DID's health score is a weighted average computed over the last 50 calls:

Scores are recomputed after every call event. The did-health job writes events to the did_health_events table and recalculates the score — no in-memory state, no data loss on restart.

Health Thresholds

DID Lifecycle States

Every DID moves through a defined set of states:

warming → active → cooling → burned → quarantine

Warming — Newly provisioned DIDs start here. Call volume is limited according to the warming schedule (see below). This builds a clean call history before full-volume usage.

Active — The DID is in normal rotation. The campaign engine selects it based on health score and local presence matching.

Cooling — The DID hit its max_calls_per_did threshold and is resting for 2 hours. It returns to active automatically.

Burned — Health score dropped below 0.5. The DID is removed from all rotation and flagged for manual review.

Quarantine — The DID was flagged by an external reputation provider. It remains quarantined until the flag is cleared and an admin reactivates it.

Warming Schedule

New DIDs follow a graduated volume ramp to establish clean reputation with carriers:

Cooling Strategy

The default cooling configuration:

• 200 calls per DID, then 2-hour cooldown, then back to rotation
• With a pool of 5,000+ DIDs and 50 active at a time: 200 x 50 = 10,000 calls before any DID needs a second rotation

This rotation pattern keeps each DID's call volume well below carrier flagging thresholds. The did-lifecycle job checks DID states every 60 seconds and transitions cooling DIDs back to active when their rest period is complete.

API Endpoints

Pool overview

curl https://api.trunx.io/dids/health \
  -H "Authorization: Bearer $TRUNX_API_KEY"

Returns aggregate health statistics across your entire DID pool: counts by state, average health score, and DIDs needing attention.

Single DID detail

curl https://api.trunx.io/dids/+14155559876/health \
  -H "Authorization: Bearer $TRUNX_API_KEY"

Returns the full health profile for a single DID: current score, factor breakdown, lifecycle state, call history summary, and reputation flags.

Manual cooldown

curl -X POST https://api.trunx.io/dids/+14155559876/cooldown \
  -H "Authorization: Bearer $TRUNX_API_KEY"

Immediately pull a DID from rotation and start a 2-hour cooldown period.

Reactivate

curl -X POST https://api.trunx.io/dids/+14155559876/activate \
  -H "Authorization: Bearer $TRUNX_API_KEY"

Move a DID from cooling or quarantine back to active rotation.

Mark as burned

curl -X POST https://api.trunx.io/dids/+14155559876/burn \
  -H "Authorization: Bearer $TRUNX_API_KEY"

Permanently remove a DID from rotation. Use this when you know a number has been flagged by carriers.

SSE Events

Subscribe to real-time DID health events:

curl -N https://api.trunx.io/events?channels=did-health \
  -H "Authorization: Bearer $TRUNX_API_KEY"