generated: '2026-08-14'
method: searched
source: >-
  https://docs.fullcontact.com/docs/request-properties,
  https://docs.fullcontact.com/docs/rate-limiting,
  https://docs.fullcontact.com/docs/response-codes-errors,
  https://docs.fullcontact.com/docs/webhooks
description: >-
  Cross-cutting request/response semantics for the FullContact V3 API — the
  behaviours that apply to every endpoint rather than to any one operation.
  FullContact's V3 surface is RPC-flavoured REST: every call is a POST to a
  dot-named action path (/v3/person.enrich, /v3/identity.map) carrying a JSON
  body, so several conventions common elsewhere (cursor pagination, sparse
  fieldsets, PATCH semantics) simply do not exist here.

base_url: https://api.fullcontact.com
api_style: >-
  RPC over HTTPS. POST to /v3/<resource>.<action>, JSON request body, JSON
  response body.

authentication:
  scheme: HTTP Bearer
  header: 'Authorization: Bearer <FullContact API key>'
  key_provisioning: https://docs.fullcontact.com/docs/generate-an-api-key
  oauth: false
  detail: authentication/fullcontact-authentication.yml

idempotency:
  supported: false
  note: >-
    FullContact documents no idempotency key, no request-replay contract, and
    no Idempotency-Key header. Enrichment calls are read-shaped and repeating
    one re-bills, so an agent must dedupe on its own side. Recorded as an
    honest absence — no Idempotency pointer is wired in apis.yml.

pagination:
  supported: false
  note: >-
    No pagination contract is published. The V3 endpoints return a single
    person/company summary or a bulk artifact; bulk results are delivered
    through audience.create / audience.download rather than through paged list
    responses.

field_selection:
  supported: true
  mechanism: request-body parameters that shape which insights are returned
  parameters:
    - name: confidence
      values: [LOW (60%), MED (80%), HIGH (95%, default), MAX (98%)]
      description: >-
        Quality threshold. If the confidence of the data to be returned does
        not meet or exceed the value supplied, the result is not a match.
        Higher = more accurate, fewer matches.
    - name: dataFilter
      description: Restrict the response to named Insights Bundles.
    - name: dataFilterLogic
      values: [AND, OR]
      description: >-
        Whether the bundles named in dataFilter must all be present (AND) or
        any of them (OR). Defaults to OR.
    - name: infer
      description: >-
        Disable FullContact's inferencers when you want only directly observed
        data.
    - name: minimumDataFields
      description: Require a minimum set of populated fields before a match is returned.
    - name: maxMaids
      description: Cap the number of Mobile Advertising IDs returned (default up to 5).
    - name: maxEmailHashes
      description: Cap the number of hashed emails returned (max 20).
    - name: hashedEmailTypeFilter
      values: [MD5, SHA1, SHA256]
      description: Choose which hashed-email variation is returned.
  docs: https://docs.fullcontact.com/docs/request-properties

request_tracing:
  request_id_header: null
  reporting_key:
    header: Reporting-Key
    description: >-
      Client-supplied label carried on the request to tailor the response and
      attribute billed usage to an internal use case, so you can see where
      specific billed events came from.
    example: 'Reporting-Key: segmentXYZ'
  mcp_request_id: >-
    The hosted MCP server returns a request_id on every error envelope, to be
    quoted on support tickets.

versioning:
  scheme: uri-path
  current: v3
  detail: lifecycle/fullcontact-lifecycle.yml

error_envelope:
  shape: '{"status": <int>, "message": "<string>"}'
  note: >-
    Not RFC 9457. The same HTTP status can carry different failure meanings, so
    the message body must be read as well as the code.
  catalog: errors/fullcontact-problem-types.yml

rate_limit_signaling:
  headers: [X-FullContact-RateDelay, X-Rate-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset]
  behavior: >-
    Requests are DELAYED up to 1000ms to stay inside the limit rather than
    rejected; X-FullContact-RateDelay reports the delay applied. A 429 is
    returned only when the required delay would exceed 1000ms.
  detail: rate-limits/fullcontact-rate-limits.yml

async_callbacks:
  supported: true
  mechanism: webhookUrl field in the request body
  behavior: >-
    When webhookUrl is supplied the API answers 202 Accepted and later POSTs
    the completed JSON result to that URL. Query parameters on the webhookUrl
    are preserved, which is the documented way to correlate the callback with
    the originating request.
  detail: asyncapi/fullcontact-webhooks.yml
  docs: https://docs.fullcontact.com/docs/webhooks

consent:
  supported: true
  mechanism: permission object on the enrich request body
  description: >-
    Consent purposes (purposeId, channel, ttl, enabled) plus collectionMethod,
    collectionLocation, policyUrl and termsService can be captured inline on a
    person.enrich call, or managed through the dedicated /v3/permission.*
    endpoints. Purpose ids follow the IAB TCF v2.0 purposes model.
  docs: https://docs.fullcontact.com/docs/request-properties

x-evidence:
  - fetched: '2026-08-14'
    url: https://docs.fullcontact.com/docs/request-properties.md
    http_status: 200
  - fetched: '2026-08-14'
    url: https://docs.fullcontact.com/docs/webhooks.md
    http_status: 200