> ## Documentation Index > Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt > Use this file to discover all available pages before exploring further. # Match Persona > Interpret a persona and rank this catalog's entries for fit. Returns fit scores from 0 to 1, the persona's interpreted characteristics, and supporting evidence for each qualifying advertiser. Scores measure relevance, not purchase probability or verified buying intent. An absent match is not a zero score. See [Score audience fit](https://docs.upriver.ai/audience/matching) for catalog setup, a complete request example, and guidance on comparing candidate audiences. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/catalogs/{catalog_id}/match openapi: 3.1.0 info: title: Upriver API description: >- A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads. version: 1.0.0 servers: - url: https://api.upriver.ai description: Production API server security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Breakout Topics - name: Taxonomy paths: /v1/catalogs/{catalog_id}/match: post: tags: - Audience summary: Match Persona description: >- Interpret a persona and rank this catalog's entries for fit. Returns fit scores from 0 to 1, the persona's interpreted characteristics, and supporting evidence for each qualifying advertiser. Scores measure relevance, not purchase probability or verified buying intent. An absent match is not a zero score. See [Score audience fit](https://docs.upriver.ai/audience/matching) for catalog setup, a complete request example, and guidance on comparing candidate audiences. operationId: match_catalog parameters: - name: catalog_id in: path required: true schema: type: string format: uuid title: Catalog Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MatchInput' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MatchOutput' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: MatchInput: properties: persona: $ref: '#/components/schemas/PersonaInputModel' description: The persona to match against this catalog. settings: $ref: '#/components/schemas/MatchSettings' description: Caller-controlled matching settings. additionalProperties: false type: object required: - persona title: MatchInput description: Request to match a persona against one catalog's entries. MatchOutput: properties: interpretation: $ref: '#/components/schemas/MatchInterpretation' matches: items: $ref: '#/components/schemas/CatalogMatch' type: array title: Matches description: Ranked catalog entries that fit the persona. settings_applied: $ref: '#/components/schemas/MatchSettings' description: The settings this match was computed under. strategy_version: type: string title: Strategy Version description: Version of the scoring strategy that produced this match. completeness: $ref: '#/components/schemas/Completeness' description: Whether this response is complete. brief_fingerprint: type: string title: Brief Fingerprint description: Stable identifier for this persona-and-settings pairing. relevance_status: type: string enum: - disabled - applied - fallback - skipped_sensitive - skipped_settings - no_candidates title: Relevance Status description: >- Full-context relevance assessment: applied, disabled, no_candidates, fallback after unavailability, skipped_sensitive to honor exclusions, or skipped_settings to preserve custom scoring preferences. default: disabled judge_applied: type: boolean title: Judge Applied description: >- Whether a borderline-match verification pass, selected server-side, was in effect for this response: either it ran and its answers were applied, or there was nothing borderline enough to need verifying. A match still returns normally, with this false, when no verification pass is configured, it only measures without changing results, or the selected backend is unavailable. default: false additionalProperties: false type: object required: - interpretation - matches - settings_applied - strategy_version - completeness - brief_fingerprint title: MatchOutput description: Ranked catalog entries for one persona, with an explained score each. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PersonaInputModel: properties: summary: anyOf: - type: string maxLength: 8000 minLength: 1 - type: 'null' title: Summary description: Free-text persona description. profile: anyOf: - $ref: '#/components/schemas/PersonaProfileInput' - type: 'null' description: Structured persona fields. facets: anyOf: - items: $ref: '#/components/schemas/PersonaFacetInput' type: array maxItems: 80 - type: 'null' title: Facets description: Caller-typed persona facets. additionalProperties: false type: object title: PersonaInputModel description: >- Persona to match against a catalog: exactly one of summary, profile or facets. example: summary: Tech founders interested in developer tools and automation MatchSettings: properties: preset: $ref: '#/components/schemas/Preset' description: >- Named weighting: balanced, performance (stated needs first) or awareness (interests and situations count more). default: balanced priorities: additionalProperties: type: number propertyNames: $ref: '#/components/schemas/FacetKind' type: object title: Priorities description: >- Optional multipliers from 0 to 2 per characteristic kind, applied on top of the preset. exclusions: $ref: '#/components/schemas/Exclusions' description: What to leave out of the results. inferred_needs: $ref: '#/components/schemas/InferredNeeds' description: >- Whether needs implied by stated interests and situations may contribute: off, capped (a bounded share of each score) or on. default: 'off' min_evidence: type: number maximum: 1 minimum: 0 title: Min Evidence description: >- Minimum score for an advertiser to be returned at all. A price-tier mismatch (see price_tier_affinity) can by itself lower a score below this threshold. default: 0.35 price_tier_affinity: type: boolean title: Price Tier Affinity description: >- Whether an entry's price tier and the persona's price sensitivity, when both are known, adjust that entry's score: a small boost when they agree, a small penalty at the two extremes. Set false to leave scores unaffected by price tier. default: true geo: anyOf: - type: string maxLength: 2 minLength: 2 pattern: ^[A-Za-z]{2}$ - type: 'null' title: Geo description: Optional country filter, as a two-letter ISO 3166-1 country code. language: anyOf: - type: string maxLength: 16 - type: 'null' title: Language description: Optional language code filter. limit: type: integer maximum: 50 minimum: 1 title: Limit description: Maximum number of advertisers returned. default: 10 additionalProperties: false type: object title: MatchSettings description: >- Caller-controlled settings. Presets plus bounded multipliers, not free weights. MatchInterpretation: properties: mode: $ref: '#/components/schemas/InterpretationMode' description: How the persona was provided. facets: items: $ref: '#/components/schemas/PersonaFacetSummary' type: array title: Facets description: The typed facets read from the persona. llm_calls: type: integer minimum: 0 title: Llm Calls description: Number of model calls used to read this persona. language: anyOf: - type: string - type: 'null' title: Language description: >- This persona's dominant language, as a two-letter code, or `mixed` when the persona mixes multiple languages with no single dominant one. Null when it could not be determined. price_sensitivity: anyOf: - type: string enum: - budget - mid - premium - type: 'null' title: Price Sensitivity description: >- This persona's price sensitivity, when stated: budget, mid or premium. Null when the persona said nothing about spend. additionalProperties: false type: object required: - mode - facets - llm_calls title: MatchInterpretation description: What was read from the supplied persona. CatalogMatch: properties: ref: type: string title: Ref description: The matched entry's caller-defined identifier. brand_url: type: string title: Brand Url description: Brand website URL for the matched entry. score: type: number maximum: 1 minimum: 0 title: Score description: Fit from 0 to 1 under the reported scoring strategy. evidence_grade: $ref: '#/components/schemas/EvidenceGrade' description: Strength of support behind this match. matched_offer: anyOf: - $ref: '#/components/schemas/MatchedOffer' - type: 'null' description: Selected offer when full-context relevance was assessed. contributions: items: $ref: '#/components/schemas/Contribution' type: array title: Contributions description: >- Supporting facet relationships. With a selected offer, these explain candidate discovery rather than add up to its relevance score. reasons: items: type: string type: array title: Reasons description: Short, human-readable reasons for this match. price_tier_fit: anyOf: - type: string enum: - match - adjacent - mismatch - type: 'null' title: Price Tier Fit description: >- How this entry's price tier compares with the persona's price sensitivity: match, adjacent, or mismatch. Null when either the persona or the entry gives no price signal. additionalProperties: false type: object required: - ref - brand_url - score - evidence_grade - contributions - reasons title: CatalogMatch description: One catalog entry ranked for fit against a persona. Completeness: type: string enum: - complete - truncated - unavailable title: Completeness ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError PersonaProfileInput: properties: identity: anyOf: - type: string maxLength: 300 minLength: 2 - type: 'null' title: Identity description: A short description of who this persona is. interests: items: type: string maxLength: 300 minLength: 2 type: array maxItems: 40 title: Interests description: Topics or activities this persona is interested in. situations: items: type: string maxLength: 300 minLength: 2 type: array maxItems: 40 title: Situations description: Situations or contexts relevant to this persona. needs: items: type: string maxLength: 300 minLength: 2 type: array maxItems: 40 title: Needs description: Needs this persona has. intent: anyOf: - type: string maxLength: 300 minLength: 2 - type: 'null' title: Intent description: This persona's stated intent, when known. additionalProperties: false type: object title: PersonaProfileInput description: Structured persona fields, mapped deterministically to facets. PersonaFacetInput: properties: kind: $ref: '#/components/schemas/FacetKind' description: What kind of statement this facet is. text: type: string maxLength: 300 minLength: 2 title: Text description: The facet's text. confidence: type: number maximum: 1 minimum: 0 title: Confidence description: Confidence in this facet, from 0 to 1. sensitive: type: boolean title: Sensitive description: Whether this facet touches a sensitive topic. default: false source_span: anyOf: - type: string maxLength: 300 - type: 'null' title: Source Span description: The phrase in the persona this facet came from, when known. parent_index: anyOf: - type: integer minimum: 0 - type: 'null' title: Parent Index description: >- Index of the stated facet this facet was inferred from. Must be null unless `inferred` is true. inferred: type: boolean title: Inferred description: >- Whether this facet was inferred by the caller rather than stated directly in the persona. default: false additionalProperties: false type: object required: - kind - text - confidence title: PersonaFacetInput description: One caller-supplied statement describing the persona. Preset: type: string enum: - balanced - performance - awareness title: Preset Exclusions: properties: categories: items: type: string type: array maxItems: 50 title: Categories description: Product categories to leave out of the results. brands: items: type: string type: array maxItems: 200 title: Brands description: Brand websites, as domains, to leave out of the results. sensitive: type: boolean title: Sensitive description: >- When true, statements about sensitive topics never contribute to a score. default: true additionalProperties: false type: object title: Exclusions InferredNeeds: type: string enum: - 'off' - capped - 'on' title: InferredNeeds InterpretationMode: type: string enum: - summary - profile - facets title: InterpretationMode PersonaFacetSummary: properties: kind: $ref: '#/components/schemas/FacetKind' description: What kind of statement this facet is. text: type: string title: Text description: The facet's text. confidence: type: number maximum: 1 minimum: 0 title: Confidence description: Confidence in this facet, from 0 to 1. sensitive: type: boolean title: Sensitive description: Whether this facet touches a sensitive topic. source_span: anyOf: - type: string maxLength: 300 - type: 'null' title: Source Span description: The phrase in the persona this facet came from, when known. parent_index: anyOf: - type: integer minimum: 0 - type: 'null' title: Parent Index description: Index of the stated facet this facet was inferred from, if any. additionalProperties: false type: object required: - kind - text - confidence - sensitive title: PersonaFacetSummary description: One typed statement interpreted from a supplied persona. EvidenceGrade: type: string enum: - grounded - sparse - derived title: EvidenceGrade MatchedOffer: properties: name: type: string title: Name description: Name of the selected product or service. url: anyOf: - type: string - type: 'null' title: Url description: Selected offer page, when known. description: type: string title: Description description: Available description of the selected offer. evidence: items: $ref: '#/components/schemas/EvidenceItem' type: array title: Evidence description: Source excerpts supporting this offer. relevance_score: type: number maximum: 1 minimum: 0 title: Relevance Score description: Assessed relevance from 0 to 1; not a purchase probability. additionalProperties: false type: object required: - name - description - relevance_score title: MatchedOffer description: Specific product or service supporting the advertiser recommendation. Contribution: properties: edge: $ref: '#/components/schemas/EdgeType' description: The kind of relationship this edge represents. user_facet: $ref: '#/components/schemas/PersonaFacetSummary' description: The persona facet on this edge. product_facet: $ref: '#/components/schemas/ProductFacetSummary' description: The product facet on this edge. similarity: type: number title: Similarity description: Raw similarity between the two facets. weight: type: number title: Weight description: Weight applied to this edge under the caller's settings. delta: type: number title: Delta description: This edge's signed contribution to the raw score. evidence: items: $ref: '#/components/schemas/EvidenceItem' type: array title: Evidence description: Supporting evidence behind the product facet. additionalProperties: false type: object required: - edge - user_facet - product_facet - similarity - weight - delta title: Contribution description: One persona-facet-to-product-facet edge that contributed to a score. FacetKind: type: string enum: - identity - need - trigger - barrier - interest - situation - intent title: FacetKind EvidenceItem: properties: source: type: string title: Source description: Community, platform or document the snippet came from. url: anyOf: - type: string - type: 'null' title: Url description: Link to the source when known. snippet: type: string maxLength: 600 minLength: 1 title: Snippet description: Short excerpt supporting the facet. similarity: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Similarity description: How closely the excerpt supports the facet, 0 to 1 when known. judge_probability: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Judge Probability description: >- Calibrated probability that this evidence supports the facet, when a judge scored it. additionalProperties: false type: object required: - source - snippet title: EvidenceItem EdgeType: type: string enum: - direct - affinity - inferred - barrier title: EdgeType ProductFacetSummary: properties: kind: $ref: '#/components/schemas/FacetKind' description: What kind of statement this facet is. text: type: string title: Text description: The facet's text. confidence: type: number maximum: 1 minimum: 0 title: Confidence description: Confidence in this facet, from 0 to 1. evidence_grade: $ref: '#/components/schemas/EvidenceGrade' description: Strength of support behind this facet. additionalProperties: false type: object required: - kind - text - confidence - evidence_grade title: ProductFacetSummary description: A minimal view of the product facet behind one score contribution. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.