ResourcesVerifications

Verifications

Create, manage, and submit regulatory compliance filings for phone numbers through the Talkturo API — handle Twilio regulatory bundle creation, document uploads, and live verification status checks.

curl -X POST "https://app.talkturo.com/api/verifications/filings" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k" \
  -d '{
    "account": "acme-voice",
    "country": "US",
    "numberType": "local",
    "carrier": "twilio"
  }'
{
  "success": true,
  "bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
  "resumed": false
}
curl "https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2" \
  -H "Cookie: sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
{
  "success": true,
  "filing": {
    "bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
    "account": "acme-voice",
    "carrier": "twilio",
    "country": "US",
    "numberType": "local",
    "status": "draft"
  }
}
curl -X PUT "https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2" \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k" \
  -d '{
    "businessName": "Acme Voice LLC",
    "contactEmail": "ops@acmevoice.com",
    "contactPhone": "+14155550123",
    "addressLine1": "548 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94104"
  }'
{
  "success": true,
  "bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
  "status": "draft"
}
curl -X POST "https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2/submit" \
  -H "Cookie: sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
{
  "success": true,
  "bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
  "status": "pending-review"
}
curl "https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2/documents" \
  -H "Cookie: sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
{
  "success": true,
  "documents": [
    {
      "id": "RD0f74e517ef5c4bb7b6d0f83ab438b8d1",
      "name": "certificate-of-incorporation.pdf",
      "type": "business_registration",
      "status": "accepted"
    }
  ]
}
curl -X POST "https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2/documents" \
  -H "Cookie: sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k" \
  -F "documentType=business_registration" \
  -F "file=@certificate-of-incorporation.pdf"
{
  "success": true,
  "document": {
    "id": "RD0f74e517ef5c4bb7b6d0f83ab438b8d1",
    "name": "certificate-of-incorporation.pdf",
    "type": "business_registration",
    "status": "uploaded"
  }
}
curl "https://app.talkturo.com/api/verifications/live" \
  -H "Cookie: sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
{
  "success": true,
  "verifications": [
    {
      "bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
      "country": "US",
      "numberType": "local",
      "status": "pending-review"
    }
  ]
}

Endpoint summary

MethodPathPurposeAuth
POST/api/verifications/filingsCreate a new filing, resume an existing draft, or reopen a rejected filing for resubmissionSession cookie
GET/api/verifications/filings/{bundleSid}Retrieve filing details for a regulatory bundleSession cookie
PUT/api/verifications/filings/{bundleSid}Update filing data before submissionSession cookie
POST/api/verifications/filings/{bundleSid}/submitSubmit a filing for carrier review and approvalSession cookie
GET/api/verifications/filings/{bundleSid}/documentsList documents attached to a filingSession cookie
POST/api/verifications/filings/{bundleSid}/documentsUpload a document to a filingSession cookie
GET/api/verifications/liveCheck live verification status across current filingsSession cookie

All Verifications endpoints require an authenticated Talkturo session cookie. These routes use server-side session auth rather than API keys, so requests from backend integrations must act on behalf of a signed-in workspace user.

Create or resume a filing

Create a regulatory filing for a phone number compliance workflow, or resume the active draft that already matches the same country and number type.

Body parameters

body
accountstring
Required

Workspace slug that owns the filing.

body
carrierstring

Carrier identifier for the filing workflow. If omitted, Talkturo uses the default carrier flow for the workspace.

body
countrystring
Required

Two-character ISO country code for the filing, such as US or CA.

body
numberTypestring

Phone number category for the filing. Defaults to local.

Allowed values:localtoll-freemobilenational
body
resubmitOfstring

Existing Twilio bundle SID to reopen as the basis for a new draft after rejection.

Response fields

successboolean
Required

Indicates whether the filing was created or resumed successfully.

bundleSidstring
Required

Twilio regulatory bundle SID for the filing.

resumedboolean
Required

Returns true when Talkturo found and reused an existing matching draft instead of creating a new bundle.

Behavior

Without resubmitOf, Talkturo checks for an existing draft bundle with the same country and numberType. If a matching draft exists, the endpoint returns that bundle and sets resumed to true.

If you pass resubmitOf, Talkturo reopens the rejected bundle workflow and creates a fresh draft for fix-and-resubmit. Use this path when carrier review failed and you need to correct documents or filing details before sending a new submission.

A filing is tied to a workspace and regulatory context. Reusing the wrong account, country, or numberType can resume a draft you did not intend to modify.

