Twilio's API now tells you which STIR/SHAKEN attestation each call went out with: here's how your voice agent can use it

Twilio announced on November 5 in its changelog that the Call resource in its Voice API now returns the STIR/SHAKEN status of each call in a new field, stir_verstat. It sounds like a fine-print detail, but it isn't if you run an AI voice agent, a reminder system or a sales dialer that calls phones in the United States: STIR/SHAKEN attestation is what carriers use to decide whether your caller ID can be trusted or whether your number ends up with a "possible spam" label on the recipient's screen. Until now, finding out meant catching webhooks in the moment. Now you can look it up afterward, call by call or in bulk, from the same API you already use.

What exactly Twilio announced

The notice is short and is marked as generally available (GA) in the Voice API. It says three things:

• The Call resource returns the STIR/SHAKEN status of each call in the stir_verstat property.
• It appears when you fetch a call or read a list of calls, and it's built into Twilio's server-side SDKs.
• The use Twilio proposes: confirm that your calls carry A attestation and find the ones signed with B or C so you can fix them.

In the Call resource reference, the field appears as a string, with an example like TN-Validation-Passed-A, and a note that it comes back empty if the call carried no STIR/SHAKEN information. All the response examples on that page already include it.

STIR/SHAKEN in two minutes

According to Twilio's guide on trusted calling, STIR (Secure Telephone Identity Revisited) is an IETF protocol for authenticating calls end to end, and SHAKEN is the ATIS specification that puts that protocol into practice so carriers can verify each other. Together they fight caller ID spoofing: the carrier originating the call signs it cryptographically and the terminating carrier can check that nobody tampered with it along the way. Twilio says it currently signs all its US calls with the appropriate attestation to meet its obligations under the TRACED Act, the US law against fraudulent robocalls.

The signature carries an attestation level:

• A: the carrier knows the customer and knows they have the right to use that number as caller ID.
• B: the customer is known, but there's no proof they have the right to use that number.
• C: meets neither A nor B; international calls, for example, fall here.

Twilio clarifies something that matters a lot if you're reading this from Mexico: its STIR/SHAKEN support is only deployed in the United States and France. If your voice bot calls Mexican numbers from Mexican numbers, this field won't tell you much. If you call the US, for example for customers there or with Twilio numbers from that country, it will.

How you get an A (and why you sometimes get B or C)

The onboarding guide explains what decides the level Twilio signs your outbound calls with:

• A: an approved Business Profile, an approved SHAKEN/STIR Trust Product linked to that profile, and the number assigned to both. Only calls coming from those assigned numbers are signed with A.
• B: at a minimum, an approved primary Business Profile and a SHAKEN/STIR Trust Product linked to the parent account. You don't need to assign numbers. Also, B is the most you can get if you use non-Twilio numbers, because Twilio can't vouch that you have the right to use them.
• C: no approved profiles, or rejected profiles.

Twilio's compliance team takes up to 24 hours to review the Business Profile and up to 72 hours to review the SHAKEN/STIR Trust Product, according to that same guide. And here's the classic mistake: approving the profile and forgetting to assign a new number. That number keeps going out with B and nobody notices until the answer rate drops.

What values stir_verstat can have

Twilio's guide lists the possible values, which are shared with the StirVerstat webhook parameter and the X-Twilio-VerStat header in Elastic SIP Trunking:

One nuance: the field description in the API reference talks about the incoming call ("empty if the incoming call had no STIR/SHAKEN information"), while the changelog presents it as the way to check the attestation of your calls. My reading is that the field reflects the STIR/SHAKEN status Twilio has recorded for each leg of the call, but the documentation doesn't make it entirely clear for each direction. Before building alerts on top of it, it's worth seeing what it returns on your own outbound and inbound calls.

How to use it in a voice bot

I haven't tested it; this comes from Twilio's official documentation. The field comes in the usual response:

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.json

{
  "sid": "CA…",
  "status": "completed",
  "direction": "outbound-api",
  "stir_verstat": "TN-Validation-Passed-A"
}

Three uses that come to mind for anyone running voice bots and agents:

1. Daily audit. Read the day's call list and count how many went out with A, B, C or no data. If B shows up on a number that should have A, it almost certainly still needs to be assigned to the Business Profile and the Trust Product.
2. Correlation with outcomes. Cross stir_verstat with status (no-answer, busy, completed) and with answered_by if you use answering machine detection. If calls with B or C get answered less, you now have the data-backed argument to go through the process for A.
3. Decisions on inbound calls. For the inbound call, Twilio already sent StirVerstat in the webhook, and its guide suggests using it to show a trust indicator or to decide the routing, for example skipping an IVR or a verification if the call comes in with A. Now that same data is stored in the Call resource, so your bot can check it later without having saved it at the time.

If you were already listening to status callbacks, Twilio also sends StirStatus with values A, B, C or null in the ringing and in-progress events. The new field doesn't replace it: it complements it with something you can query whenever you want.

What this means

My take: the real value is in observability. Attestation always existed, but it lived in a webhook that many people didn't store, so the diagnosis of "nobody answers my calls" stayed in guesswork. Twilio itself says in its guide that, for AI agents and automated notifications, high attestation helps keep you from being filtered by carriers' security algorithms or flagged as spam. With stir_verstat in the API, you can now measure it instead of guessing.

For the osky.dj audience in Mexico, the asterisk bears repeating: this applies to calls that go through the US network (or France). If your operation is local, the field is mostly useful for understanding how your calls look when they cross the border.

Sources

• Twilio Changelog: Voice API Call resource now returns STIR/SHAKEN status
• Twilio Docs: Call resource
• Twilio Docs: Trusted calling with SHAKEN/STIR
• Twilio Docs: SHAKEN/STIR Onboarding