Submit a toll-free verification for review

Sends a draft, or a rejected form you fixed, to our team: it comes back in_review.

POST/v1/toll-free-verifications/{id}/submit

Path Parameters

idstringrequired
Example: tfv_a1B2c3D4e5F6.

Body Parameters

The body is optional.

attestationBusinessAttestation
Signed by someone authorized to act for the business, once per business: that they are authorized, that the details match the business's IRS records, and that the business will text only people who agreed to it and will follow the Messaging Policy. Kept as signed, with the exact wording, who sent it (the API key), the IP address, the user agent and the date of our legal documents.

Details

A person on our team checks every form by hand, usually within a business day, then sends it to the carriers (status submitted; usually days, sometimes weeks). Nothing goes to the carriers straight from this call.

The first submit for a business also carries the signed business attestation; without one on file it answers 400 attestation_required (param attestation). Later forms for the same business details need none.

While anything the carriers require is missing it answers 409 invalid_state with problems. Toll-free verification has no fee.

Responses

200TollFreeVerification
Toll-free verification, status in_review
400Error
invalid_request: a missing business detail or attestation field; attestation_required: the business has no signature on file for these details
401Error
Missing, malformed, or revoked API key
402Error
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
404Error
Not found
409Error
invalid_state: already in review or further along, or not complete (problems lists every missing answer)
429Error
Rate limit or quota exceeded

Response Fields

idstring
Example: tfv_a1B2c3D4e5F6.
objecttoll_free_verification
statusdraft, in_review, submitted, verified, rejected
draft: not submitted. in_review: our team is checking it by hand; nothing has gone to the carriers yet. submitted: we sent it to the carriers; waiting on their answer. verified: its numbers text anyone who opted in. rejected: sent back; rejection.reason says why.
numbersarray of string
business_namestring
readyboolean
Nothing the carriers require is missing (problems is empty).
problemsarray of object
What the carriers would send it back for, one entry per answer to fix.
problems[].fieldstring
Example: ein.
problems[].messagestring
editableboolean
Whether PATCH may change it now (draft, in_review and rejected).
next_actoryou, textkit, carriers, nobody
Who acts next.
formTollFreeVerificationInput
The form as it stands, every field. contact_email is always our support address: the carriers write to us, and we forward what only you can answer.
businessobject
The business on the form, as business verification sees it. Nullable.
business.statusnot_started, pending, verified, rejected
business.attestation_neededboolean
Submit needs an attestation for these business details.
business.signedobject
Nullable.
business.signed.signer_namestring
business.signed.signer_titlestring
business.signed.signed_atstring (date-time)
business.rejectionobject
Nullable.
business.rejection.codestring
business.rejection.notestring
Nullable.
rejectionobject
Set while rejected: what the carriers or our team asked for. Nullable.
rejection.reasonstring
rejection.rejected_atstring (date-time)
carrier_referencestring
The carriers' case number, once they give one. Nullable.
registration_idstring
The registration it was filled in from, if any. Nullable.
historyarray of object
history[].atstring (date-time)
history[].statusdraft, in_review, submitted, verified, rejected
history[].actorcustomer, staff, system, carrier
history[].notestring
Nullable.
created_atstring (date-time)
updated_atstring (date-time)

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

400
invalid_request: a missing business detail or attestation field; attestation_required: the business has no signature on file for these details
401
Missing, malformed, or revoked API key
402
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
404
Not found
409
invalid_state: already in review or further along, or not complete (problems lists every missing answer)
429
Rate limit or quota exceeded

const res = await fetch('https://api.jointextkit.com/v1/toll-free-verifications/tfv_a1B2c3D4e5F6/submit', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TEXTKIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});

if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

Response 200

{
  "id": "tfv_a1B2c3D4e5F6",
  "object": "toll_free_verification",
  "status": "draft",
  "numbers": [
    "+18335550100"
  ],
  "next_actor": "you"
}