> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Risk API

> Risk-score a phone number without sending an OTP. Carrier, line type, porting, disposable-number, and fraud signals in one server-to-server call.

Use `POST /v3/phone/risk/` when you need phone intelligence before, instead of, or outside an OTP flow.

It does not send a code to the user. It creates an API session, enriches the number, applies your phone-risk rules, and returns the same normalized phone block used by Phone Verification in one synchronous response.

When the request is saved, Didit can also use the scored phone number as aggregate evidence in **Networks**. Network graphs may show high-risk phone intelligence, porting and line-type context on shared phone signals, but they do not reveal the raw phone number to other organizations.

## Interpret the response

* `status` is the final decision for this API session. It is normally `Approved`; the risk evaluation can produce `In Review` or `Declined`.
* `phone.full_number` is the normalized E.164 number. `phone.phone_number_prefix` and `phone.phone_number` split it into the international prefix and national number.
* `phone.is_disposable` and `phone.is_virtual` are the stable yes/no signals for application logic. The carrier lookup adds `carrier.name` and `carrier.type` (`mobile`, `voip`, and similar).
* `phone.phone_intelligence.score` uses a 0-100 risk scale where a higher number means higher risk. `phone_type_risk` (`Low`, `Medium`, `High`) and `phone_trust_index` (inverse of the score) are derived views.
* `phone.phone_intelligence` and `phone.enrichment` are compatibility aliases with the same normalized object. New integrations can read `phone.enrichment`.
* `phone.matches` lists other sessions of your application where the same number was used by a different user. Use it for duplicate-account detection.
* `request_id` is the API session id. Store it with `vendor_data` if you need to correlate the result with later webhooks or console activity.

<Warning>
  `phone.phone_intelligence` and `phone.enrichment` are best-effort fields. A completed lookup can omit both when no usable intelligence data is returned for that number, country, or plan. Build rules on the stable normalized fields first and treat missing intelligence as "unknown", not "safe".
</Warning>

## Social footprint add-on

Set `enable_social` to `true` to add a `phone_social` block to the response under `phone`: the online platforms this phone number is registered on, grouped by category, with the summary counts and any profile details our data partners return.

* `phone.phone_social.profiles_registered` and `phone.phone_social.profiles_checked` are the headline numbers: platforms where the phone number is confirmed registered, out of the platforms evaluated.
* `phone.phone_social.registered_platforms` and `phone.phone_social.not_registered_platforms` list each platform with its `category` and `scope` (`global`, or `local` for region-specific platforms).
* `phone.phone_social.categories` gives the registered count and ratio per category, and `phone.phone_social.profiles` carries per-platform profile details when a platform exposes them (name, photo URL, about text, privacy status, business-account flag).
* Summary indexes (`digital_footprint_diversity`, `digital_sophistication_index`, `engagement_depth_index`, `subscription_affordability_index`) are 0-10 composites. Every count can be `null` when the check returned no data for it.

`profiles_registered: 0` is a real answer, not a failure: the platforms were checked and the phone number was found on none of them, which is a common synthetic-identity signal. This endpoint does not act on it by itself - use `phone_no_social_presence_action` in a workflow to turn it into a Review or Decline verdict.

The block is absent when `enable_social` is not set, and also when the social check could not be completed - in which case it is not billed.

## Sandbox behavior

Sandbox keys validate the request and return deterministic approved data. They do not send an OTP, consume credits, create a session, or contribute to Networks. With `enable_social` set, they also return a deterministic `phone_social` block.

## Billing

Phone Risk API calls use Phone Risk API pricing, lower than full Phone Verification because no OTP is sent. A live request is billable once the lookup starts, even when some best-effort fields are unavailable.

The social footprint add-on is billed separately: one `phone_social` unit per request on top of the Phone Risk API price, whenever the check completes. The credit check before the lookup covers both.


## OpenAPI

