{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/placementapi-com/json-schema/placementapi-com-quote-line-schema.json",
  "title": "QuoteLine",
  "description": "One placement in a held basket (POST /v1/quote, POST /v1/targets/gap, GET /v1/quotes/{quote_id}). Fields are added, never renamed.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/placementapi-com-openapi.json#/components/schemas/QuoteLine",
  "type": "object",
  "properties": {
    "offer_id": {
      "type": "string"
    },
    "site_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Null on blind inventory."
    },
    "inventory_mode": {
      "$ref": "#/$defs/InventoryMode"
    },
    "placement_type": {
      "$ref": "#/$defs/PlacementType"
    },
    "price_credits": {
      "type": "integer",
      "description": "Held price. Credits. 1 credit = 1 US cent."
    },
    "dr": {
      "type": [
        "number",
        "null"
      ],
      "description": "The vendor's claim. On a subdomain, the parent's number."
    },
    "traffic": {
      "type": [
        "number",
        "null"
      ]
    },
    "verification": {
      "$ref": "#/$defs/Verification"
    },
    "verified_dr": {
      "type": [
        "number",
        "null"
      ],
      "description": "DataForSEO backlinks rank, 0-1000; corroborates, does not replace dr."
    },
    "verified_traffic": {
      "type": [
        "number",
        "null"
      ]
    },
    "organic_keywords": {
      "type": [
        "integer",
        "null"
      ]
    },
    "referring_domains": {
      "type": [
        "integer",
        "null"
      ]
    },
    "spam_score": {
      "type": [
        "number",
        "null"
      ]
    },
    "subdomain_of": {
      "type": [
        "string",
        "null"
      ]
    },
    "quality_reasons": {
      "$ref": "#/$defs/QualityReasons"
    },
    "restricted": {
      "$ref": "#/$defs/Restricted"
    },
    "outbound_external": {
      "type": [
        "integer",
        "null"
      ]
    },
    "inbound_domains": {
      "type": [
        "integer",
        "null"
      ]
    },
    "cc_pagerank": {
      "type": [
        "number",
        "null"
      ]
    },
    "leader_links": {
      "$ref": "#/$defs/LeaderLinks"
    },
    "survival": {
      "$ref": "#/$defs/Survival"
    },
    "supplier_reliability": {
      "$ref": "#/$defs/SupplierReliability"
    },
    "placement_score": {
      "$ref": "#/$defs/PlacementScore"
    },
    "market_reference": {
      "$ref": "#/$defs/MarketReference"
    },
    "plausibility": {
      "$ref": "#/$defs/Plausibility"
    },
    "demand": {
      "$ref": "#/$defs/Demand"
    },
    "why": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Factual sentences behind the pick, derived from the fields on this line and the brief — cite them. Prose; do not parse it."
    },
    "intelligence": {
      "type": "object",
      "description": "Present only when the deployment has placement intelligence configured and this placement was actually judged; absent means not judged, which is not the same as judged and rejected. An advisory semantic judgment. In a `recommended` basket running in configured `rank` mode a rank-usable judgment can reorder a line within the explicit demand/leader priorities; it can never exclude a placement, an alternative or a publisher, and missing, invalid, failed or below-threshold evidence leaves the deterministic result — and every price — unchanged. The service judges a sampled publisher page resolved by site id, not the offered placement itself, so a below-threshold reading is not evidence against buying this slot. `topical_fit` and `confidence` are on the service's own scale — not a probability of SEO impact. No provider payload, evidence text or customer id is ever included.",
      "properties": {
        "status": {
          "type": "string",
          "description": "computed | cached when a judgment exists; disabled | insufficient_evidence | no_evidence | invalid_evidence | unavailable | budget_exhausted | busy | invalid_response | timeout otherwise."
        },
        "rank_usable": {
          "type": "boolean",
          "description": "True only in rank mode when the service's own policy called the judgment usable. In a `recommended` basket a rank-usable judgment is what can reorder the placement; no judgment, usable or not, removes one."
        },
        "topical_fit": {
          "type": [
            "number",
            "null"
          ],
          "description": "The judged fit to the brief's recognized topics, on the service's own scale; null when nothing usable was produced."
        },
        "confidence": {
          "type": [
            "number",
            "null"
          ]
        },
        "editorial_format": {
          "type": [
            "string",
            "null"
          ]
        },
        "policy_version": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "relevance": {
      "description": "Topic coverage of the brief, or null when the brief named no topics."
    },
    "alternatives": {
      "type": "array",
      "maxItems": 2,
      "items": {
        "$ref": "#/$defs/QuoteAlternative"
      }
    },
    "turnaround_days": {
      "type": [
        "integer",
        "null"
      ]
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "guarantees": {},
    "order_requirements": {
      "$ref": "#/$defs/OrderRequirements"
    }
  },
  "$defs": {
    "ContentOption": {
      "type": "object",
      "description": "A writing tier purchasable with the placement. Tiers are normalised across every supplier: 'supplied' = you provide the copy; 'included' = writing is in the price; 'standard' = purchasable, AI-drafted and human-edited; 'native' = purchasable, native expert writer; 'papi_written' = Placement Papi drafts to the spec for a flat 1,500 credits charged with the order, buyer approves before it goes out.",
      "properties": {
        "tier": {
          "type": "string",
          "enum": [
            "supplied",
            "included",
            "standard",
            "native",
            "papi_written"
          ]
        },
        "vendor_label": {
          "type": [
            "string",
            "null"
          ],
          "description": "Pass as content_tier for content_mode 'service'."
        },
        "price_credits": {
          "type": "integer",
          "description": "Add-on cost. Credits. 1 credit = 1 US cent."
        },
        "word_count": {
          "type": [
            "integer",
            "null"
          ]
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "ContentSpec": {
      "type": [
        "object",
        "null"
      ],
      "description": "The brief to write against when the buyer supplies copy. Null when copy cannot be supplied.",
      "properties": {
        "word_count_min": {
          "type": [
            "integer",
            "null"
          ]
        },
        "word_count_max": {
          "type": [
            "integer",
            "null"
          ]
        },
        "links_allowed": {
          "type": "integer"
        },
        "anchor_types_forbidden": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Editorial rules in the publisher's own words."
        }
      }
    },
    "Demand": {
      "type": [
        "object",
        "null"
      ],
      "description": "Observed demand: distinct buyers who bought the domain in twelve months and the niches they bought for. Null under the three-buyer floor. Nothing about any one buyer is ever here.",
      "properties": {
        "buyers_12m": {
          "type": "integer"
        },
        "purchases_12m": {
          "type": "integer"
        },
        "niches": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "topic": {
                "type": "string"
              },
              "buyers": {
                "type": "integer"
              }
            }
          }
        }
      }
    },
    "InventoryMode": {
      "type": "string",
      "enum": [
        "named",
        "pre_approval",
        "blind"
      ],
      "description": "The most important field. 'named' = a specific, identified domain you can inspect before ordering. 'pre_approval' = the vendor proposes candidate domains and the buyer approves them BEFORE placement. 'blind' = a promise (e.g. DR50+, finance) where the domain is assigned at fulfilment with no veto. Only 'named' carries a site_id. Never present a pre_approval or blind offer as though a specific site were secured, and never price-compare a specification against a named domain as the same product."
    },
    "LeaderLinks": {
      "type": [
        "object",
        "null"
      ],
      "description": "Common Crawl web graph, root sites only (null on subdomains): how many of a topic's top-ranking sites the domain links to, keyed by topic.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "linked": {
            "type": "integer"
          },
          "of": {
            "type": "integer"
          }
        }
      }
    },
    "MarketReference": {
      "type": [
        "object",
        "null"
      ],
      "description": "The median ASK of comparable placements (same type, inventory mode and claimed-DR decade), not a clearing price — say 'market reference', never 'fair value'. own_asks is the spread of asks across suppliers for this exact domain and type, as counts and credits only. ask_history is null under 14 days of observations. Null on a thin band.",
      "properties": {
        "reference_credits": {
          "type": "integer"
        },
        "method": {
          "type": "string",
          "const": "band_median_v1"
        },
        "comparables_n": {
          "type": "integer"
        },
        "vs_reference_pct": {
          "type": "number",
          "description": "This price against the reference, in percent; negative is cheaper."
        },
        "assessment": {
          "type": "string",
          "enum": [
            "under",
            "at",
            "over"
          ],
          "description": "±15% band around the reference."
        },
        "own_asks": {
          "type": "object",
          "properties": {
            "listings": {
              "type": "integer"
            },
            "suppliers": {
              "type": "integer"
            },
            "lowest": {
              "type": "integer"
            },
            "median": {
              "type": "integer"
            },
            "highest": {
              "type": "integer"
            }
          }
        },
        "ask_history": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "first_seen_at": {
              "type": "string",
              "format": "date-time"
            },
            "days_observed": {
              "type": "integer"
            },
            "first_credits": {
              "type": "integer"
            },
            "change_pct": {
              "type": "number"
            }
          }
        }
      }
    },
    "OrderRequirements": {
      "type": [
        "object",
        "null"
      ],
      "description": "What you MUST send, what you MAY send, and what you can buy, normalised across suppliers. `required` lists the fields to include in POST /v1/orders. Read `confidence`: 'observed' and 'documented' are reliable; 'assumed' means the confirmation step may ask for something not listed.",
      "properties": {
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Always includes target_url; anchor_text is absent only where the publisher writes the anchor."
        },
        "optional": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "content": {
          "type": "object",
          "properties": {
            "supplied_allowed": {
              "type": "boolean",
              "description": "Whether you may write the article yourself."
            },
            "spec": {
              "$ref": "#/$defs/ContentSpec"
            },
            "options": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ContentOption"
              }
            },
            "due_days": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Days a supplied article may take to arrive after ordering (14); null where the publisher writes."
            }
          }
        },
        "speed": {
          "type": "object",
          "properties": {
            "standard_days": {
              "type": [
                "integer",
                "null"
              ]
            },
            "expedited_days": {
              "type": [
                "integer",
                "null"
              ]
            },
            "expedited_surcharge_bps": {
              "type": [
                "integer",
                "null"
              ]
            }
          }
        },
        "confirmation_required": {
          "type": "boolean",
          "description": "True when a human at the supplier confirms the line before it is placed; treat the order as pending rather than done."
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Placement rules the buyer must respect regardless of who writes the copy."
        },
        "confidence": {
          "type": "string",
          "enum": [
            "observed",
            "documented",
            "assumed"
          ]
        }
      }
    },
    "PlacementScore": {
      "type": [
        "object",
        "null"
      ],
      "description": "Placement Score v1: { score 0-100, version, confidence high|medium|low, components each 0-100 or null, capped }. Weights (authority 25 / visibility 25 / quality 30 / graph 10 / survival 10) are stated, not fitted; unmeasured components drop out and the rest re-weight; a suspect publisher never scores above 40. Derived from the fields beside it, so it can be checked. Does NOT include observed effectiveness, relevance to your brief, or supplier reliability. Quote the components, not just the number.",
      "properties": {
        "score": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "version": {
          "type": "string"
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ],
          "description": "Share of the weight that had a measurement behind it."
        },
        "components": {
          "type": "object",
          "properties": {
            "authority": {
              "type": [
                "number",
                "null"
              ]
            },
            "visibility": {
              "type": [
                "number",
                "null"
              ]
            },
            "quality": {
              "type": [
                "number",
                "null"
              ]
            },
            "graph": {
              "type": [
                "number",
                "null"
              ]
            },
            "survival": {
              "type": [
                "number",
                "null"
              ]
            }
          }
        },
        "capped": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "suspect",
            null
          ]
        }
      }
    },
    "PlacementType": {
      "type": "string",
      "enum": [
        "guest_post",
        "niche_edit",
        "link_insert",
        "homepage_link",
        "media_placement"
      ]
    },
    "Plausibility": {
      "type": [
        "object",
        "null"
      ],
      "description": "Where this price sits among comparable domains (same placement type, inventory mode and claimed-DR decade). flag 'low' = under the 10th percentile, which is bought authority more often than it is a bargain; 'high' = above the 90th. Null when the band had too few domains to describe.",
      "properties": {
        "pct": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "band": {
          "type": "string"
        },
        "flag": {
          "type": "string",
          "enum": [
            "low",
            "ok",
            "high"
          ]
        },
        "n": {
          "type": "integer",
          "description": "Domains behind the distribution."
        }
      }
    },
    "QualityReasons": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Which rules made verification read suspect: high_authority_no_traffic, high_authority_no_keywords, spam_score, subdomain_without_own_footprint, saturated_outbound. Empty when not suspect."
    },
    "QuoteAlternative": {
      "type": "object",
      "description": "Another domain that could take this line's place, HELD at the price shown. Order it with the same quote_id and it is charged that price; the primary it replaces is simply not ordered.",
      "properties": {
        "offer_id": {
          "type": "string"
        },
        "site_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "placement_type": {
          "$ref": "#/$defs/PlacementType"
        },
        "price_credits": {
          "type": "integer"
        },
        "dr": {
          "type": [
            "number",
            "null"
          ]
        },
        "verification": {
          "$ref": "#/$defs/Verification"
        },
        "plausibility_pct": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "Restricted": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "gambling / adult / piracy when the site is one, from the domain name and a short topic list. Such rows appear only when asked for (include_restricted, or a topic/accepts naming the vertical)."
    },
    "SupplierReliability": {
      "type": "object",
      "description": "How the seller behind the line has performed for us (fulfilment, on-time delivery, link survival, failures, refunds) over n submitted orders. Never a name. Within 5% of price the basket prefers the better band; 'unknown' (under five orders) is judged on price alone.",
      "properties": {
        "band": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low",
            "unknown"
          ]
        },
        "n": {
          "type": "integer"
        }
      }
    },
    "Survival": {
      "type": [
        "object",
        "null"
      ],
      "description": "What happened to the placements WE bought on this publisher. Our crawler re-checks every delivered link at 0/7/30/60/90/180/365 days. Null under three orders.",
      "properties": {
        "orders": {
          "type": "integer"
        },
        "checks": {
          "type": "integer"
        },
        "live_share": {
          "type": "number"
        },
        "live_90d_share": {
          "type": [
            "number",
            "null"
          ]
        },
        "median_days_to_missing": {
          "type": [
            "number",
            "null"
          ]
        },
        "dofollow_share": {
          "type": [
            "number",
            "null"
          ]
        },
        "noindex_share": {
          "type": [
            "number",
            "null"
          ]
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "Verification": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "ok",
        "suspect",
        "unverified",
        null
      ],
      "description": "Our independent verdict on the claimed authority; no supplier publishes it. 'suspect' = high link authority with little or no organic search presence, which is what a link farm looks like — do not plan around suspect domains. 'ok' = measured, and search presence matches the rating. 'unverified' = not measured yet, which is not a pass."
    }
  }
}