Submitting Feedback

Pick a signal

The valid signal depends on theresource_type. Each type has one positive signal plus the specific ways it can be wrong. The full list lives in the API reference; the common ones:

1. Hold onto the resource id

You already have it: the id of the bill you render, or the account-connection (account link) id. That’s theresource_id — no run id, no biller id to track. BillerAPI resolves the producing run on its side.

2. POST the feedback

On submission, POST with an idempotency_key so a network retry doesn’t double-count. Generate it once at the moment the user clicks submit and re-send it on retry. Recommended format: idem_<timestamp>_<resource_id>.

async function submitFeedback({ resourceType, resourceId, signal, notes }) {
  // Generated ONCE here. If the network errors and you retry, reuse this same key.
  const idempotencyKey = `idem_${Date.now()}_${resourceId}`;

  const res = await fetch('https://sandbox.api.billerapi.com/v1/feedback', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer $BILLERAPI_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      resource_type: resourceType,   // 'bill' | 'account_connection'
      resource_id: resourceId,
      signal,                        // valid values depend on resource_type
      idempotency_key: idempotencyKey,
      notes,                         // optional, recommended when reporting a problem
    }),
  });

  if (!res.ok) {
    const error = await res.json();
    throw new Error(`feedback failed: ${error.error_code} — ${error.error_message}`);
  }
  return await res.json();  // { resource_type, resource_id, agent_type, signal, attributable, run_id?, already_existed }
}

3. Handle the response

Success is 202 Accepted. Two fields on the response are worth reading; the full error catalog is at Feedback errors.

• attributable: false — recorded, but BillerAPI couldn’t locate the producing run (unknown or aged out). This is normal and not an error; the feedback is still stored.
• already_existed: true — idempotent replay; nothing new was written. Safe.
• 400 FEEDBACK_INVALID_SIGNAL — the signal isn’t valid for the resource_type (or the key is missing). Fix client-side validation.
• 404 FEEDBACK_RUN_NOT_FOUND — the resource doesn’t exist or isn’t owned by your client. Don’t expose to the user; log + investigate.
• 409 FEEDBACK_ALREADY_SUBMITTED — a different key already submitted for this resource. Reuse the original key to replay, or treat as success.

What happens to your feedback

Attributed feedback enters the per-biller signal pipeline:

• Positive signals (bill_correct, accounts_correct) — count toward auto-promote thresholds for the prompt version that ran. Affirmative feedback is what lets winning versions graduate.
• Everything-wrong signals — count toward auto-rollback thresholds. A cluster on the same biller crosses the threshold and reverts the agent to its prior prompt version without human intervention.

This is why high-quality feedback matters. A noisy stream of mis-categorized signals or empty notes dilutes the pipeline. Gate on user confirmation, populate notes with the specifics, and the per-biller signal compounds.