Get Started
API DOCUMENTATION

Will This Person Answer API

Send the contacts you plan to call. Get back a grade, next action, reason and supporting signals for each one, through the REST API or MCP.

ENDPOINTPOST /api/v1/analyze
AUTHBearer token
FORMATJSON in, JSON out
COVERAGEUS contacts only
GETTING STARTED

Authentication

Every request needs your API key. Sign up free, then create a key. Keep it secret and only use it from your server, never in browser code.

Send the key in the Authorization header on every request. The base URL is https://app.willthispersonanswer.com.

HEADER
Authorization: Bearer YOUR_API_KEY
REST API

Analyse contacts

POST/api/v1/analyze

Send one or more contacts in a single request. Each contact analysed uses one credit.

Request body

FIELDTYPEDESCRIPTION
contactsarrayRequired. The contacts to analyse. Maximum per request: 100 contacts.
contacts[].first_namestringRequired. The contact’s first name.
contacts[].last_namestringRequired. The contact’s last name.
contacts[].phonestringRequired. A US phone number, e.g. +16091843726.

Example request

CURL
curl -X POST "https://app.willthispersonanswer.com/api/v1/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contacts":[{"first_name":"Tavin","last_name":"Orrell","phone":"+16091843726"}]}'
REQUEST
POST /api/v1/analyze

{
  "contacts": [
    {
      "first_name": "Tavin",
      "last_name": "Orrell",
      "phone": "+16091843726"
    }
  ]
}

Example response

RESPONSE
{
  "results": [
    {
      "phone": "+16091843726",
      "status": "ok",
      "grade": "A1",
      "action": "call_first",
      "reason": "The number is valid, the supplied name matches the number, and the line shows strong activity signals.",
      "signals": {
        "valid": true,
        "line_type": "mobile",
        "activity": "strong",
        "name_match": true,
        "litigation_risk": false
      }
    }
  ],
  "summary": {
    "analyzed": 1,
    "grades": { "A1": 1, "A2": 0, "A3": 0, "X": 0 },
    "undetermined": 0
  }
}

Response fields

The grade tells you what to do. The reason tells you why. Signals come after.

FIELDTYPEDESCRIPTION
results[].gradestring | nullA1, A2, A3 or X. Null where the analysis did not finish.
results[].actionstring | nullWhat to do next, e.g. call_first.
results[].reasonstringWhy the contact got this grade, in plain English. Deterministic: the same signals always produce the same sentence.
results[].phonestringThe phone number this result refers to.
results[].statusstringResult status, e.g. ok. Other values: ok, invalid_request, unsupported_market, incomplete, provider_unavailable.
results[].signals.validboolean | nullWhether the line is real. Null where nobody could establish it.
results[].signals.line_typestringLine type, e.g. mobile. Other values: mobile, landline, voip, other, unknown.
results[].signals.activitystringActivity level, e.g. strong. Other values: strong, weak, silent.
results[].signals.name_matchboolean | nullWhether the supplied name matches the number. Null where there is no opinion.
results[].signals.litigation_riskboolean | nullTrue found, false screened and clean, null no answer. Null is never clean.
summary.analyzedintegerHow many contacts were analysed.
summary.gradesobjectCount of results per grade.
summary.undeterminedintegerContacts that didn’t get a grade. A contact comes back undetermined when the analysis did not finish: the input was not usable (invalid_request), the number is outside the US (unsupported_market), we could not establish enough about the contact to grade it - the number could not be confirmed valid, or the litigation screen did not complete (incomplete) - or the provider could not be reached (provider_unavailable). Its grade and action are null. A null grade is never an X: it means we do not know, not that the contact is bad.

Grades and actions

Every graded contact comes back with one of four grades, each mapped to one action. The grade is decided from the evidence returned beside it: whether the number is valid, whether the supplied name matches it, and how active the line looks.

GRADEACTIONACTION VALUEWHY THIS GRADEWHAT TO DO
A1Call Firstcall_firstValid number, the supplied name matches the number, and strong activity signals.Put this contact at the top of your calling list.
A2Call Nextcall_nextValid number and the supplied name matches the number, but strong activity is not confirmed.Call this contact after your A1s.
A3LinkedIn + Emaillinkedin_emailValid number, but the name association is not confirmed or does not match.Work your A1 and A2 contacts first. Use the other information you have about the contact before prioritising another call.
XRemoveremoveOne or more hard negative signals: an invalid number, weak activity signals, overall contactability too weak, or litigation risk. Not every X carries every one.Remove this contact from the active calling queue.

Errors

Errors return a non-200 status code and a JSON body. { "error": { "code": "invalid_request", "message": "..." } }

STATUSWHENWHAT TO DO
401 invalid_api_keyMissing or invalid API keySend it as Authorization: Bearer YOUR_API_KEY.
402 insufficient_creditsNot enough credits for the whole batchNothing was analysed and nothing was charged. Top up or upgrade, then retry.
400 invalid_requestBody is not valid JSON, or `contacts` is missing, empty or longer than 100Check the required fields and the phone format.
200 with status unsupported_marketA non-US phone numberNot an error. The contact comes back inside a normal 200 with `status: "unsupported_market"`, a null grade and no charge - no upstream call is made.
429 rate_limit_exceededOver the rate limitWait and retry. The response carries a Retry-After header holding 60.
500 internal_errorSomething broke on our sideNothing was charged. Retry.

Limits and credits

ITEMDETAIL
Credits per contact1 credit analyses 1 contact.
Credit expiryCredits never expire.
Shared balanceAPI and MCP use the same account and credits.
Undetermined contactsNo. Only a contact that came back with a grade is charged for, so undetermined contacts cost nothing.
Contacts per request100 contacts
Rate limit60 requests per 60 seconds, per API key, shared between REST and MCP
CoverageUS contacts only.
MCP

Connect through MCP

Add Will This Person Answer to any MCP client and ask it to prioritise contacts in plain English. It uses the same account and credits as the API.

Server URL

https://mcp.willthispersonanswer.com

Add it to your client

Claude: Run: claude mcp add --transport http will-this-person-answer https://mcp.willthispersonanswer.com --header "Authorization: Bearer YOUR_API_KEY" -s user

Other MCP clients: Add an HTTP MCP server pointing at https://mcp.willthispersonanswer.com, with the header Authorization: Bearer YOUR_API_KEY. The same key and the same credits as the REST API.

MCP CONFIG
{
  "mcpServers": {
    "will-this-person-answer": {
      "url": "https://mcp.willthispersonanswer.com"
    }
  }
}

Example prompt

“Prioritise this outbound list and tell me who to call first.”

MCP tools

The tools your agent can use once connected.

TOOLWHAT IT DOES
analyze_contactsAnalyses contacts you are planning to call and returns, for each one, a grade (A1, A2, A3 or X), an action, a plain-language reason and the supporting signals the grade was decided from. One credit per contact that came back with a grade. Litigation screening is included and is not optional. US contacts only; each contact needs a first name, a last name and a phone number.
Ready to try it?
Start with 250 free credits. No card required.
Get API key