Experian · OpenAPI Overlay 1.0.0

API Evangelist enhancements for the Experian Aperture Data Quality API

7 actions 7 updates update extends openapi/experian-aperture-openapi.json
Derived by API Evangelist Built from the contracts Experian publishes. Experian did not publish this file.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-api-evangelistx-documentation-urlx-support-urlx-status-pagex-terms-urlx-sla-urlx-eosl-urlx-rate-limit

Targets 3

$.info
$.components.securitySchemes.Auth-Token
$.servers

OpenAPI Overlay

Raw ↑
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Experian Aperture Data Quality API
  version: 1.0.0
extends: openapi/experian-aperture-openapi.json
x-generated: '2026-09-13'
x-method: generated
x-source: openapi/experian-aperture-openapi.json plus the artifacts derived from it in this repo
x-note: >-
  This overlay records API Evangelist enhancements to Experian's published contract. It NEVER mutates
  the original document. Two gaps drove it. First, not one of the 41 operations in Experian's
  published spec carries an operationId — measured, zero of 41 — which makes the contract unusable by
  every code generator and every tool that binds a tool name to an operation, and is why the agent
  skills in this repo have to address operations by method and path. This overlay does not invent
  operationIds into the provider's document; it records the gap as an extension so the absence is
  legible rather than silent. Second, the runtime semantics Experian documents on web pages —
  the account-wide 150 req/min limit and its X-Rate-Limit-* headers, the rfc9457-shaped error
  envelope, the reversibility posture of the two write surfaces — appear nowhere in the contract, so
  an agent reading only the spec cannot see them.
actions:
  - target: $.info
    description: Record the contract-quality gaps measured against the published document and point
      at the derived artifacts that fill them.
    update:
      x-api-evangelist:
        measured: '2026-09-13'
        operations: 41
        operations_with_operationid: 0
        operations_with_summary: 41
        operations_with_description: 0
        operations_with_tags: 41
        components_schemas: 389
        spec_declares_tags_array: false
        note: >-
          Every operation has a summary and a tag but none has an operationId and none has a
          description. The document also declares no top-level tags[] array, so the tag names used on
          operations are undescribed. These are the highest-leverage single fixes available to
          Experian in this contract.
        derived_artifacts:
          authentication: authentication/experian-authentication.yml
          conventions: conventions/experian-conventions.yml
          errors: errors/experian-problem-types.yml
          rate_limits: rate-limits/experian-rate-limits.yml
          lifecycle: lifecycle/experian-lifecycle.yml
          data_model: data-model/experian-data-model.yml
          conformance: conformance/experian-conformance.yml
          mcp_candidate: mcp/experian-mcp.yml
  - target: $.info
    description: Attach the published contact and licensing context absent from info.
    update:
      x-documentation-url: https://docs.experianaperture.io/
      x-support-url: https://community.experianaperture.io/
      x-status-page: https://status.edq.com/
      x-terms-url: https://docs.experianaperture.io/standard-terms-and-conditions-and-policies
      x-sla-url: https://docs.experianaperture.io/saas-services-sla
      x-eosl-url: https://docs.experianaperture.io/end-of-service-life-status
  - target: $.info
    description: Record the runtime rate-limit contract, which the spec does not express.
    update:
      x-rate-limit:
        scope: per-account
        window: 1 minute
        limit: 150
        adjustable: false
        status_on_exhaustion: 429
        headers:
          - X-Rate-Limit-Limit
          - X-Rate-Limit-Remaining
          - X-Rate-Limit-Reset
        retry_after: false
        source: https://docs.experianaperture.io/address-validation/experian-address-validation/help/rate-limiting/
  - target: $.info
    description: Record the error-envelope semantics and the fact that the RFC 9457 media type is
      not used.
    update:
      x-error-format:
        shape: rfc9457-shaped
        media_type: application/json
        problem_json: false
        wrapper: error
        members:
          - type
          - title
          - detail
          - instance
        missing_members:
          - status
        catalog: errors/experian-problem-types.yml
  - target: $.info
    description: Record the agent-safety posture of the surface — idempotency, dry-run and
      reversibility — none of which the contract expresses.
    update:
      x-agent-safety:
        idempotency:
          coverage: none
          header: null
        dry_run: false
        reversibility:
          grade: documented
          reversible_writes:
            - surface: bulk batches
              reversal: POST /{address|email|phone}/bulk/v1/batches/{batch_id}/stop
              window_stated: false
          irreversible_writes:
            - surface: custom address layouts
              operation: DELETE /address/layouts/v2/{name}
              note: no restore or soft-delete is documented
        read_only_majority: true
        pii_operations:
          - POST /enrichment/v2
          - POST /identity/append/v1
          - POST /phone/append/v1
        pii_note: >-
          These three operations return personal or household-level data about identifiable people.
          Any agent integration should treat them as consent-gated regardless of what the API
          permits, and any use in the United States falls under FCRA permissible-purpose rules.
  - target: $.components.securitySchemes.Auth-Token
    description: Record the operational controls attached to the token that the scheme description
      omits.
    update:
      x-issued-from: https://docs.experianaperture.io/more/self-service-portal/
      x-additional-controls:
        - per-integration domain allowlist (403 when the calling domain is not allowlisted)
        - per-integration IP allowlist (403 when the calling IP is not allowlisted)
      x-environment-selection: by hostname, not by key prefix — a token's value does not reveal
        whether it is test or live
  - target: $.servers
    description: Note that the single declared server is the only Aperture host; the Global
      Developer Platform is a separate, region-partitioned surface with no published contract.
    update:
      x-related-platforms:
        - name: Experian Global Developer Platform
          hosts:
            - https://us-api.experian.com
            - https://uk-api.experian.com
            - https://eu-api.experian.com
            - https://api.experian.com.au
          contract_published: false
          portal: https://developer.experian.com/

Work with this as data

Every overlay here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for openapi overlays

4 MCP tools reach this
  • find_overlaysBrowse and filter every overlay in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This overlay
curl "https://apis.io/api/v1/overlays/experian-aperture-overlay"
All openapi overlays
curl "https://apis.io/api/v1/overlays?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.