Error responses

StatusMeaning
400Missing or invalid request body values
401No authenticated session
403Authenticated user does not have access to the workspace
404Workspace or filing context was not found
502Upstream carrier or regulatory bundle provider error

Get filing details

Retrieve the current state of a filing, including the bundle identifier and provider-backed verification details.

Path parameters

path
bundleSidstring
Required

Twilio bundle SID that identifies the filing.

Response fields

successboolean
Required

Indicates whether the filing was retrieved successfully.

filingobject
Required

Filing details returned for the requested bundle.

filing.bundleSidstring
Required

Twilio bundle SID for the filing.

filing.accountstring
Required

Workspace slug associated with the filing.

filing.carrierstring

Carrier associated with the filing workflow.

filing.countrystring
Required

Two-character ISO country code for the filing.

filing.numberTypestring
Required

Number type for the filing.

filing.statusstring
Required

Current provider or workflow status for the filing, such as draft, pending-review, approved, or rejected.

Update a filing

Update filing data before submission. Use this endpoint to save applicant information, business details, addresses, and any other regulatory fields required by the active bundle workflow.

Path parameters

path
bundleSidstring
Required

Twilio bundle SID for the filing you want to update.

Body parameters

body
businessNamestring

Legal business name or organization name used in the filing.

body
contactEmailstring

Primary contact email for the filing.

body
contactPhonestring

Primary contact phone number in E.164 format.

body
addressLine1string

Street address line 1 for the business or applicant.

body
citystring

City for the filing address.

body
statestring

State or region for the filing address.

body
postalCodestring

Postal or ZIP code for the filing address.

Response fields

successboolean
Required

Indicates whether the filing update succeeded.

bundleSidstring
Required

Twilio bundle SID for the updated filing.

statusstring
Required

Current filing status after the update.

Update the filing before calling the submit endpoint. Once provider review starts, some fields may require a rejection and resubmission cycle instead of an in-place edit.

Submit a filing

Submit a completed filing for approval after all required fields and documents are in place.

Path parameters

path
bundleSidstring
Required

Twilio bundle SID for the filing to submit.

Response fields

successboolean
Required

Indicates whether the submission request succeeded.

bundleSidstring
Required

Twilio bundle SID that was submitted.

statusstring
Required

Submission status after the provider accepted the filing for review.

List documents

List the documents currently attached to a filing so you can confirm which requirements are already satisfied.

Path parameters

path
bundleSidstring
Required

Twilio bundle SID for the filing whose documents you want to inspect.

Response fields

successboolean
Required

Indicates whether the document list was retrieved successfully.

documentsarray
Required

Documents currently attached to the filing.

documents[].idstring
Required

Provider document identifier.

documents[].namestring
Required

Original filename for the uploaded document.

documents[].typestring

Document classification used by the verification workflow.

documents[].statusstring

Current provider status for the uploaded document.

Upload a document

Upload a supporting document to a filing before submission. The document type and file contents must match the regulatory requirements for the selected country and number type.

Path parameters

path
bundleSidstring
Required

Twilio bundle SID for the filing that will receive the document.

Body parameters

body
documentTypestring
Required

Classification for the uploaded document, such as business_registration, proof_of_address, or another requirement defined by the active filing workflow.

body
filefile
Required

Binary file upload sent as multipart form data.

Response fields

successboolean
Required

Indicates whether the upload succeeded.

documentobject
Required

Uploaded document metadata.

document.idstring
Required

Provider document identifier.

document.namestring
Required

Filename recorded for the uploaded document.

document.typestring
Required

Document classification associated with the upload.

document.statusstring
Required

Current status for the uploaded document after Talkturo stores and forwards it.

Carrier review can reject a filing even when the upload succeeds. Validate document legibility, match the document type correctly, and ensure the document belongs to the same legal entity named in the filing.

Check live verification status

Fetch the current live verification status for the authenticated workspace. Use this endpoint to power dashboards, polling jobs, or operational checks after submission.

Response fields

successboolean
Required

Indicates whether the live status query succeeded.

verificationsarray
Required

Current verification records visible to the authenticated workspace.

verifications[].bundleSidstring
Required

Twilio bundle SID for the verification.

verifications[].countrystring
Required

Two-character ISO country code for the verification.

verifications[].numberTypestring
Required

Number type associated with the verification.

verifications[].statusstring
Required

Latest live status reported for the verification.