> ## 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 https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/branded-calling/infringement-claims.yml post /infringement_claims/{claim_id}/contest openapi: 3.1.0 info: title: Telnyx Branded Calling Infringement Claims API version: 2.0.0 description: >- View and contest infringement claims raised against your DIRs, and re-submit a suspended DIR for vetting. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] 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/branded-calling_GenericErrorResponse' 4XX: $ref: '#/components/responses/branded-calling_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 branded-calling_Errors: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/branded-calling_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' branded-calling_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: branded-calling_GenericErrorResponse: description: >- An error occurred. The response carries the standard Telnyx error envelope. content: application/json: schema: $ref: '#/components/schemas/branded-calling_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: scheme: bearer type: http ````