Report bad contact data - Forager.ai Docs

Report bad contact data: call and email outcomes flow back to Forager through the feedback endpoints

Report bad contact data: call and email outcomes flow back to Forager through the feedback endpoints

When you call a number or email an address that Forager returned, send the outcome back with the feedback endpoints. Each report is stored as its own record. A dialer or sequencer can send one automatically after every call or bounce.

Choose the endpoint

You contacted	Endpoint	Required fields	`contact_status` values
A phone number	Phone number feedback	`phone_number`, `contact_status`	`connected`, `disconnected`
A personal email	Personal email feedback	`email`, `contact_status`	`valid`, `invalid`
A work email	Work email feedback	`email`, `contact_status`	`valid`, `invalid`

Optional fields on all three:

is_correct_person: true if the person was confirmed, false if it was the wrong person. Omit it or send null when you couldn’t tell; for example, a disconnected number reaches nobody. null means “unknown”, which is different from false.
name: the name you believe the contact belongs to.
person_id: the Forager person ID the contact came from.

Send a report

curl -X POST "https://api-v2.forager.ai/api/$FORAGER_ACCOUNT_ID/datastorage/feedback/phone_numbers/" \
  -H "X-API-KEY: $FORAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+12025550142", "contact_status": "connected", "is_correct_person": true, "person_id": 1234567}'

import os, requests

resp = requests.post(
    f"https://api-v2.forager.ai/api/{os.environ['FORAGER_ACCOUNT_ID']}/datastorage/feedback/phone_numbers/",
    headers={"X-API-KEY": os.environ["FORAGER_API_KEY"]},
    json={"phone_number": "+12025550142", "contact_status": "connected",
          "is_correct_person": True, "person_id": 1234567},
)
resp.raise_for_status()  # 201 Created

const resp = await fetch(
  `https://api-v2.forager.ai/api/${process.env.FORAGER_ACCOUNT_ID}/datastorage/feedback/phone_numbers/`,
  {
    method: "POST",
    headers: { "X-API-KEY": process.env.FORAGER_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      phone_number: "+12025550142", contact_status: "connected",
      is_correct_person: true, person_id: 1234567,
    }),
  },
);
if (resp.status !== 201) throw new Error(`Forager returned ${resp.status}`);

Phone numbers can be sent in any format; Forager normalizes them to E.164. Personal emails are lowercased and trimmed before storage.

Responses

Status	Meaning
`201`	Stored. The body echoes the record with its `id` and `date_created`.
`400`	Validation failed: an unparseable phone number or email, an unknown `contact_status`, or a missing required field.
`403`	Missing or invalid `X-API-KEY`, a key for a different account, or an inactive key user.
`429`	Rate limited. The feedback endpoints share a budget of 60 requests per minute per account.

Feedback requests are free: they don’t use credits.

Last modified on October 28, 2026