````yaml POST /v3/phone/risk/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/phone/risk/:
    post:
      tags:
        - Standalone APIs
      summary: Risk-score a phone number
      description: >-
        Resolve a phone number and return carrier, line-type, porting,
        disposable-number, cross-session match, and normalized risk-intelligence
        signals without sending an OTP. The endpoint creates an API session and
        returns its id as `request_id`.


        **Decision.** The top-level `status` mirrors `phone.status`. It is
        normally `Approved`; the risk evaluation can produce `In Review` or
        `Declined`.


        **Compatibility aliases.** Live responses expose the normalized
        intelligence object as both `phone.phone_intelligence` and
        `phone.enrichment`. The values are identical. New integrations can read
        `phone.enrichment`. Both keys are absent when no usable intelligence
        data was returned.


        **Billing.** Live calls use Phone Risk API pricing. The request is
        billable once the lookup starts, even when some best-effort fields are
        unavailable.


        **Sandbox.** Sandbox keys validate the request and return deterministic
        approved data without sending an OTP, consuming credits, creating a
        session, or contributing to Networks.


        **Authentication.** Send your application's API key in `x-api-key`.
        Missing or invalid credentials return `403` - this API never returns
        `401`.


        **Rate limit.** Shared write budget of 300 requests per minute per API
        key across all POST/PATCH/DELETE endpoints.


        **Social footprint.** Set `enable_social` to `true` to add a
        `phone_social` block: the online platforms this number is registered on,
        with per-category counts and any profile details available.
        `profiles_registered: 0` means the platforms were checked and the number
        was found on none of them - a valid, billable answer. The block is
        absent when the add-on was not requested or the check could not be
        completed, and it is not billed in that case. Billing adds one
        `phone_social` unit per request on top of this endpoint's own price.
      operationId: post_v3phone_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PhoneRiskRequest'
            examples:
              Minimal:
                summary: Score a number with defaults
                value:
                  phone_number: '+14155552671'
              Full context:
                summary: Score with signals, country hint, and correlation ids
                value:
                  phone_number: '+14155552671'
                  country_code: US
                  signals:
                    ip: 192.0.2.1
                    device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2
                    device_platform: ios
                    device_model: iPhone17,2
                    os_version: 18.0.1
                    app_version: 1.2.34
                    user_agent: >-
                      Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X)
                      AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0
                      Mobile/15E148 Safari/604.1
                  vendor_data: lead-123
                  metadata:
                    source: signup_prescreen
      responses:
        '200':
          description: >-
            The risk evaluation completed. Inspect `status` for the decision;
            HTTP is always `200` for completed lookups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneRiskResponse'
              examples:
                Clean mobile number:
                  summary: Clean mobile number with intelligence coverage
                  value:
                    request_id: 4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62
                    status: Approved
                    phone:
                      status: Approved
                      phone_number_prefix: '+1'
                      phone_number: '4155552671'
                      full_number: '+14155552671'
                      country_code: US
                      country_name: United States
                      carrier:
                        name: Example Mobile
                        type: mobile
                      is_disposable: false
                      is_virtual: false
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                      enrichment:
                        score: 3
                        phone_type_risk: Low
                        phone_trust_index: 97
                        network_stability_index: 95
                        is_disposable: false
                        is_ported: false
                        is_recently_ported: false
                        carrier_type: mobile
                        reason_codes: []
                    vendor_data: lead-123
                    metadata:
                      source: signup_prescreen
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Number in review:
                  summary: Disposable or virtual number flagged for review
                  value:
                    request_id: 8c22e1f0-4b3d-4a3a-9d1e-2f6b7c8d9e0f
                    status: In Review
                    phone:
                      status: In Review
                      phone_number_prefix: '+44'
                      phone_number: '7700900123'
                      full_number: '+447700900123'
                      country_code: GB
                      country_name: United Kingdom
                      carrier:
                        name: Example VoIP
                        type: voip
                      is_disposable: true
                      is_virtual: true
                      verification_method: null
                      verification_attempts: 0
                      verified_at: null
                      warnings: []
                      lifecycle: []
                      matches: []
                      phone_intelligence:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - DISPOSABLE_NUMBER
                          - RECENT_PORT
                      enrichment:
                        score: 72
                        phone_type_risk: High
                        phone_trust_index: 28
                        network_stability_index: 40
                        is_disposable: true
                        is_ported: true
                        is_recently_ported: true
                        carrier_type: voip
                        reason_codes:
                          - DISPOSABLE_NUMBER
                          - RECENT_PORT
                    vendor_data: lead-124
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/PhoneRiskValidationError'
        '403':
          $ref: '#/components/responses/RiskPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/phone/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "phone_number": "+14155552671",
                "country_code": "US",
                "vendor_data": "lead-123",
                "metadata": {"source": "signup_prescreen"}
              }'
        - lang: python
          label: Python
          source: |-
            import os, requests

            resp = requests.post(
                "https://verification.didit.me/v3/phone/risk/",
                headers={"x-api-key": os.environ["DIDIT_API_KEY"], "Content-Type": "application/json"},
                json={
                    "phone_number": "+14155552671",
                    "country_code": "US",
                    "vendor_data": "lead-123",
                    "metadata": {"source": "signup_prescreen"},
                },
                timeout=15,
            )
            resp.raise_for_status()
            result = resp.json()
            print(result["status"])  # Approved / In Review / Declined
            print(result["phone"]["phone_intelligence"]["score"])
        - lang: javascript
          label: JavaScript
          source: >-
            const res = await
            fetch('https://verification.didit.me/v3/phone/risk/', {
              method: 'POST',
              headers: {
                'x-api-key': 'YOUR_API_KEY',
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({
                phone_number: '+14155552671',
                country_code: 'US',
                vendor_data: 'lead-123',
                metadata: { source: 'signup_prescreen' },
              }),
            });

            const data = await res.json();

            console.log(data.status, data.phone.phone_intelligence?.score);
components:
  schemas:
    PhoneRiskRequest:
      type: object
      required:
        - phone_number
      properties:
        phone_number:
          type: string
          maxLength: 20
          description: Phone number to score. It is validated and normalized to E.164.
          example: '+14155552671'
        country_code:
          type: string
          maxLength: 3
          description: >-
            Optional ISO 3166-1 alpha-2 or alpha-3 country hint for intelligence
            coverage.
          example: US
        signals:
          $ref: '#/components/schemas/RiskSignals'
        vendor_data:
          type: string
          description: >-
            Your stable reference for this request. Stored on the API session
            and echoed in the response.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Your non-sensitive JSON metadata. Stored on the API session and
            echoed in the response.
        enable_social:
          type: boolean
          default: false
          description: >-
            When true, also look up the social footprint of the number - the
            messaging, social, e-commerce and professional platforms it is
            registered on. Billed as one `phone_social` unit per request in
            addition to this endpoint's own price.
          example: true
    PhoneRiskResponse:
      type: object
      required:
        - request_id
        - status
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Id of the API session created for this request. Store it with
            `vendor_data` if you need to correlate the result with later
            webhooks or console activity.
        status:
          type: string
          enum:
            - Approved
            - In Review
            - Declined
          description: >-
            Final decision for this API session. Normally `Approved`; the risk
            evaluation can produce `In Review` or `Declined`.
        vendor_data:
          type: string
          nullable: true
          description: >-
            Echo of the `vendor_data` you sent, `null` when you did not send
            one.
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: Echo of the `metadata` you sent, `null` when you did not send one.
        created_at:
          type: string
          format: date-time
          description: Timestamp of this response.
        phone:
          type: object
          description: >-
            Normalized phone report, the same block used by Phone Verification
            responses.
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
                - Declined
              description: Decision for this phone number. Mirrors the top-level `status`.
            phone_number_prefix:
              type: string
              description: Country calling code with leading `+` (e.g., `+1`).
              example: '+1'
            phone_number:
              type: string
              description: National number without the country calling code.
              example: '4155552671'
            full_number:
              type: string
              description: Complete number in E.164 format.
              example: '+14155552671'
            country_code:
              type: string
              nullable: true
              description: ISO 3166-1 alpha-2 country of the number.
              example: US
            country_name:
              type: string
              description: Full country name derived from `country_code`.
              example: United States
            carrier:
              type: object
              nullable: true
              description: >-
                Current network serving the number. `null` when the lookup could
                not resolve a carrier.
              properties:
                name:
                  type: string
                  description: >-
                    Carrier name. Empty string when the lookup could not
                    identify it.
                type:
                  type: string
                  description: >-
                    Line type reported by the lookup: `mobile`, `fixed_line`,
                    `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, or
                    similar.
            is_disposable:
              type: boolean
              description: >-
                `true` when the number belongs to a temporary or burner number
                service.
            is_virtual:
              type: boolean
              description: '`true` when the line type is virtual (`voip`, `isp`, or `vpn`).'
            verification_method:
              type: string
              nullable: true
              description: >-
                OTP channel of the underlying verification. `null` for risk
                lookups, which never send a code.
            verification_attempts:
              type: integer
              description: OTP sends for this number. `0` for risk lookups.
            verified_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                When the number was last verified by an OTP. `null` for risk
                lookups.
            warnings:
              type: array
              description: >-
                Risk warnings recorded for this request. Empty array when there
                are none.
              items:
                $ref: '#/components/schemas/RiskWarning'
            lifecycle:
              type: array
              description: >-
                Chronological audit trail of the request. Empty array for risk
                lookups without send events.
              items:
                $ref: '#/components/schemas/RiskLifecycleEvent'
            matches:
              type: array
              description: >-
                Other sessions of your application where the same phone number
                was used by a different user (different `vendor_data`). Up to 5
                entries. Empty array when there are no matches.
              items:
                $ref: '#/components/schemas/PhoneMatchItem'
            phone_intelligence:
              $ref: '#/components/schemas/PhoneIntelligence'
            enrichment:
              $ref: '#/components/schemas/PhoneIntelligence'
            phone_social:
              $ref: '#/components/schemas/PhoneSocialFootprint'
    RiskSignals:
      type: object
      description: >-
        Optional device and network context observed by your application. All
        fields are optional. Passing them feeds cross-session match detection in
        Networks.
      properties:
        ip:
          type: string
          format: ip
          description: IPv4 or IPv6 address observed for the end user.
          example: 192.0.2.1
        device_id:
          type: string
          maxLength: 255
          description: >-
            Stable device identifier collected by your application (Android
            `ANDROID_ID`, iOS `identifierForVendor`).
        device_platform:
          type: string
          enum:
            - android
            - ios
            - ipados
            - tvos
            - web
          description: Platform of the end user's device.
        device_model:
          type: string
          maxLength: 255
          description: Device model reported by your application.
        os_version:
          type: string
          maxLength: 64
          description: Operating-system version.
        app_version:
          type: string
          maxLength: 64
          description: Version of your application.
        user_agent:
          type: string
          maxLength: 512
          description: Browser or app user agent.
    RiskWarning:
      type: object
      required:
        - feature
        - risk
        - log_type
        - short_description
        - long_description
      properties:
        feature:
          type: string
          description: Feature that produced the warning.
        risk:
          type: string
          description: Machine-readable risk code. New values can be added over time.
        additional_data:
          type: object
          nullable: true
          additionalProperties: true
          description: Risk-specific context, or `null`.
        log_type:
          type: string
          enum:
            - error
            - warning
            - information
          description: Severity used by the decision rules.
        short_description:
          type: string
          description: Human-readable one-line summary.
        long_description:
          type: string
          description: Human-readable explanation.
    RiskLifecycleEvent:
      type: object
      required:
        - type
        - timestamp
        - details
        - fee
      properties:
        type:
          type: string
          description: Machine-readable event type. New values can be added over time.
        timestamp:
          type: string
          format: date-time
          description: When the event happened.
        details:
          type: object
          nullable: true
          additionalProperties: true
          description: Event-specific payload, or `null`.
        fee:
          type: number
          description: USD amount billed for this event.
    PhoneMatchItem:
      type: object
      description: >-
        Another session of your application that used the same phone number with
        a different `vendor_data`.
      properties:
        session_id:
          type: string
          format: uuid
          description: Session id of the other verification that used this phone number.
        session_number:
          type: integer
          description: Human-friendly sequential number of that session.
        vendor_data:
          type: string
          nullable: true
          description: '`vendor_data` of that session.'
        verification_date:
          type: string
          description: When that session was created (`YYYY-MM-DDTHH:MM:SSZ`).
        phone_number:
          type: string
          description: The matched phone number.
        status:
          type: string
          description: >-
            Status of that session (e.g., `Approved`, `Declined`, `In
            Progress`).
        is_blocklisted:
          type: boolean
          description: Whether the phone number is on your application's blocklist.
        api_service:
          type: string
          nullable: true
          description: >-
            For API-type sessions, the standalone API that created it; `null`
            for regular verification sessions.
        source:
          type: string
          description: >-
            Where the match was found. Usually `session`; a blocklist hit via an
            organization list entry uses `list_entry`.
    PhoneIntelligence:
      type: object
      description: >-
        Normalized phone-intelligence block. Present only when the intelligence
        add-on ran for this lookup; when present it is also exposed under the
        `enrichment` alias with identical values.
      properties:
        score:
          type: number
          nullable: true
          description: Normalized 0-100 risk score. Higher is riskier.
        phone_type_risk:
          type: string
          nullable: true
          description: '`Low`, `Medium` or `High`, derived from the score.'
        phone_trust_index:
          type: number
          nullable: true
          description: Inverse of the score, for dashboards that prefer higher is better.
        network_stability_index:
          type: number
          nullable: true
          description: Stability of the line's network.
        is_disposable:
          type: boolean
          nullable: true
          description: '`true` when the number looks disposable or virtual.'
        is_ported:
          type: boolean
          nullable: true
          description: '`true` when the number has moved carrier.'
        is_recently_ported:
          type: boolean
          nullable: true
          description: '`true` when the port happened recently.'
        carrier_type:
          type: string
          nullable: true
          description: Line classification reported by the lookup (e.g., `mobile`).
        reason_codes:
          type: array
          items:
            type: string
          description: >-
            Machine-readable codes explaining the score. Values can grow over
            time, so do not reject unknown codes.
    PhoneSocialFootprint:
      type: object
      nullable: true
      description: >-
        Social footprint of the phone number: the online platforms it is
        registered on. Present only when `enable_social` was set and the check
        completed. Every count may be null when no data was returned for it.
        `profiles_registered: 0` means the platforms were checked and the phone
        number was found on none of them - a valid, billable answer and a common
        synthetic-identity signal.
      properties:
        profiles_registered:
          type: integer
          nullable: true
          description: Platforms where the phone number is confirmed registered.
          example: 5
        profiles_checked:
          type: integer
          nullable: true
          description: Platforms evaluated for registration.
          example: 14
        names_found:
          type: integer
          nullable: true
          description: Platforms that returned an associated name.
          example: 0
        photos_found:
          type: integer
          nullable: true
          description: Platforms that returned a profile photo.
          example: 0
        communication_breadth:
          type: integer
          nullable: true
          description: Communication platforms with detected presence.
          example: 2
        digital_footprint_diversity:
          type: integer
          nullable: true
          description: Distinct platform categories with detected presence.
          example: 5
        digital_sophistication_index:
          type: integer
          nullable: true
          description: Composite digital-maturity indicator, 0-10.
          example: 5
        engagement_depth_index:
          type: integer
          nullable: true
          description: Profile-richness indicator, 0-10.
          example: 3
        subscription_affordability_index:
          type: integer
          nullable: true
          description: Free vs paid platform mix, 0-10.
          example: 2
        free_platforms:
          type: integer
          nullable: true
          description: Registrations on free platforms.
          example: 4
        full_paid_platforms:
          type: integer
          nullable: true
          description: Registrations on fully paid platforms.
          example: 0
        partial_paid_platforms:
          type: integer
          nullable: true
          description: Registrations on freemium platforms.
          example: 1
        whatsapp_profile_completeness:
          type: string
          nullable: true
          enum:
            - Basic
            - Partial
            - Complete
            - Not Present
            - null
          description: Completeness of the WhatsApp profile. Phone only; null for email.
          example: Partial
        registered_platforms:
          type: array
          description: Platforms where registration is confirmed.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        not_registered_platforms:
          type: array
          description: Platforms checked with a negative result.
          items:
            $ref: '#/components/schemas/SocialFootprintPlatform'
        categories:
          type: object
          description: Registered count and ratio per platform category.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintCategorySummary'
        profiles:
          type: object
          description: >-
            Per-platform profile details, keyed by platform, when the platform
            exposes them.
          additionalProperties:
            $ref: '#/components/schemas/SocialFootprintProfile'
    SocialFootprintPlatform:
      type: object
      properties:
        platform:
          type: string
          description: Platform identifier.
          example: whatsapp
        category:
          type: string
          description: >-
            Platform category, e.g. MESSAGING, SOCIAL_MEDIA, ECOMMERCE,
            PROFESSIONAL, EMAIL_PROVIDER.
          example: MESSAGING
        scope:
          type: string
          enum:
            - global
            - local
          description: '`global` for worldwide platforms, `local` for region-specific ones.'
          example: global
    SocialFootprintCategorySummary:
      type: object
      properties:
        registered:
          type: integer
          nullable: true
          description: Platforms in this category where registration is confirmed.
          example: 2
        ratio:
          type: number
          format: float
          nullable: true
          description: >-
            Share of the category's checked platforms with a registration,
            0.0-1.0.
          example: 0.6667
    SocialFootprintProfile:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Profile name, when the platform exposes one.
        photo:
          type: string
          nullable: true
          description: Profile photo URL, when the platform exposes one.
        about:
          type: string
          nullable: true
          description: Profile about/bio text, when the platform exposes one.
        privacy_status:
          type: string
          nullable: true
          enum:
            - PUBLIC
            - PRIVATE
            - null
          description: Profile visibility, when the platform exposes it.
        business_account:
          type: boolean
          nullable: true
          description: >-
            Whether the profile is a business account, when the platform exposes
            it.
  responses:
    PhoneRiskValidationError:
      description: Request validation failed.
      content:
        application/json:
          examples:
            Missing phone number:
              summary: Missing phone number
              value:
                phone_number:
                  - This field is required.
            Invalid phone number:
              summary: Invalid phone number
              value:
                phone_number:
                  - Invalid phone number provided.
            Invalid signal IP:
              summary: Invalid signal IP
              value:
                signals:
                  ip:
                    - Enter a valid IPv4 or IPv6 address.
    RiskPermissionDenied:
      description: >-
        The API key is missing or invalid, or the organization cannot cover the
        live lookup. This API never returns `401`.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              summary: No `x-api-key` header, or the key is invalid or revoked
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              summary: Organization balance cannot cover the lookup price
              value:
                error: You don't have enough credits to perform this request.
    RateLimitedWrite:
      description: >-
        The shared write limit of 300 requests per minute per API key was
        exceeded. Honor `Retry-After` before retrying.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your application's API key, from Developers -> API keys in the Business
        Console. The primary key has full access. A named key can be scoped:
        none, read or write per resource, limited to some workflows or to
        approved sessions, to a list of IP addresses, and to an expiry date. 401
        means the key is missing, wrong, revoked or expired; 403 means the key
        has no access to this resource or action, or the request came from an
        address outside its IP list; 404 on a session route means the session is
        outside the key's workflows or statuses. A key without media access
        receives image, video and PDF URLs as null, and a key without sessions
        write receives session links and tokens as null. See
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.