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"
}'
const response = await fetch("https://app.talkturo.com/api/verifications/filings", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Cookie": "sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
},
body: JSON.stringify({
account: "acme-voice",
country: "US",
numberType: "local",
carrier: "twilio"
})
});
const data = await response.json();
console.log(data);
{
"success": true,
"bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
"resumed": false
}
{
"error": "country is required"
}
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"
const response = await fetch(
"https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
{
headers: {
"Cookie": "sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
}
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"filing": {
"bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
"account": "acme-voice",
"carrier": "twilio",
"country": "US",
"numberType": "local",
"status": "draft"
}
}
{
"error": "filing not found"
}
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"
}'
const response = await fetch(
"https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
{
method: "PUT",
headers: {
"Content-Type": "application/json",
"Cookie": "sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
},
body: JSON.stringify({
businessName: "Acme Voice LLC",
contactEmail: "ops@acmevoice.com",
contactPhone: "+14155550123",
addressLine1: "548 Market Street",
city: "San Francisco",
state: "CA",
postalCode: "94104"
})
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
"status": "draft"
}
{
"error": "invalid filing payload"
}
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"
const response = await fetch(
"https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2/submit",
{
method: "POST",
headers: {
"Cookie": "sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
}
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
"status": "pending-review"
}
{
"error": "missing required documents"
}
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"
const response = await fetch(
"https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2/documents",
{
headers: {
"Cookie": "sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
}
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"documents": [
{
"id": "RD0f74e517ef5c4bb7b6d0f83ab438b8d1",
"name": "certificate-of-incorporation.pdf",
"type": "business_registration",
"status": "accepted"
}
]
}
{
"error": "filing not found"
}
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"
const formData = new FormData();
formData.append("documentType", "business_registration");
formData.append(
"file",
new File(
["PDF-1.4 regulatory document bytes"],
"certificate-of-incorporation.pdf",
{ type: "application/pdf" }
)
);
const response = await fetch(
"https://app.talkturo.com/api/verifications/filings/BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2/documents",
{
method: "POST",
headers: {
"Cookie": "sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
},
body: formData
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"document": {
"id": "RD0f74e517ef5c4bb7b6d0f83ab438b8d1",
"name": "certificate-of-incorporation.pdf",
"type": "business_registration",
"status": "uploaded"
}
}
{
"error": "file is required"
}
curl "https://app.talkturo.com/api/verifications/live" \
-H "Cookie: sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
const response = await fetch("https://app.talkturo.com/api/verifications/live", {
headers: {
"Cookie": "sb-access-token=sb_session_example_8df31f; sb-refresh-token=sb_refresh_example_6ad92k"
}
});
const data = await response.json();
console.log(data);
{
"success": true,
"verifications": [
{
"bundleSid": "BU7c9d2d9d6e5a4b1f8b7c3a2d4e9f1a2",
"country": "US",
"numberType": "local",
"status": "pending-review"
}
]
}
{
"error": "not authenticated"
}
Endpoint summary
| Method | Path | Purpose | Auth |
|---|---|---|---|
POST | /api/verifications/filings | Create a new filing, resume an existing draft, or reopen a rejected filing for resubmission | Session cookie |
GET | /api/verifications/filings/{bundleSid} | Retrieve filing details for a regulatory bundle | Session cookie |
PUT | /api/verifications/filings/{bundleSid} | Update filing data before submission | Session cookie |
POST | /api/verifications/filings/{bundleSid}/submit | Submit a filing for carrier review and approval | Session cookie |
GET | /api/verifications/filings/{bundleSid}/documents | List documents attached to a filing | Session cookie |
POST | /api/verifications/filings/{bundleSid}/documents | Upload a document to a filing | Session cookie |
GET | /api/verifications/live | Check live verification status across current filings | Session 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
Workspace slug that owns the filing.
Carrier identifier for the filing workflow. If omitted, Talkturo uses the default carrier flow for the workspace.
Two-character ISO country code for the filing, such as US or CA.
Phone number category for the filing. Defaults to local.
localtoll-freemobilenationalExisting Twilio bundle SID to reopen as the basis for a new draft after rejection.
Response fields
Indicates whether the filing was created or resumed successfully.
Twilio regulatory bundle SID for the filing.
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
| Status | Meaning |
|---|---|
400 | Missing or invalid request body values |
401 | No authenticated session |
403 | Authenticated user does not have access to the workspace |
404 | Workspace or filing context was not found |
502 | Upstream 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
Twilio bundle SID that identifies the filing.
Response fields
Indicates whether the filing was retrieved successfully.
Filing details returned for the requested bundle.
Twilio bundle SID for the filing.
Workspace slug associated with the filing.
Carrier associated with the filing workflow.
Two-character ISO country code for the filing.
Number type for the filing.
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
Twilio bundle SID for the filing you want to update.
Body parameters
Legal business name or organization name used in the filing.
Primary contact email for the filing.
Primary contact phone number in E.164 format.
Street address line 1 for the business or applicant.
City for the filing address.
State or region for the filing address.
Postal or ZIP code for the filing address.
Response fields
Indicates whether the filing update succeeded.
Twilio bundle SID for the updated filing.
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
Twilio bundle SID for the filing to submit.
Response fields
Indicates whether the submission request succeeded.
Twilio bundle SID that was submitted.
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
Twilio bundle SID for the filing whose documents you want to inspect.
Response fields
Indicates whether the document list was retrieved successfully.
Documents currently attached to the filing.
Provider document identifier.
Original filename for the uploaded document.
Document classification used by the verification workflow.
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
Twilio bundle SID for the filing that will receive the document.
Body parameters
Classification for the uploaded document, such as business_registration, proof_of_address, or another requirement defined by the active filing workflow.
Binary file upload sent as multipart form data.
Response fields
Indicates whether the upload succeeded.
Uploaded document metadata.
Provider document identifier.
Filename recorded for the uploaded document.
Document classification associated with the upload.
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
Indicates whether the live status query succeeded.
Current verification records visible to the authenticated workspace.
Twilio bundle SID for the verification.
Two-character ISO country code for the verification.
Number type associated with the verification.
Latest live status reported for the verification.