tpsclear-co-uk API

openapi: 3.1.0
info:
  title: tpsclear-co-uk API
  version: '2026-10-31'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-31: 19 operation(s) read from 6 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; tpsclear-co-uk has published no machine-readable contract that
    the pipeline could find. Engine: anthropic.'
  x-evidence-tiers:
    code-example: 1
    documentation: 18
    pages-with-code: 2
    pages-read: 6
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-31'
  x-generator: generate-contract-from-docs.py
  x-engine: anthropic
  x-sources:
  - https://tpsclear.co.uk/articles/tps-register-api
  - https://tpsclear.co.uk/zapier
  - https://tpsclear.co.uk/developers
  - https://tpsclear.co.uk/articles/hlr-lookup-explained
  - https://tpsclear.co.uk/how-it-works
  - https://tpsclear.co.uk/articles/do-not-call-register-australia
servers:
- url: https://api.tpsclear.co.uk
paths:
  /v1/consents:
    delete:
      operationId: delete_v1_consents
      tags:
      - Consents
      summary: Remove one number when consent is withdrawn.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteV1ConsentsResponse'
      x-evidence:
        kind: documentation
    get:
      operationId: get_v1_consents
      tags:
      - Consents
      summary: 'Your consent list: numbers you hold consent to call.'
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ConsentsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_consents
      tags:
      - Consents
      summary: Add numbers to the consent list with the same bodies and limits as POST /v1/suppressions.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ConsentsRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ConsentsResponse'
      x-evidence:
        kind: documentation
  /v1/dead-number:
    get:
      operationId: get_v1_dead_number
      tags:
      - Dead Number
      summary: The dead number checks left on your account.
      x-source: https://tpsclear.co.uk/developers
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1DeadNumberResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_dead_number
      tags:
      - Dead Number
      summary: Ask the mobile network whether up to 500 numbers are live, switched off or dead.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1DeadNumberRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1DeadNumberResponse'
      x-evidence:
        kind: documentation
  /v1/dncr:
    get:
      operationId: get_v1_dncr
      tags:
      - Dncr
      summary: Get the Australian Do Not Call Register washes remaining on your key.
      x-source: https://tpsclear.co.uk/developers
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1DncrResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_dncr
      tags:
      - Dncr
      summary: Screen an Australian phone number against ACMA's Do Not Call Register.
      x-source: https://tpsclear.co.uk/zapier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1DncrRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1DncrResponse'
      x-evidence:
        kind: documentation
  /v1/keys/rotate:
    post:
      operationId: post_v1_keys_rotate
      tags:
      - Keys
      summary: Mint a replacement token for the key and optionally revoke the old one.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1KeysRotateRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1KeysRotateResponse'
      x-evidence:
        kind: documentation
  /v1/me:
    get:
      operationId: get_v1_me
      tags:
      - Me
      summary: The calling key's name, environment, plan and scopes.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1MeResponse'
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_v1_me
      tags:
      - Me
      summary: PATCH /v1/me
      x-source: https://tpsclear.co.uk/developers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1MeRequest'
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchV1MeResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -X PATCH https://api.tpsclear.co.uk/v1/me  -H "Authorization: Bearer tpsc_live_xxx"  -H "Content-Type: application/json"  -d
          ''{"company_name": "Acme Outbound Ltd"}'' Rate limits and cost A live check costs one credit from your prepaid balance. Limits are counted
          in lookups, not requests, so a bulk call of 500 numbers counts as 500. A self-serve key has a daily lookup budget of 5,000, and the
          a'
  /v1/screen:
    post:
      operationId: post_v1_screen
      tags:
      - Screen
      summary: Screen a single number or small batch of phone numbers against the TPS and CTPS registers.
      x-source: https://tpsclear.co.uk/articles/tps-register-api
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer token for authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ScreenRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ScreenResponse'
      x-evidence:
        kind: documentation
  /v1/screen/bulk:
    post:
      operationId: post_v1_screen_bulk
      tags:
      - Screen
      summary: Submit a bulk list of up to 50,000 phone numbers for screening against the TPS and CTPS registers.
      x-source: https://tpsclear.co.uk/articles/tps-register-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ScreenBulkRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ScreenBulkResponse'
      x-evidence:
        kind: documentation
  /v1/screen/bulk/scr_01HYZ:
    get:
      operationId: get_v1_screen_bulk_scr_01HYZ
      tags:
      - Screen
      summary: Retrieve the results of a bulk screening job.
      x-source: https://tpsclear.co.uk/articles/tps-register-api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ScreenBulkScr01HyzResponse'
      x-evidence:
        kind: documentation
  /v1/screen/{id}:
    get:
      operationId: get_v1_screen_id
      tags:
      - Screen
      summary: Fetch a past screen result by id for audit purposes.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ScreenIdResponse'
      x-evidence:
        kind: documentation
  /v1/suppressions:
    delete:
      operationId: delete_v1_suppressions
      tags:
      - Suppressions
      summary: Remove one number from the suppression list.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteV1SuppressionsResponse'
      x-evidence:
        kind: documentation
    get:
      operationId: get_v1_suppressions
      tags:
      - Suppressions
      summary: 'Your own do-not-call list: the total count and the 100 most recent entries.'
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1SuppressionsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_suppressions
      tags:
      - Suppressions
      summary: Add up to 10,000 numbers per request to the suppression list.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1SuppressionsRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1SuppressionsResponse'
      x-evidence:
        kind: documentation
  /v1/usage:
    get:
      operationId: get_v1_usage
      tags:
      - Usage
      summary: Current-window usage for the key plus rolling 30-day totals for the account.
      x-source: https://tpsclear.co.uk/developers
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1UsageResponse'
      x-evidence:
        kind: documentation
  /webhooks/tpsclear:
    post:
      operationId: post_webhooks_tpsclear
      tags:
      - Webhooks
      summary: Webhook endpoint that receives re-screening notifications when a number's TPS or CTPS status changes.
      x-source: https://tpsclear.co.uk/articles/tps-register-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostWebhooksTpsclearRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    DeleteV1ConsentsResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Operation success
        removed:
          type: boolean
          description: Whether the number was removed
    GetV1ConsentsResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of consents on the list
        consents:
          type: array
          description: Array of the 100 most recent consent entries
    PostV1ConsentsRequest:
      type: object
      properties:
        numbers:
          type: array
          description: Array of phone numbers to add
        entries:
          type: array
          description: Array of entries with number, optional reason and datetime
    PostV1ConsentsResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Operation success
        added:
          type: integer
          description: Number of new entries added
        alreadyListed:
          type: integer
          description: Number of entries already on the list
        invalid:
          type: array
          description: Array of up to 50 rejected values
        invalidRows:
          type: array
          description: Detailed error information for each invalid row
        invalidCount:
          type: integer
          description: Total count of invalid entries
        total:
          type: integer
          description: Total consents on the list after operation
    GetV1DeadNumberResponse:
      type: object
      properties:
        checksRemaining:
          type: integer
    PostV1DeadNumberRequest:
      type: object
      properties:
        numbers:
          type: array
          description: Array of up to 500 phone numbers in international format
      required:
      - numbers
    PostV1DeadNumberResponse:
      type: object
      properties:
        results:
          type: array
          description: Array of results, one per number sent in order
        checksCharged:
          type: integer
          description: Total checks charged for this request
        checksRemaining:
          type: integer
          description: Balance of checks remaining after this request
    GetV1DncrResponse:
      type: object
      properties:
        washesRemaining:
          type: integer
    PostV1DncrRequest:
      type: object
      properties:
        phone_number:
          type: string
          description: Australian phone number to screen against DNCR
      required:
      - phone_number
    PostV1DncrResponse:
      type: object
      properties:
        status:
          type: string
          description: 'Status: on_register, not_on_register, invalid or unknown'
        safe_to_call:
          type: boolean
          description: Whether the number is safe to call
        wash_date:
          type: string
          description: Date the wash was performed
        valid_until:
          type: string
          description: Date until which the result is valid, 30 days later
    PostV1KeysRotateRequest:
      type: object
      properties:
        revokeOld:
          type: boolean
          description: Whether to revoke the old key immediately (default true)
    PostV1KeysRotateResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Operation success
        token:
          type: string
          description: New token, shown only once
        tokenPrefix:
          type: string
          description: Prefix of the new token
        last4:
          type: string
          description: Last 4 characters of new token
        revokedOld:
          type: boolean
          description: Whether old key was revoked
        note:
          type: string
          description: Notice that token is shown only once
    GetV1MeResponse:
      type: object
      properties:
        key:
          type: object
          description: Key last 4 characters and name
        environment:
          type: string
          description: live or test
        plan:
          type: string
          description: The key's plan
        scopes:
          type: array
          description: Array of scopes the key holds
    PatchV1MeRequest:
      type: object
      properties:
        company_name:
          type: string
    PatchV1MeResponse:
      type: object
      properties:
        error:
          type: string
    PostV1ScreenRequest:
      type: object
      properties:
        phoneNumbers:
          type: array
          description: Array of phone numbers to screen
      required:
      - phoneNumbers
    PostV1ScreenResponse:
      type: object
      properties:
        results:
          type: array
          description: Array of screening results
        phoneNumber:
          type: string
          description: The phone number screened
        tpsListed:
          type: boolean
          description: Whether the number is listed on the TPS
        ctpsListed:
          type: boolean
          description: Whether the number is listed on the CTPS
        checkedAt:
          type: string
          description: Timestamp when the number was checked
        fileVersion:
          type: string
          description: Version of the TPS/CTPS file used for checking
    PostV1ScreenBulkRequest:
      type: object
      properties:
        phoneNumbers:
          type: array
          description: Array of up to 50,000 phone numbers to screen
      required:
      - phoneNumbers
    PostV1ScreenBulkResponse:
      type: object
      properties:
        jobId:
          type: string
          description: Unique identifier for the bulk screening job
        status:
          type: string
          description: Current status of the bulk job
    GetV1ScreenBulkScr01HyzResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the bulk job
        results:
          type: array
          description: Array of screening results with the same shape as single-screen response
    GetV1ScreenIdResponse:
      type: object
      properties:
        id:
          type: string
          description: The request id, same as X-Request-Id header
        createdAt:
          type: string
          description: When the record was written
        environment:
          type: string
          description: live or test
        lookups:
          type: integer
          description: Distinct valid numbers sent for register check
        campaignRef:
          type: string
          description: Optional campaign reference from original call
        summary:
          type: object
          description: Results counted by status
        providerFailures:
          type: integer
          description: Numbers whose register lookup failed
        results:
          type: array
          description: One entry per number sent, in order sent
    DeleteV1SuppressionsResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Operation success
        removed:
          type: boolean
          description: Whether the number was removed
    GetV1SuppressionsResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of suppressions on the list
        suppressions:
          type: array
          description: Array of the 100 most recent suppression entries
    PostV1SuppressionsRequest:
      type: object
      properties:
        numbers:
          type: array
          description: Array of phone numbers to add
        entries:
          type: array
          description: Array of entries with number, optional reason and datetime
    PostV1SuppressionsResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: Operation success
        added:
          type: integer
          description: Number of new entries added
        alreadyListed:
          type: integer
          description: Number of entries already on the list
        invalid:
          type: array
          description: Array of up to 50 rejected values
        invalidRows:
          type: array
          description: Detailed error information for each invalid row
        invalidCount:
          type: integer
          description: Total count of invalid entries
        total:
          type: integer
          description: Total suppressions on the list after operation
    GetV1UsageResponse:
      type: object
      properties:
        key:
          type: object
          description: Key last 4 characters and name
        environment:
          type: string
          description: live or test
        plan:
          type: string
          description: The key's plan type
        window:
          type: object
          description: Current fair-use window limits and usage
        last30d:
          type: object
          description: 30-day rolling totals for calls and lookups
        uk_credits:
          type: integer
          description: Prepaid UK checks remaining on live key
    PostWebhooksTpsclearRequest:
      type: object
      properties:
        event:
          type: string
          description: Event type, e.g. 'rescreen.changed'
        phoneNumber:
          type: string
          description: The phone number whose status changed
        previous:
          type: object
          description: Previous TPS and CTPS listing status
        current:
          type: object
          description: Current TPS and CTPS listing status
        checkedAt:
          type: string
          description: Timestamp when the change was detected
      required:
      - event
      - phoneNumber
      - previous
      - current
      - checkedAt
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Consents
- name: Dead Number
- name: Dncr
- name: Keys
- name: Me
- name: Screen
- name: Suppressions
- name: Usage
- name: Webhooks