> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC Submissions & Documents: Troubleshooting

> Fix the failures operators actually hit across the KYC flow: rejected uploads, sends refused on verification, profiles stuck in review, carrier document requests, 10DLC brand rejections, and documents that age out.

# 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](/compliance/kyc-identity-model); for the happy-path
walkthrough see
[KYC Profile Submission Runbook](/compliance/kyc-profile-submission-runbook)
and
[KYC Documents & the Compliance-Profile Lifecycle](/compliance/documents-kyc).

***

## Symptom → stage map

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

| Symptom | Stage that emits it | Start here |
| - | - | - |
| Upload refused: unsupported file type or file over 10 MB | Document upload | [Upload rejected](#upload-rejected-type-or-size) |
| Send refused with `401` `ORG_KYC_REQUIRED` | Organization KYC form, or per-number review | [Which surface owns the block](#401-org_kyc_required-on-send) |
| Profile sitting on `pending_review` longer than expected | Carrier-facing profile (ops review) | [Stuck on pending\_review](#profile-stuck-on-pending_review) |
| Carrier says "rejected — additional docs required" on a Sender-ID registration | Carrier-facing profile (document refs) | [Additional docs required](#carrier-rejected-additional-docs-required) |
| 10DLC brand rejected and you're not sure why | Organization KYC/KYB data, or campaign body | [Brand rejection vs KYC](#10dlc-brand-rejection-that-is-really-kyc) |
| Previously approved number suddenly fails preflight | Document renewal / expiry | [Renewal and expiry](#renewal-and-expiry) |

### 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](/compliance/documents-kyc) (`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](/compliance/documents-kyc).

One call tells you which surface owns the block:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/organization/kyc/status" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

| `status` in the response | The block is | Fix |
| - | - | - |
| `not_started` | Org gate | Submit the KYC form; sending unlocks after approval. |
| `pending_review` | Org gate | Wait for the review ([below](#profile-stuck-on-pending_review)); do not resubmit. |
| `rejected` | Org gate | Correct the flagged fields and submit again. |
| `approved` | Per-number review | The org is fine; the failing number needs a satisfying profile. Check [regulatory preview](/numbers/regulatory-preview) for that number and see [additional docs required](#carrier-rejected-additional-docs-required) or [renewal and expiry](#renewal-and-expiry). |

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:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/organization/kyc/status" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

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.

<Warning>
  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`.)
</Warning>

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.

<Note>
  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.
</Note>

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](/compliance/documents-kyc).

***

## 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](/guides/10dlc-rejections-and-revet), and see
[10DLC Brand & Campaign Profiles](/compliance/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](/numbers/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](/numbers/lifecycle) for the release side.

Find what is expiring before or after the fact with the expiry feed:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/numbers/document-expiry-alerts" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

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](/compliance/documents-kyc):

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

* [KYC Profile Submission Runbook](/compliance/kyc-profile-submission-runbook) —
  the submit-to-approval walkthrough this page troubleshoots.
* [KYC Documents & the Compliance-Profile Lifecycle](/compliance/documents-kyc) —
  the document library, roles, and renewal model.
* [Regulatory Preview](/numbers/regulatory-preview) — see which fields and
  documents a country requires before a purchase or send fails on them.
* [10DLC Rejections & Revet](/guides/10dlc-rejections-and-revet) — the
  carrier verdict-code decoder for US brands and campaigns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.