Skip to main content

​
Overview

If a third party believes your DIR’s display name, logo, or content infringes on a protected right (trademark, copyright, etc.), they can file an infringement claim through Telnyx. Claims are filed and adjudicated by Telnyx, you cannot create a claim through this API, but you can read and contest claims filed against your own DIRs. While a claim is pending or contested:
  • The DIR is moved to suspended.
  • Branded calling pauses for the affected DIR.
  • You cannot add phone numbers to the DIR (returns 400).
  • You cannot delete the DIR (returns 409, blocked by the no_active_claims precondition).
  • You cannot re-submit the DIR with POST /submit (returns 409 with the open claim IDs, blocked by the no_active_claims precondition).
  • To revise content while the claim is open, call PUT /v2/dir/{dir_id}/infringement_update on the suspended DIR (see “Fix-and-resubmit” below). This is the only way to re-vet during an open claim.

​
Claim lifecycle

pending ──► contested  (you submit a contest)
        ──► resolved   (Telnyx admin adjudicates)

resolved.resolution = upheld   ──► your DIR moves to permanently_rejected (terminal); the live registration and phone-number registrations are torn down. The DIR cannot be recovered, create a new DIR with corrected content.
resolved.resolution = rejected ──► claim is dismissed; if your DIR was suspended for the claim, it is restored to verified and branded calling resumes.
resolved.resolution = modified ──► partial outcome; DIR status is unchanged by the resolve, see resolution_notes for required follow-up.

​
API endpoints

MethodPathDescription
GET/v2/dir/{dir_id}/infringement_claimsList claims against a DIR
GET/v2/infringement_claims/{claim_id}Get a single claim
POST/v2/infringement_claims/{claim_id}/contestFile a contest

​
Listing claims on a DIR

curl -g "https://api.telnyx.com/v2/dir/{dir_id}/infringement_claims?page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Getting a single claim

curl https://api.telnyx.com/v2/infringement_claims/{claim_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Contesting a claim

You can submit a contest more than once, the first submission moves the claim from pending to contested; later submissions append additional notes and documents to the same claim without changing status. 
curl -X POST https://api.telnyx.com/v2/infringement_claims/{claim_id}/contest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contest_notes": "Acme Plumbing LLC has been operating under this name since 2008, predating the cited trademark filing. Attached: trademark search results and our state business registration.",
    "documents": [
      {
        "document_id": "d1e2f3a4-573d-446d-b3ce-aff9117272a6",
        "document_type": "trademark_registration",
        "description": "Our 2008 state trademark registration."
      }
    ]
  }'
FieldRequiredDescription
contest_notesyes10-2000 characters. Explain why the claim is invalid or how you’ve addressed it.
documentsnoUp to 20 supporting documents per submission. Each must reference a document_id from the Telnyx Documents API and include a document_type. Duplicate document_ids within one submission are rejected.
Contesting a resolved claim returns 400.

​
Fix-and-resubmit a suspended DIR

While an infringement claim is open (pending or contested), Telnyx may pre-emptively move your DIR to suspended to halt branded calling. To recover without waiting for the claim to be resolved, use the dedicated PUT /v2/dir/{dir_id}/infringement_update endpoint to atomically apply your content fix and re-submit for vetting in one call. This endpoint requires an active (unresolved) claim and a suspended DIR (see “After the claim resolves” below). 
curl -X PUT https://api.telnyx.com/v2/dir/{dir_id}/infringement_update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Acme Local Plumbing",
    "logo_url": "https://acmeplumbing.example.com/logo-v2-256.bmp",
    "certify_no_infringement": true,
    "certify_brand_is_accurate": true,
    "certify_no_shaft_content": true,
    "certify_ip_ownership": true,
    "infringement_resolution_notes": "Renamed to Acme Local Plumbing and replaced the logo so the new display identity no longer reads on the cited trademark."
  }'
Requirements:
  • The DIR must have an active (unresolved) infringement claim.
  • The DIR must be in suspended status.
  • All four certifications (certify_no_infringement, certify_brand_is_accurate, certify_no_shaft_content, certify_ip_ownership) must be supplied as true.
  • infringement_resolution_notes is required (10-500 chars), explain how the edits resolve the claim.
The content fields (display_name, logo_url, call_reasons) are all optional; send only the ones you’re changing. See the Infringement Claims guide for the full field table. After the update, the DIR moves to submitted and goes through vetting again, even though the claim is still open. If the new content passes vetting, the DIR returns to verified and the claim can be resolved. If vetting rejects the changes, the DIR returns to suspended and you can update again. You can submit infringement_update multiple times while the claim is open.
Why the standard PATCH + POST /submit flow doesn’t work here: POST /submit is gated by the FSM’s no_active_claims precondition and returns 409 while a claim is still pending or contested. PUT /infringement_update is the only customer-callable endpoint that can move a suspended-with-open-claim DIR back into vetting; it bypasses the no_active_claims gate by design. Use PATCH + POST /submit only after Telnyx has marked the claim resolved with resolution = modified. resolution = rejected auto-restores the DIR and resolution = upheld is terminal, neither requires a customer PATCH + /submit.

​
After the claim resolves

  • resolution = rejected: your DIR is automatically restored to verified; no action required. Branded calling resumes.
  • resolution = upheld: your DIR is permanently_rejected and cannot be reused. To continue branded calling, create a new DIR with corrected content; you may reuse the same enterprise.
  • resolution = modified: read resolution_notes for the required content edits, then PATCH the DIR and POST /submit (the no_active_claims gate is now open because the claim is resolved).