Skip to content
UpriverUpriverUpriver API Docs

Match Persona

v1.0.0
OpenAPI 3.1.0

Upriver API

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.

Server:https://api.upriver.ai

Production API server

Client Libraries
Shell Curl

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 for catalog setup, a complete request example, and guidance on comparing candidate audiences.

Path Parameters
  • catalog_id
    Type: string · Catalog IdFormat: uuid
    required
Body·MatchInput
required
application/json

Request to match a persona against one catalog's entries.

  • persona
    Type: object · PersonaInputModel
    required

    The persona to match against this catalog.

  • settings
    Type: object · MatchSettings

    Caller-controlled matching settings.

Responses
  • application/json
  • application/json
Request Example for post/v1/catalogs/{catalog_id}/match
curl https://api.upriver.ai/v1/catalogs/123e4567-e89b-12d3-a456-426614174000/match \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "persona": {
    "summary": "Tech founders interested in developer tools and automation"
  },
  "settings": {
    "preset": "balanced",
    "priorities": {
      "identity": 1
    },
    "exclusions": {
      "categories": [
        ""
      ],
      "brands": [
        ""
      ],
      "sensitive": true
    },
    "inferred_needs": "off",
    "min_evidence": 0.35,
    "price_tier_affinity": true,
    "geo": "",
    "language": "",
    "limit": 10
  }
}'

{
  "interpretation": {
    "mode": "summary",
    "facets": [
      {
        "kind": "identity",
        "text": "string",
        "confidence": 0,
        "sensitive": true,
        "source_span": "string",
        "parent_index": 0
      }
    ],
    "llm_calls": 0,
    "language": "string",
    "price_sensitivity": "budget"
  },
  "matches": [
    {
      "ref": "string",
      "brand_url": "string",
      "score": 0,
      "evidence_grade": "grounded",
      "matched_offer": {
        "name": "string",
        "url": "string",
        "description": "string",
        "evidence": [
          {
            "source": "string",
            "url": "string",
            "snippet": "string",
            "similarity": 0,
            "judge_probability": 0
          }
        ],
        "relevance_score": 0
      },
      "contributions": [
        {
          "edge": "direct",
          "user_facet": {
            "kind": "identity",
            "text": "string",
            "confidence": 0,
            "sensitive": true,
            "source_span": "string",
            "parent_index": 0
          },
          "product_facet": {
            "kind": "identity",
            "text": "string",
            "confidence": 0,
            "evidence_grade": "grounded"
          },
          "similarity": 1,
          "weight": 1,
          "delta": 1,
          "evidence": [
            {
              "source": "string",
              "url": "string",
              "snippet": "string",
              "similarity": 0,
              "judge_probability": 0
            }
          ]
        }
      ],
      "reasons": [
        "string"
      ],
      "price_tier_fit": "match"
    }
  ],
  "settings_applied": {
    "preset": "balanced",
    "priorities": {
      "identity": 1
    },
    "exclusions": {
      "categories": [
        "string"
      ],
      "brands": [
        "string"
      ],
      "sensitive": true
    },
    "inferred_needs": "off",
    "min_evidence": 0.35,
    "price_tier_affinity": true,
    "geo": "string",
    "language": "string",
    "limit": 10
  },
  "strategy_version": "string",
  "completeness": "complete",
  "brief_fingerprint": "string",
  "relevance_status": "disabled",
  "judge_applied": false
}

Successful Response