Skip to main content

​
KYC Submissions & Documents: Troubleshooting

KYC work in Orbit happens in three stages, and each one fails differently: the organization KYC form (who you are, reviewed by the Orbit ops team), the document library (the files carriers and regulators want, uploaded at Settings → Compliance → Documents), and the carrier-facing profile (the structured identity a carrier approves for a country and use case). This page maps the symptoms you actually see to the stage that emits them, and to the first check that resolves them. For the conceptual model see KYC Identity Model; for the happy-path walkthrough see KYC Profile Submission Runbook and KYC Documents & the Compliance-Profile Lifecycle.

​
Symptom → stage map

Scan this table first, then jump to the matching section.

​
Upload rejected: type or size

POST /compliance/documents accepts JPEG, PNG, WebP, and PDF, up to 10 MB, and only the eleven document types listed in KYC Documents (id_card, passport, business_registration, and so on). A 422 on upload is almost always one of:
  • A HEIC or scanned-TIFF export renamed to .jpg. Re-export the scan as JPEG or PDF before uploading; the validator reads the file, not the extension.
  • A PDF export above 10 MB. Print-to-PDF at a lower resolution or split the document; the cap is per file.
  • A document type that doesn’t match the file’s content. A VAT certificate uploaded as business_registration is refused by the carrier later, even when the upload itself goes through, so pick the type the document actually is.
The upload returns the doc_… library ID every profile and registration references, so fix the file before it enters the library rather than detaching and re-uploading afterwards.

​
401 ORG_KYC_REQUIRED on send

Two different gates produce “the send failed for a compliance reason,” and they are owned by different stages:
  • The organization gate: your org’s KYC submission is missing, in review, or rejected. This is the form at POST /organization/kyc/submit, reviewed by the Orbit ops team.
  • The per-number Documents-KYC review: the org is approved, but the specific number or Sender ID lacks an approved compliance profile for its country. This is the surface described in KYC Documents.
One call tells you which surface owns the block:
If the status is approved, stop looking at the org form: no amount of re-submitting it changes a per-number result, and the number-side fix is a profile and its documents, not your company details.

​
Profile stuck on pending_review

Org KYC submissions are reviewed by a human, in submission order, against a one-business-day SLA from submitted_at. The same endpoint as above is your queue view:
It returns status: "pending_review" together with submitted_at, the timestamp your current submission entered the queue. Compare submitted_at against the SLA: inside one business day, the submission is simply in line; past it with no reviewed_at, contact support with the request_id rather than submitting again.
Do not resubmit to “nudge” the review. A new POST /organization/kyc/submit overwrites your queued submission and stamps a fresh submitted_at, which puts you back at the end of the review queue. The only safe action while pending_review is to wait, or to contact support once the SLA has passed. (After approval, a resubmit is refused outright with 409 ALREADY_VERIFIED.)
A pending_review you never caused is usually the automatic stamp placed when your account’s email was verified, before any form was submitted. The status response marks that case with a source field; it clears the moment you submit the real form, which replaces the stamp with your company details.

​
Carrier rejected: additional docs required

A Sender-ID registration that comes back “rejected — additional docs required” means the carrier reviewed the registration’s document_refs and wants a specific one supplemented or refreshed. The registration never holds files itself, only doc_… IDs, so the failing document is always in your library:
  1. Open Settings → Compliance → Documents and locate the doc_… ID the registration references for that country.
  2. Re-upload the refreshed or corrected file against that same doc_… entry so every profile and registration that references the ID keeps pointing at the current file. Correct the thing the carrier named: wrong document type, unreadable scan, or an address that no longer matches the registered business name.
  3. Confirm the document’s role (id_proof, address_proof, business_doc, authorization, other) matches the requirement the carrier flagged, then watch the registration status move back through review.
The doc_… ID is the single pointer shared by every profile and registration in your organization. That is why the fix is to refresh the document behind the ID, not to delete and recreate it: a deleted ID leaves dangling references on every profile that used it, and deletion is refused while any profile still attaches the document.
If the carrier wants a document you have never uploaded (a power of attorney for a third-party signatory, say), upload it once as a new doc_… entry and attach it in the role the carrier asked for, per KYC Documents.

​
10DLC brand rejection that is really KYC

A US 10DLC brand rejection is a verdict on your business identity, so a share of brand rejections are KYC/KYB misses wearing a brand-error costume. Two tells:
  • EIN / registration-number mismatch. The registration_number and company_name on your KYC submission must match what the EIN lookup returns, character for character. “Acme GmbH” submitted while the registration says “ACME GMBH” fails the brand vet the same way it fails a bank’s check. Fix the org details and resubmit the KYC form (resubmission is open while your status is rejected), then re-file the brand.
  • Sanctioned-party screen. The denied-parties screen runs against your legal name and declared beneficial owners at KYC submit. A match puts the org into manual review, and the brand follows the org. This is not something you fix by editing campaign text; contact support with your request_id.
A campaign rejection, by contrast, is about the message body and sample traffic: opt-in language, use-case mismatch, forbidden content. If the brand is approved and only the campaign is rejected, the KYC side is fine. Decode the carrier verdict codes in 10DLC Rejections & Revet, and see 10DLC Brand & Campaign Profiles for the brand/campaign split.

​
Renewal and expiry

Documents age out. Orbit stores an expires_at per attached document, and once a document lapses it stops counting toward the country’s requirements, even though the file is still in your library. The visible symptom is that numbers which used to send fine start failing preflight: the regulatory preview flips compliance_profile_satisfies to false, and a number waiting on that profile can sit at pending_compliance or be auto-released if the carrier’s verify-by deadline passes. See Number Lifecycle for the release side. Find what is expiring before or after the fact with the expiry feed:
Each alert names the number, the soonest binding expiry, and a suggested_action of renew (inside your alert window) or renew_or_release (already lapsed). The recovery path is the renewal flow from KYC Documents:
  1. Upload the current replacement document.
  2. Attach it to the affected profile in the same role as the one expiring.
  3. Detach the expired document (and delete it only after detaching).
Approved profiles stay approved while you swap; the submission is re-reviewed on next use, and preflight passes again once the attached documents are current. The expiry banner on the Numbers page reads the same feed, so console operators see the same renew prompts without curl.

​
See also