Docs
Phone numbers

Submit a business verification

POSThttps://api.norreach.app/v1/number-verifications

Sends the workspace's business details and documents for a country and number type for review, exactly as the Phone numbers page does: the requirements are read again on the server, every field is checked, one submission per country and type runs at a time (409 while one is running or approved), the documents go straight to review and only their names are kept. Answer each field by its id from GET /number-verifications/requirements: values for text, addresses for addresses, documents (base64, PDF / JPG / PNG — all together at most about 3 MB through the API; larger scans go through the app). dry_run=true checks everything and sends nothing. Owners, admins and managers.

⚠ numbers:verifyRole must allow: numbers.verifyIdempotency-Key requiredSupports dry_runOperation id: submit_number_verification
POST/number-verifications
curl -X POST "https://api.norreach.app/v1/number-verifications" \
  -H "Authorization: Bearer $NORREACH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "country": "SE",
  "number_type": "local",
  "values": {
    "req-company-number": "556677-8899"
  },
  "addresses": {
    "req-address": {
      "business_name": "Example Care AB",
      "first_name": "Anna",
      "last_name": "Berg",
      "street_address": "Storgatan 1",
      "locality": "Stockholm",
      "postal_code": "11122",
      "country_code": "SE"
    }
  },
  "documents": {
    "req-proof": {
      "file_name": "utility-bill.pdf",
      "content_type": "application/pdf",
      "data_base64": "JVBERi0xLjcK…"
    }
  }
}'
Submit a business verification
{
  "object": "number_verification_submission",
  "dry_run": false,
  "verification": {
    "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
    "object": "number_verification",
    "country": "SE",
    "number_type": "local",
    "status": "submitted",
    "decline_reason": null,
    "submitted_at": "2026-11-05T09:00:00.000Z",
    "decided_at": null,
    "checked_at": "2026-11-05T09:00:00.000Z",
    "created_at": "2026-11-05T08:59:58.000Z",
    "fields": [
      {
        "label": "Company registration number",
        "kind": "text"
      },
      {
        "label": "Address matching the DID area code",
        "kind": "address"
      },
      {
        "label": "Proof of address",
        "kind": "document"
      }
    ],
    "documents": [
      {
        "label": "Proof of address",
        "file_name": "utility-bill.pdf",
        "size": 182311,
        "content_type": "application/pdf"
      }
    ]
  },
  "note": "Sent for review. The decision usually takes a few working days — follow it with GET /number-verifications."
}

Authorizations

Authorizationstringheaderrequired

Bearer authentication: send Authorization: Bearer <key>, with an API key or an OAuth access token. The key needs the scope numbers:verify. API keys and scopes

Query parameters

dry_runbooleanquery

Run every check and return what would happen, changing nothing.

Headers

Idempotency-Keystringheaderrequired

Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.

Body

application/json

countrystringrequired

ISO 3166-1 alpha-2.

number_typeenumrequired
One of:localmobiletoll_freenationalshared_cost
valuesobject

Text answers by field id.

addressesobject

Addresses by field id.

confirm_addressesstring[]

Field ids of addresses to send as entered after the address check suggested a change.

documentsobject

Documents by field id (PDF, JPG or PNG). All files together at most about 3 MB through the API — larger scans go through the app.

Response

201application/json— Submit a business verification

object"number_verification_submission"required
dry_runbooleanrequired
verificationobject | nullrequired
notestringrequired

Errors

Errors are application/problem+json with a stable code.

StatusCodeMeaning
400bad_requestThe request couldn't be read.
400unknown_fieldThe request has a field this operation doesn't know.
400idempotency_key_requiredThis operation needs an Idempotency-Key header.
401unauthorizedA valid API key is required.
403insufficient_scopeThis API key doesn't have the scope this operation needs.
403feature_not_enabledThe API isn't switched on for this workspace.
403role_forbiddenThe key's creator's role can't do this.
409idempotency_in_progressA request with this Idempotency-Key is still running.
409conflictThat conflicts with the current state.
413too_largeThe request body is too large.
422validation_failedThe request has invalid fields.
422idempotency_mismatchThis Idempotency-Key was used with a different request.
429rate_limitedToo many requests. Slow down and try again.
500server_errorSomething went wrong on our side.
503unavailableThe API isn't available right now. Try again shortly.