Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Estimate a verification

How many of the target’s contacts were never verified and what verifying them would cost. Changes nothing.

POST/verifications/estimate
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Request body
requiredapplication/json
targetVerificationTargetrequired
Show properties
One of:
object
kindstringrequired
Allowed:contacts
contact_idsstring<uuid>[]required

Contacts of the team, by id

min items 1 · max items 50000
object
kindstringrequired
Allowed:segment
segment_idstring<uuid>required

Every contact in this segment

object
kindstringrequired
Allowed:broadcast
broadcast_idstring<uuid>required

The broadcast's audience: the contacts it would mail, leaving out everyone who unsubscribed

Responses
200

The counts and the estimated cost

objectstringrequired
Allowed:verification_estimate
totalintegerrequired

Contacts the target names

unverifiedintegerrequired

Of them, never verified: what a start would verify (verified ones are skipped)

in_runintegerrequired

Of the unverified, already being verified

grant_remainingintegerrequired

Free verification credit left this quota month, which a run uses first

estimated_centsintegerrequired

What verifying the unverified would cost past the credit, in cents

401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
404

The segment or broadcast is not one of the team's

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

Over the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://api.billionsend.com/verifications/estimate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "target": {
    "kind": "contacts",
    "contact_ids": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  }
}'
Response
{
  "object": "verification_estimate",
  "total": 0,
  "unverified": 0,
  "in_run": 0,
  "grant_remaining": 0,
  "estimated_cents": 0
}

Was this page helpful?