---
title: "Listing flyer: just listed, open house, Instagram 4:5 (agent-branded)"
method: POST
path: "/api/locus-property-flyer"
tags: ["data", "search", "real-estate", "property", "property-research", "due-diligence", "public-records", "x402", "listing-flyer", "just-listed", "open-house", "instagram", "realtor", "agent-branding", "flyer", "category:marketing"]
---

# Listing flyer: just listed, open house, Instagram 4:5 (agent-branded)

`POST /api/locus-property-flyer`

## Request

- Base URL: `https://api.locus.report`
- URL: `https://api.locus.report/api/locus-property-flyer`
- Auth: API key in header `PAYMENT-SIGNATURE`

Just-listed, open-house, or coming-soon 4:5 PNG for one address with agent colors, logo, contact, and headshot. With no licensed subject photo, uses an aerial hero and official parcel outline when available; the model supplies only decorative skin. No valuation or ranking. npx @velinussage/locus-agent-skill add.

## Request body

- object: Only `address` is required. Everything else is optional: brand (colors, logo, contact strip, headshot), style, headline, creative brief, seller-attested features, a licensed subject photo, and a proof-gated PDF handoff for the QR. With no photo, Locus generates the hero aerial itself.
  - `address` string, required: Exact US street address or identified lot/parcel used for location research and the flyer subject.
  - `headline` 'PROPERTY OVERVIEW' | 'PROPERTY HIGHLIGHTS' | 'PROPERTY CONTEXT' | 'WATERFRONT PROPERTY OVERVIEW' | 'LAND OVERVIEW'
  - `subjectEvidence` object: Optional caller attestation for the displayed subject identity. Address-only requests may omit it; Locus attaches official parcel provenance when available.
    - `authority` 'seller_attested', required: The requester attests this marketing fact. A supplied public-record link remains caller evidence, not independent Locus verification.
    - `sourceName` string, required
    - `sourceUrl` string, uri
    - `recordId` string
    - `observedAt` string, date-time, required: Timestamp when the official record was fetched or the seller assertion was made.
  - `reportHandoff` object: Optional flyer-specific PDF handoff. When omitted, the flyer renders without a report QR or report CTA.
    - `pdfUrl` string, required: Proof-gated PDF URL produced by a property-update job. Before payment, the server requires its exact origin to appear in LOCUS_PROPERTY_FLYER_HANDOFF_ORIGINS and verifies the capability, PDF-ready state, expiry, and subject against D1.
    - `expiresAt` string, date-time, required: Expiry of the proof-gated PDF link, shown beside the QR as useful availability metadata.
  - `cta` 'OPEN THE FULL PROPERTY REPORT' | 'REVIEW THE PROPERTY REPORT' | 'SCAN FOR THE FULL PROPERTY REPORT'
  - `features` object[]: Optional seller-attested feature copy. When omitted, Locus derives up to three bounded facts from official parcel/aerial results and omits unavailable slots.
    - `text` string, required: One concise, factual property benefit or condition. Describe the property only; no audiences, communities, demographics, predictions, rankings, or safe/unsafe claims.
    - `evidence` object, required
      - `authority` 'seller_attested', required: The requester attests this marketing fact. A supplied public-record link remains caller evidence, not independent Locus verification.
      - `sourceName` string, required
      - `sourceUrl` string, uri
      - `recordId` string
      - `observedAt` string, date-time, required: Timestamp when the official record was fetched or the seller assertion was made.
  - `propertyImage` object: Optional licensed subject image. When omitted, Locus generates the hero itself: an upscaled public aerial with the official parcel outline when the address resolves to a discrete parcel, or a tight clean crop otherwise.
    - `role` 'subject_property_media', required: Declares that this is raw subject-property media, never a finished flyer, poster, listing screenshot, or style reference.
    - `url` string, uri, required: HTTPS URL for the licensed subject-property image. It is composited unchanged after generation and is never sent through the image model.
    - `sourceName` string, required
    - `kind` 'licensed_property_photo' | 'locus_report_visual', required
    - `rightsConfirmed` true, required: Required caller attestation that Locus may render this image into the paid flyer.
    - `rightsBasis` 'owned_by_requester' | 'licensed_for_marketing' | 'public_domain' | 'locus_generated', required
    - `rightsHolder` string, required
    - `permittedUse` 'commercial_marketing', required
    - `attestedAt` string, date-time, required
    - `privacyReviewed` true, required: Requester confirms the image was reviewed for faces, license plates, and other unnecessary personal information.
  - `brand` object
    - `primaryColor` string
    - `accentColor` string
    - `highlightColor` string
    - `logo` object: Optional caller-authorized raster logo that replaces the visible Locus wordmark.
      - `role` 'brand_logo', required: Declares a raster brand mark that replaces visible Locus branding in the requested flyer or video.
      - `url` string, required: HTTPS URL for a caller-authorized PNG, JPEG, or WebP logo. The API fetches and embeds it; renderers never fetch this URL.
      - `sourceName` string, required
      - `rightsConfirmed` true, required
      - `rightsBasis` 'owned_by_requester' | 'licensed_for_marketing' | 'public_domain', required
      - `rightsHolder` string, required
      - `permittedUse` 'commercial_marketing', required
      - `attestedAt` string, date-time, required
      - `privacyReviewed` true, required: Requester confirms the logo contains no unnecessary personal information.
    - `contact` object: Optional listing-agent or brokerage contact strip rendered as exact text above the footer. Business contact details only; Locus never looks these up and never adds any.
      - `name` string, required: Listing agent or team name as it should appear on the flyer.
      - `organization` string: Brokerage or company name.
      - `license` string: License identifier exactly as it must appear for advertising compliance, e.g. "NC Lic. 123456" or "TREC #0123456".
      - `phone` string, required: Business phone, digits and separators only.
      - `email` string, email
      - `website` string: Website shown as text only; the flyer never links out.
    - `headshot` object: Optional caller-authorized raster headshot for the contact strip. Requires `contact`. Same host allowlist, size, and rights attestation as `logo`.
      - `role` 'agent_headshot', required: Declares a caller-authorized portrait of the listed contact, composited as a circular crop beside the contact strip.
      - `url` string, required: HTTPS URL for a caller-authorized PNG, JPEG, or WebP logo. The API fetches and embeds it; renderers never fetch this URL.
      - `sourceName` string, required
      - `rightsConfirmed` true, required
      - `rightsBasis` 'owned_by_requester' | 'licensed_for_marketing' | 'public_domain', required
      - `rightsHolder` string, required
      - `permittedUse` 'commercial_marketing', required
      - `attestedAt` string, date-time, required
      - `privacyReviewed` true, required: Requester confirms the logo contains no unnecessary personal information.
  - `style` 'local_editorial' | 'coastal' | 'land' | 'luxury' | 'modern'
  - `creativeBrief` string: Optional design direction and grounded-fact emphasis only. It cannot add, alter, or override factual claims and is reduced to a closed token set before the model prompt.

