Get a line reputation audit

GET/v3/phone_numbers/{phoneNumber}/reputation_audit/{auditId}

Returns the audit’s status and, once complete, the report. Audits are scoped to the line in the URL — an auditId started on a different line returns 404.

Path ParametersExpand Collapse

phoneNumber: string

auditId: string

ReturnsExpand Collapse

ReputationAudit object { audit_id, status, error, 3 more }

audit_id: string

status: "pending" or "complete" or "error"

pending until the report is ready — poll until complete or error.

One of the following:

"pending"

"complete"

"error"

error: optional string

Present only when status is error. Short, generic reason safe to display.

generated_at: optional string

When the report was generated; signals reflect the line at this moment.

formatdate-time

phone: optional string

The line audited, E.164.

report: optional ReputationReport { action_items, drivers, evidence, 3 more }

Present only when status is complete.

action_items: optional array of ReputationActionItem { detail, expected_impact, priority, title }

Ordered by priority; 1 = do first.

detail: optional string

expected_impact: optional "high" or "medium" or "low"

One of the following:

"high"

"medium"

"low"

priority: optional number

1 = do first

title: optional string

drivers: optional array of ReputationDriver { key, metric, summary }

Ranked, highest impact first.

key: optional ReputationDriverKey

Stable driver-category identifier — what is dragging the line, or one of its conversations, down.

low_engagement — The conversation is one-sided: several messages sent, few or no replies back. Pause or rework outreach where recipients are not replying, and lead with messages that invite a response. Conversation-level: it appears on evidence.unhealthy_chats[].driver_keys, never in drivers.
overall_conversation_health — A large share of the line’s active conversations are trending unhealthy. Fix those conversations first — review their content and timing, and whether recipients are engaging.
volume_spike — The line’s daily sending volume jumped far above its own normal level. Ramp gradually instead of spiking, spread large sends across days, and prioritize people who have already engaged.
new_conversation_rate — The line is starting too many brand-new conversations in a single day. Spread new conversations out over time instead of starting many at once.
opt_out_handling — Recipients asked this line to stop. Honor every stop request immediately: send nothing further to that recipient unless they opt back in. Every send to them is rejected with 403 (error code 2024), including a final courtesy message — to send one telling them they can reply to resume, set override_optout: true on that single request.
flagged — The line is currently restricted and its messages may not be reaching recipients. Move active traffic to a healthy line now, and let this one recover before sending more.
other — Fallback for a signal without dedicated partner copy.

One of the following:

"low_engagement"

"overall_conversation_health"

"volume_spike"

"new_conversation_rate"

"opt_out_handling"

"flagged"

"other"

metric: optional string

A specific observed figure when available; otherwise a short qualitative note.

summary: optional string

One plain-English sentence.

evidence: optional ReputationEvidence { opt_out_chats, unhealthy_chats }

The specific conversations behind the drivers, so partners can verify every claim against their own send logs. Each chat_id can be fetched via GET /v3/chats/{chatId} — its current health appears there.

opt_out_chats: optional array of ReputationOptOutChat { chat_id, messages_after_stop }

Worst first — most messages sent after the stop request; honor these immediately.

chat_id: optional string

messages_after_stop: optional number

Outbound messages sent after the recipient asked to stop.

unhealthy_chats: optional array of ReputationUnhealthyChat { chat_id, driver_keys, status }

Up to 15, worst first.

chat_id: optional string

driver_keys: optional array of ReputationDriverKey

What is dragging this conversation down, in the same vocabulary as the report’s drivers. Each key’s meaning and the fix for it are documented on ReputationDriverKey.

One of the following:

"low_engagement"

"overall_conversation_health"

"volume_spike"

"new_conversation_rate"

"opt_out_handling"

"flagged"

"other"

status: optional "AT_RISK" or "CRITICAL" or "OPTED_OUT"

The conversation’s current health — the same value GET /v3/chats/{chatId} reports for it.

One of the following:

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

primary_driver: optional string

The key of the most important driver. Empty string when the line has nothing to act on — the report then carries a single reassurance action item. Its values are the ReputationDriverKey vocabulary — see that schema for what each means and what to do about it.

severity: optional "HEALTHY" or "AT_RISK" or "CRITICAL"

Current reputation of this phone line.

HEALTHY — The line is in good standing. Send normally.
AT_RISK — Warning signs on the line: engagement is low across many of its conversations, or it’s starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line’s send pace, avoid opening many new conversations at once, and review your messaging patterns.
CRITICAL — Strong signals that messages from this line aren’t landing well. Pause outbound on the line until it recovers.

Defaults to HEALTHY for lines that have not yet been scored.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

summary_markdown: optional string

Deterministic markdown rendering of this report, suitable for feeding directly to automated systems and AI agents as investigation context. Rendered from the structured fields above, which remain the source of truth.

Get a line reputation audit

curl https://api.linqapp.com/api/partner/v3/phone_numbers/$PHONE_NUMBER/reputation_audit/$AUDIT_ID \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY"

{
  "audit_id": "audit_id",
  "status": "pending",
  "error": "error",
  "generated_at": "2019-12-27T18:11:19.117Z",
  "phone": "phone",
  "report": {
    "action_items": [
      {
        "detail": "detail",
        "expected_impact": "high",
        "priority": 0,
        "title": "title"
      }
    ],
    "drivers": [
      {
        "key": "low_engagement",
        "metric": "metric",
        "summary": "summary"
      }
    ],
    "evidence": {
      "opt_out_chats": [
        {
          "chat_id": "chat_id",
          "messages_after_stop": 0
        }
      ],
      "unhealthy_chats": [
        {
          "chat_id": "chat_id",
          "driver_keys": [
            "low_engagement"
          ],
          "status": "AT_RISK"
        }
      ]
    },
    "primary_driver": "primary_driver",
    "severity": "HEALTHY",
    "summary_markdown": "## Line reputation summary\n\n**Status:** AT_RISK\n..."
  }
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "audit_id": "audit_id",
  "status": "pending",
  "error": "error",
  "generated_at": "2019-12-27T18:11:19.117Z",
  "phone": "phone",
  "report": {
    "action_items": [
      {
        "detail": "detail",
        "expected_impact": "high",
        "priority": 0,
        "title": "title"
      }
    ],
    "drivers": [
      {
        "key": "low_engagement",
        "metric": "metric",
        "summary": "summary"
      }
    ],
    "evidence": {
      "opt_out_chats": [
        {
          "chat_id": "chat_id",
          "messages_after_stop": 0
        }
      ],
      "unhealthy_chats": [
        {
          "chat_id": "chat_id",
          "driver_keys": [
            "low_engagement"
          ],
          "status": "AT_RISK"
        }
      ]
    },
    "primary_driver": "primary_driver",
    "severity": "HEALTHY",
    "summary_markdown": "## Line reputation summary\n\n**Status:** AT_RISK\n..."
  }
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}