> ## 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. # Confirm or give up ownership of a phone number > Answer an ownership question about a phone number hosted with another provider. Send `still_own: true` to confirm you still own a number whose `ownership_status` is `pending_confirmation` or `flagged`; its status returns to `verified` and, after a carrier change, the new carrier becomes the one on record. Send `still_own: false` to report that you no longer own the number. It is removed from Number Reputation immediately, whatever its current status, and the response shows it with `ownership_status: removed`. ## OpenAPI ````yaml /openapi/source/external/number-reputation/number-reputation.json post /enterprises/{enterprise_id}/reputation/numbers/{phone_number}/ownership_confirm openapi: 3.1.0 info: x-latency-category: responsive title: Telnyx Number Reputation API version: 2.0.0 description: >- The Telnyx Number Reputation API lets you monitor the spam-score / reputation of your phone numbers on US/CA carrier networks. Register a phone number for reputation monitoring, submit a Letter of Authorization (LOA) so carriers honor your remediation requests, refresh scores on a schedule, and inspect reputation history over time. Flow: create an enterprise, register it for Number Reputation, submit the LOA, add phone numbers, then read their reputation data and trends. Number Reputation is billable - 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: Terms of Service description: >- Accept and review the Branded Calling and Phone Number Reputation terms of service. - name: Reputation description: Phone-number reputation monitoring (spam-score lookup and tracking). - name: Enterprises description: Manage the legal-entity record that owns your DIRs and phone numbers. paths: /enterprises/{enterprise_id}/reputation/numbers/{phone_number}/ownership_confirm: post: tags: - Reputation summary: Confirm or give up ownership of a phone number description: >- Answer an ownership question about a phone number hosted with another provider. Send `still_own: true` to confirm you still own a number whose `ownership_status` is `pending_confirmation` or `flagged`; its status returns to `verified` and, after a carrier change, the new carrier becomes the one on record. Send `still_own: false` to report that you no longer own the number. It is removed from Number Reputation immediately, whatever its current status, and the response shows it with `ownership_status: removed`. operationId: confirmReputationNumberOwnership parameters: - $ref: '#/components/parameters/EnterpriseId' - $ref: '#/components/parameters/PhoneNumberPath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OwnershipConfirmRequest' example: still_own: true responses: '200': description: The phone number after the confirmation, or the removed number. content: application/json: schema: $ref: '#/components/schemas/ReputationPhoneNumberWithReputation' '400': $ref: '#/components/responses/GenericErrorResponse' '401': $ref: '#/components/responses/GenericErrorResponse' '404': $ref: '#/components/responses/GenericErrorResponse' '503': $ref: '#/components/responses/GenericErrorResponse' components: parameters: EnterpriseId: name: enterprise_id in: path description: The enterprise id. Lowercase UUID. required: true schema: type: string format: uuid example: 4a6192a4-573d-446d-b3ce-aff9117272a6 PhoneNumberPath: name: phone_number in: path required: true description: >- Phone number in E.164 format (`+1NPANXXXXXX` for US/CA). The leading `+` MUST be URL-encoded as `%2B` (e.g. `%2B19493253498`). schema: type: string example: '+19493253498' schemas: OwnershipConfirmRequest: type: object required: - still_own properties: still_own: type: boolean description: >- `true` confirms you still own the number. `false` reports that you no longer own it and removes it from Number Reputation. example: true evidence_document_id: type: string minLength: 1 maxLength: 255 description: Optional id of an uploaded document supporting the confirmation. example: 2a7e8337-e803-4057-a4ae-26c40eb0bc6c ReputationPhoneNumberWithReputation: type: object required: - data properties: data: $ref: '#/components/schemas/ReputationPhoneNumber' ReputationPhoneNumber: type: object properties: id: type: string format: uuid example: 8a4b1f5e-2f12-4c0c-9a98-9b3a7d8b8e62 readOnly: true enterprise_id: type: string format: uuid example: 4a6192a4-573d-446d-b3ce-aff9117272a6 phone_number: type: string description: E.164 with leading `+`. example: '+19493253498' source: $ref: '#/components/schemas/ReputationNumberSource' ownership_status: $ref: '#/components/schemas/ReputationOwnershipStatus' flag_reason: type: - string - 'null' description: >- Why the number's ownership was flagged. `carrier_changed` when an ownership check found the number with a different carrier. example: carrier_changed confirm_by: type: - string - 'null' format: date-time description: >- Deadline to confirm you still own the number. Set only while `ownership_status` is `pending_confirmation`. example: '2026-10-08T07:00:00Z' removed_at: type: - string - 'null' format: date-time description: When the number was removed. Set only for removed numbers. example: '2026-10-09T06:02:11Z' removal_reason: anyOf: - $ref: '#/components/schemas/ReputationRemovalReason' - type: 'null' description: Why the number was removed. Set only for removed numbers. reputation_data: anyOf: - $ref: '#/components/schemas/ReputationData' - type: 'null' description: '`null` until the first refresh has been collected for this number.' created_at: type: string format: date-time example: '2026-04-26T18:06:51.940749Z' readOnly: true updated_at: type: string format: date-time example: '2026-04-26T18:09:24.785211Z' 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). ReputationNumberSource: type: string enum: - telnyx - external description: >- Where the phone number is hosted. `telnyx`: in your Telnyx inventory. `external`: a number you own that is hosted with another provider. example: external ReputationOwnershipStatus: type: string enum: - verified - flagged - pending_confirmation - removed description: >- Result of ongoing ownership checks. `verified`: the number is with the carrier on record. `pending_confirmation`: the number's carrier changed, or a periodic ownership re-verification is due; confirm you still own it before `confirm_by`. `flagged`: a periodic re-verification went unanswered; the number stays monitored and is not removed, but confirm ownership (`POST .../ownership_confirm`) to return it to `verified`. `removed`: the number is no longer monitored; returned by `POST .../ownership_confirm` with `still_own: false`, and when listing numbers with `filter[ownership_status]=removed`. example: verified ReputationRemovalReason: type: string enum: - ported_away - unconfirmed_ownership - reassigned - customer_reported - customer_removed description: >- Why a number was removed. `ported_away`: you confirmed the number left your control after a carrier change. `unconfirmed_ownership`: a carrier change was not confirmed before the deadline. `reassigned`: the number was reported as permanently disconnected. `customer_reported`: you reported that you no longer own the number. `customer_removed`: you removed the number. example: unconfirmed_ownership ReputationData: type: object description: >- Reputation snapshot for a phone number. Each metric is a 0–100 score; `spam_risk` is a coarse bucket. Field set may grow over time - read by key. properties: spam_risk: type: - string - 'null' enum: - low - medium - high - null description: Overall spam-risk classification. example: low spam_category: type: - string - 'null' description: Category label from the reputation feed when the number is flagged. example: null maturity_score: type: - integer - 'null' minimum: 0 maximum: 100 example: 72 connection_score: type: - integer - 'null' minimum: 0 maximum: 100 example: 80 engagement_score: type: - integer - 'null' minimum: 0 maximum: 100 example: 64 sentiment_score: type: - integer - 'null' minimum: 0 maximum: 100 example: 75 last_refreshed_at: type: - string - 'null' format: date-time example: '2026-04-26T18:09:24.785211Z' 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. 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. ````