## Response `200`

Successful paid artifact, or a free pre-charge diagnostic when the request is outside current coverage.

- union: A temporary 4:5 PNG flyer plus the location-art-direction prompt and source ledger, or a charged:false runtime/research diagnostic.
  - object
    - `kind` 'property_flyer', required
    - `flyerId` string, required
    - `generatedAt` string, required
    - `expiresAt` string, required
    - `address` string, required
    - `imageUrl` string, uri, required
    - `width` 1600, required
    - `height` 2000, required
    - `mediaType` 'image/png', required
    - `model` 'google/nano-banana-pro', required
    - `prompt` string, required
    - `contentHash` string, required
    - `composition` object, required
      - `designSystemVersion` 'editorial-evidence-v2' | 'editorial-evidence-v3' | 'editorial-evidence-v4', required
      - `generatedDesignSkin` boolean, required
      - `designSkinPromptConstrained` true, required
      - `designSkinComposited` boolean, required
      - `designSkinHash` string, required
      - `heroSource` 'caller' | 'locus_generated', required
      - `propertyImagePreserved` boolean, required
      - `heroUpscaled` boolean, required
      - `exactCopyRenderedDeterministically` true, required
      - `callerLogoComposited` boolean, required
      - `callerContactRendered` boolean
      - `callerHeadshotComposited` boolean
      - `creativeBriefConstrained` true, required
      - `creativeBriefApplied` boolean, required
      - `reportQrRendered` boolean
    - `subjectEvidence` union
      - object
        - `authority` 'seller_attested', required: The requester attests this marketing fact. A supplied public-record link remains caller evidence, not independent Locus verification.
        - `sourceName` string, required
        - `sourceUrl` string, uri
        - `recordId` string
        - `observedAt` string, date-time, required: Timestamp when the official record was fetched or the seller assertion was made.
      - object
        - `authority` 'locus_official', required
        - `sourceName` string, required
        - `sourceUrl` string, uri
        - `recordId` string
        - `observedAt` string, date-time, required
    - `priceEvidence` union
      - object
        - `authority` 'seller_attested', required: The requester attests this marketing fact. A supplied public-record link remains caller evidence, not independent Locus verification.
        - `sourceName` string, required
        - `sourceUrl` string, uri
        - `recordId` string
        - `observedAt` string, date-time, required: Timestamp when the official record was fetched or the seller assertion was made.
      - object
        - `authority` 'locus_official', required
        - `sourceName` string, required
        - `sourceUrl` string, uri
        - `recordId` string
        - `observedAt` string, date-time, required
    - `reportHandoff` object
      - `pdfUrl` string, uri, required
      - `expiresAt` string, date-time, required
    - `propertyImageEvidence` object
      - `role` 'subject_property_media', required
      - `sourceName` string, required
      - `kind` 'licensed_property_photo' | 'locus_report_visual', required
      - `rightsConfirmed` true, required
      - `rightsBasis` 'owned_by_requester' | 'licensed_for_marketing' | 'public_domain' | 'locus_generated', required
      - `rightsHolder` string, required
      - `permittedUse` 'commercial_marketing', required
      - `attestedAt` string, date-time, required
      - `privacyReviewed` true, required
    - `brandLogoEvidence` object
      - `role` 'brand_logo', required: Declares a raster brand mark that replaces visible Locus branding in the requested flyer or video.
      - `sourceName` string, required
      - `rightsConfirmed` true, required
      - `rightsBasis` 'owned_by_requester' | 'licensed_for_marketing' | 'public_domain', required
      - `rightsHolder` string, required
      - `permittedUse` 'commercial_marketing', required
      - `attestedAt` string, date-time, required
      - `privacyReviewed` true, required: Requester confirms the logo contains no unnecessary personal information.
      - `contentHash` string, required
    - `brandHeadshotEvidence` object
      - `role` 'agent_headshot', required
      - `sourceName` string, required
      - `rightsConfirmed` true, required
      - `rightsBasis` 'owned_by_requester' | 'licensed_for_marketing' | 'public_domain', required
      - `rightsHolder` string, required
      - `permittedUse` 'commercial_marketing', required
      - `attestedAt` string, date-time, required
      - `privacyReviewed` true, required: Requester confirms the logo contains no unnecessary personal information.
      - `contentHash` string, required
    - `generatedHero` object
      - `source` 'usda_naip_via_usgs', required
      - `precision` 'parcel' | 'address' | 'area', required
      - `parcelOutline` boolean, required
      - `naipDate` string
      - `heroUpscaled` boolean, required
      - `upscaleModel` 'google/upscaler'
      - `displayEnhanced` boolean, required
    - `features` object[], required
      - `text` string, required: One concise, factual property benefit or condition. Describe the property only; no audiences, communities, demographics, predictions, rankings, or safe/unsafe claims.
      - `evidence` union, required
        - object
          - `authority` 'seller_attested', required: The requester attests this marketing fact. A supplied public-record link remains caller evidence, not independent Locus verification.
          - `sourceName` string, required
          - `sourceUrl` string, uri
          - `recordId` string
          - `observedAt` string, date-time, required: Timestamp when the official record was fetched or the seller assertion was made.
        - object
          - `authority` 'locus_official', required
          - `sourceName` string, required
          - `sourceUrl` string, uri
          - `recordId` string
          - `observedAt` string, date-time, required
    - `referenceResearch` object, required
      - `provider` 'exa' | 'tavily' | 'stableenrich-x402', required
      - `cached` boolean, required
      - `sources` object[], required
        - `title` string, required
        - `url` string, uri, required
      - `imageCandidates` object[], required
        - `imageUrl` string, uri, required
        - `sourcePageUrl` string, uri, required
        - `sourceTitle` string, required
        - `usage` 'inspection_only_unlicensed', required
        - `licenseStatus` 'unknown', required
    - `caveats` string[], required
  - object
    - `kind` 'property_flyer_diagnostic', required
    - `charged` false, required
    - `status` 'not_configured' | 'reference_research_unavailable' | 'imagery_unavailable' | 'design_generation_unavailable', required
    - `message` string, required
    - `recommendedAction` 'configure_flyer_runtime' | 'retry_reference_research' | 'repair_reference_research_runtime' | 'supply_property_image_or_retry' | 'separate_property_media_and_style_reference' | 'retry_design_generation', required
    - `provider` 'exa' | 'tavily' | 'stableenrich-x402'
    - `failureCode` 'reference_runtime_not_configured' | 'reference_budget_unavailable' | 'reference_signer_policy_denied' | 'reference_upstream_unavailable' | 'reference_no_results' | 'hero_analysis_point_unavailable' | 'hero_imagery_unavailable' | 'hero_input_role_mismatch' | 'design_model_unavailable'

## Other responses

- `400`: Invalid request body, or a pre-payment property_flyer_claim_rejected response identifying the rejected field, optional zero-based feature index, and stable rule reason.
- `402`: Payment Required. For x402 v2, repeat the identical request with a valid PAYMENT-SIGNATURE header (legacy X-PAYMENT is accepted for compatibility). MPP is disabled for this lifecycle-bound tool.

---

[API](https://skmtc.dev/locus/apis/locus-api.md) · [All operations](https://skmtc.dev/locus/apis/locus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/locus/apis/locus-api/revisions/ba7786b74adb?raw)