> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Contest an infringement claim > Submit a written response and supporting documents disputing the claim. The first call moves the claim from `pending` to `contested`; subsequent calls append supplementary evidence without changing status. The `documents[]` you attach are aggregated across rounds in the claim's `contest_documents` field. Only `pending` and `contested` claims accept new evidence. A `resolved` claim returns `400`. Failure modes: - `400` - the claim is `resolved` (terminal); cannot be contested further. - `404` - the claim does not exist or is not against a DIR you own. - `422` - `contest_notes` is too short (< 10 chars), too long (> 2000 chars), `documents` is > 20 entries, or a `document_id` is duplicated within the same submission. ## OpenAPI ````yaml /openapi/source/external/branded-calling/branded-calling.json post /infringement_claims/{claim_id}/contest openapi: 3.0.0 info: x-latency-category: responsive version: 2.0.0 title: Telnyx Branded Calling API description: >- The Telnyx Branded Calling API lets you register your business identity as Display Identity Records (DIRs) and associate phone numbers so your verified caller identity is shown on outbound calls. Flow: create an enterprise → activate Branded Calling → create a DIR → submit it for vetting → after approval, attach phone numbers and submit them in a batch for vetting. Several actions are billable (Branded Calling activation and phone-number registration). See https://telnyx.com/pricing/numbers for current pricing. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 description: Telnyx API v2 (production) security: - bearerAuth: [] tags: - name: Enterprises description: Manage the legal-entity record that owns your DIRs and phone numbers. - name: Display Identity Records description: >- A Display Identity Record (DIR) is the verified calling identity (display name, logo, call reasons) shown to recipients on outbound calls. - name: DIR References description: >- Submit and manage the two business references and one financial reference that vouch for a DIR. References are contacted to confirm the business identity during vetting. - name: Email Verification description: >- Verify ownership of a DIR's authorizer email. A short code is emailed and confirmed; the email must be verified before references can be submitted. - name: Phone Numbers description: >- Associate phone numbers with a verified DIR so calls from those numbers carry the DIR's display identity. - name: Phone Number Batches description: >- Phone numbers are submitted to Telnyx for vetting in batches. Batches group all numbers added in a single request under the same Letter of Authorization. - name: Comments description: >- Read messages from the Telnyx vetting team and reply with clarifying information. - name: Infringement Claims description: >- Trademark or impersonation claims filed against your DIR. Customers may contest a claim with supporting evidence. - name: Reference Data description: >- Static reference values the API accepts: call reasons, document types, rejection types. - name: Terms of Service description: >- Accept and review the Branded Calling and Phone Number Reputation terms of service. paths: /infringement_claims/{claim_id}/contest: post: tags: - Infringement Claims summary: Contest an infringement claim description: >- Submit a written response and supporting documents disputing the claim. The first call moves the claim from `pending` to `contested`; subsequent calls append supplementary evidence without changing status. The `documents[]` you attach are aggregated across rounds in the claim's `contest_documents` field. Only `pending` and `contested` claims accept new evidence. A `resolved` claim returns `400`. Failure modes: - `400` - the claim is `resolved` (terminal); cannot be contested further. - `404` - the claim does not exist or is not against a DIR you own. - `422` - `contest_notes` is too short (< 10 chars), too long (> 2000 chars), `documents` is > 20 entries, or a `document_id` is duplicated within the same submission. operationId: contestInfringementClaim parameters: - name: claim_id in: path description: Unique identifier of the claim. required: true schema: type: string format: uuid example: e379fbc8-cd83-4bef-a280-a0ac9d00dcf8 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InfringementClaimContest' example: contest_notes: >- We own the trademark outright; our registration precedes the claimant by three years. See attached certificate. documents: - document_id: 2a7e8337-e803-4057-a4ae-26c40eb0bc6c document_type: trademark_registration description: USPTO trademark certificate. responses: '200': description: Updated claim, status `contested`. content: application/json: schema: $ref: '#/components/schemas/InfringementClaimWrapped' default: $ref: '#/components/responses/GenericErrorResponse' 4XX: $ref: '#/components/responses/GenericErrorResponse' x-codeSamples: - lang: JavaScript source: >- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); const response = await client.infringementClaims.contest('e379fbc8-cd83-4bef-a280-a0ac9d00dcf8', { contest_notes: 'We own the trademark outright; our registration precedes the claimant by three years. See attached certificate.', documents: [ { document_id: '2a7e8337-e803-4057-a4ae-26c40eb0bc6c', document_type: 'trademark_registration', description: 'USPTO trademark certificate.', }, ], }); console.log(response.data); - lang: Python source: | import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) response = client.infringement_claims.contest( claim_id="e379fbc8-cd83-4bef-a280-a0ac9d00dcf8", contest_notes="We own the trademark outright; our registration precedes the claimant by three years. See attached certificate.", documents=[{ "document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c", "document_type": "trademark_registration", "description": "USPTO trademark certificate.", }], ) print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.InfringementClaims.Contest(\n\t\tcontext.TODO(),\n\t\t\"e379fbc8-cd83-4bef-a280-a0ac9d00dcf8\",\n\t\ttelnyx.InfringementClaimContestParams{\n\t\t\tContestNotes: \"We own the trademark outright; our registration precedes the claimant by three years. See attached certificate.\",\n\t\t\tDocuments: []telnyx.InfringementClaimContestParamsDocument{{\n\t\t\t\tDocumentID: \"2a7e8337-e803-4057-a4ae-26c40eb0bc6c\",\n\t\t\t\tDocumentType: \"trademark_registration\",\n\t\t\t\tDescription: telnyx.String(\"USPTO trademark certificate.\"),\n\t\t\t}},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" - lang: Java source: >- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.infringementclaims.InfringementClaimContestParams; import com.telnyx.sdk.models.infringementclaims.InfringementClaimContestResponse; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); InfringementClaimContestParams params = InfringementClaimContestParams.builder() .claimId("e379fbc8-cd83-4bef-a280-a0ac9d00dcf8") .contestNotes("We own the trademark outright; our registration precedes the claimant by three years. See attached certificate.") .build(); InfringementClaimContestResponse response = client.infringementClaims().contest(params); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") response = telnyx.infringement_claims.contest( "e379fbc8-cd83-4bef-a280-a0ac9d00dcf8", contest_notes: "We own the trademark outright; our registration precedes the claimant by three years. See attached certificate." ) puts(response) - lang: PHP source: >- infringementClaims->contest( 'e379fbc8-cd83-4bef-a280-a0ac9d00dcf8', contestNotes: 'We own the trademark outright; our registration precedes the claimant by three years. See attached certificate.', documents: [ [ 'documentID' => '2a7e8337-e803-4057-a4ae-26c40eb0bc6c', 'documentType' => 'trademark_registration', 'description' => 'USPTO trademark certificate.', ], ], ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx infringement-claims contest \ --api-key 'My API Key' \ --claim-id e379fbc8-cd83-4bef-a280-a0ac9d00dcf8 \ --contest-notes 'We own the trademark outright; our registration precedes the claimant by three years. See attached certificate.' components: schemas: InfringementClaimContest: type: object required: - contest_notes additionalProperties: false properties: contest_notes: type: string minLength: 10 maxLength: 2000 description: Customer's response to the claim. 10–2000 characters. example: >- We own the trademark outright; our registration precedes the claimant by three years. documents: type: array items: $ref: '#/components/schemas/Document' maxItems: 20 description: >- Up to 20 supporting documents per submission. `document_id` must be unique within this submission. Documents are aggregated into the claim's `contest_documents` across all submissions. InfringementClaimWrapped: type: object required: - data properties: data: $ref: '#/components/schemas/InfringementClaim' Document: type: object required: - document_id - document_type properties: document_id: type: string format: uuid description: >- Id returned by the Telnyx Documents API after you upload the file (upload via `POST /v2/documents`; see https://developers.telnyx.com/api/documents). example: 2a7e8337-e803-4057-a4ae-26c40eb0bc6c document_type: type: string enum: - letter_of_authorization - business_registration - articles_of_incorporation - tax_document - ein_letter - trademark_registration - website_ownership - business_license - professional_license - government_id - utility_bill - bank_statement - other example: business_registration description: >- Type of supporting document. Pick the closest match to what the file actually contains; `other` triggers manual vetting and may slow approval. The matching short_name reference list is at `GET /v2/dir/document_types`. description: type: string maxLength: 255 example: Certificate of incorporation. InfringementClaim: type: object properties: id: type: string format: uuid example: e379fbc8-cd83-4bef-a280-a0ac9d00dcf8 readOnly: true dir_id: type: string format: uuid example: 42a3f554-7ce3-44c2-bfe9-6e1afe0d7991 enterprise_id: type: string format: uuid example: 7eca8226-8081-4e11-abdc-437b5f53a81f claim_type: $ref: '#/components/schemas/InfringementClaimType' claim_description: type: string minLength: 10 maxLength: 2000 example: Alleged infringement on trademark XYZ. claimant_name: type: string minLength: 1 maxLength: 255 example: Test Claimant LLC claimant_contact: type: string minLength: 1 maxLength: 255 example: legal@testclaimant.example.com claim_date: type: string format: date-time description: >- When the claim was filed (set by the claimant's representative at file time). example: '2026-04-22T02:12:54Z' readOnly: true status: $ref: '#/components/schemas/InfringementClaimStatus' resolution: type: string nullable: true enum: - upheld - rejected - modified description: Set only when `status` is `resolved`. resolution_date: type: string format: date-time nullable: true readOnly: true resolution_notes: type: string nullable: true maxLength: 2000 readOnly: true contest_documents: type: array items: $ref: '#/components/schemas/Document' description: Aggregated across all customer contest submissions on this claim. contest_history: type: array items: $ref: '#/components/schemas/ContestSubmission' description: >- Per-round submission audit trail. Each entry records one `POST /infringement_claims/{id}/contest` call (notes, timestamp, document count). Aggregated documents live on `contest_documents`. readOnly: true dir: $ref: '#/components/schemas/InfringementClaimDirRef' created_at: type: string format: date-time example: '2026-04-22T02:12:55.908411Z' readOnly: true updated_at: type: string format: date-time example: '2026-04-22T02:12:55.908417Z' readOnly: true Errors: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/Error' description: List of one or more error entries. Order is not significant. description: >- Canonical Telnyx error envelope. Returned on every 4xx and 5xx response from this service. `errors` is non-empty; multiple entries indicate multiple distinct problems with the same request (e.g. one entry per invalid phone number on a bulk operation). InfringementClaimType: type: string enum: - trademark - copyright description: Category of infringement being claimed. InfringementClaimStatus: type: string enum: - pending - contested - resolved description: >- Lifecycle status. `pending` - newly filed; the DIR is auto-suspended. `contested` - you have submitted contest evidence; awaiting Telnyx review. `resolved` - final. ContestSubmission: type: object description: >- One round of customer contest evidence on an infringement claim. The aggregated documents across rounds live on the parent claim's `contest_documents`; this submission record carries only the per-round notes and document count. properties: notes: type: string example: >- We own the trademark outright; our registration precedes the claimant by three years. submitted_at: type: string format: date-time example: '2026-04-22T02:13:06.629473Z' readOnly: true document_count: type: integer minimum: 0 example: 1 readOnly: true InfringementClaimDirRef: type: object description: >- Snapshot of the DIR the claim is filed against, embedded for convenience. properties: id: type: string format: uuid example: 42a3f554-7ce3-44c2-bfe9-6e1afe0d7991 readOnly: true display_name: type: string example: Acme Plumbing enterprise_id: type: string format: uuid example: 7eca8226-8081-4e11-abdc-437b5f53a81f status: $ref: '#/components/schemas/DirStatus' Error: type: object required: - code - title - detail - meta properties: code: type: string example: '10005' description: >- Stable numeric Telnyx error catalog id. See `meta.url` for the full catalog entry. title: type: string example: Invalid parameters description: >- Short human-readable category, e.g. `Bad Request`, `Duplicate resource`, `Not Found`, `Forbidden`. Treat as advisory only - the stable identifier is `code`. detail: type: string example: field required description: >- Context-specific message describing what went wrong on this particular request. May embed offending values; do not rely on it for programmatic matching - branch on `code`. meta: type: object required: - url properties: url: type: string format: uri example: https://developers.telnyx.com/docs/overview/errors/10005 pending_check_ids: type: array items: type: string format: uuid description: >- Set on `422 vetting_checks_incomplete` responses from `/admin/dir/{id}/approve` and `/admin/phone-number-batches/approve`. Lists the still-pending vetting check ids. pending_check_codes: type: array items: type: string description: >- Codes of the pending vetting checks (e.g. `loa_signature_valid`). pending_check_labels: type: array items: type: string description: Human-readable labels of the pending vetting checks. description: >- Carries `url` linking to the Telnyx error catalog entry for this `code`. Useful for forwarding the user to documentation. source: type: object description: Optional pointer at the offending field of the request. properties: pointer: type: string example: /body/legal_name parameter: type: string example: page[size] description: >- A single entry in the canonical Telnyx error envelope. `code` is the stable Telnyx error catalog id; the human-readable explanation lives at `meta.url`. `detail` is a context-specific message; `source.pointer` (when present) names the offending field of the request. DirStatus: type: string enum: - draft - submitted - in_review - verified - rejected - unsuccessful - suspended - expired - infringement_claimed - permanently_rejected description: >- DIR lifecycle status. - `draft` - newly created; editable; not yet submitted. - `submitted` / `in_review` - Telnyx is reviewing. - `verified` - approved; phone numbers may be attached. - `rejected` - Telnyx rejected this submission; `rejection_reasons` is populated; customer can edit and resubmit. - `unsuccessful` - system-side error during processing; customer can edit and resubmit. - `suspended` - temporarily disabled (e.g. by an active infringement claim). - `expired` - verification expired; customer must resubmit. - `infringement_claimed` - a trademark/impersonation claim is open against this DIR. - `permanently_rejected` - terminal; cannot be resubmitted. responses: GenericErrorResponse: description: >- An error occurred. The response carries the standard Telnyx error envelope. content: application/json: schema: $ref: '#/components/schemas/Errors' examples: validation_error: summary: 422 - request body failed validation value: errors: - code: '10005' title: Invalid parameters detail: field required meta: url: https://developers.telnyx.com/docs/overview/errors/10005 source: pointer: /body/legal_name bad_request: summary: 400 - request rejected by a state guard description: >- Returned when the request itself is well-formed but the resource is in a state that disallows this action (e.g. updating a DIR while it is being vetted, or deleting an enterprise that still has DIRs in vetting). value: errors: - code: '10015' title: Bad Request detail: Cannot update DIR in 'verified' status meta: url: https://developers.telnyx.com/docs/overview/errors/10015 not_found: summary: 404 - resource does not exist or is not yours value: errors: - code: '10009' title: Resource not found detail: Enterprise not found. meta: url: https://developers.telnyx.com/docs/overview/errors/10009 conflict: summary: 409 - request conflicts with current resource state value: errors: - code: '10021' title: Resource in use detail: >- DIR has 1 active infringement claim(s). Resolve the claim before making this change. meta: url: https://developers.telnyx.com/docs/overview/errors/10021 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys. ````