Skip to main content

Generate a marketplace handoff URL for a category

POST 
/api/marketplace/links/category/:categorySlug

Requires admin token. Returns an Ownli-hosted handoff URL for the given marketplace category. The integrator renders this URL as an anchor (button, card, deep link) inside its own app; clicking lands the end user on Ownli's hosted handoff page, which collects any missing fields and forwards the user to the vendor.

Authentication (server-side only): this endpoint must be called from the partner's backend, authenticated with an Authorization: Bearer token from POST /api/auth/token. Credentials must never be embedded in browser or mobile client code — link generation is a server-to-server call, and the calling partner is identified from the credentials (used for attribution and user ownership).

User continuity: Ownli resolves users by user.email/user.phone. The first call for a user not yet known to Ownli creates them (which is why email or phone is required); subsequent calls with the same email/phone resolve to the same user, so repeat visits skip data the user already provided.

Vehicle context: optional. Supply a VIN (preferred) or license plate + state if the partner already knows the vehicle — Ownli enriches year/make/model from the VIN automatically. If omitted, the handoff page collects vehicle details from the end user.

Address: optional. Supply user.address (addressLine1, addressLine2, city, state, zip) if the partner already knows the end user's address. The whole block is optional; when present, state is the only required field (a valid 2-letter US code) and country is assumed US.

Link lifetime: the returned URL embeds a single-use token with a limited TTL (24 hours by default). Generate the link at render time rather than caching it; an expired link sends the user to a recovery flow instead of the vendor.

Category-based selection: the path parameter is always a marketplace category slug (e.g. insurance, tires, extended-warranty), never a specific vendor. Ownli selects and shows the best vendor for the category during the handoff flow. The set of categories grows as new ones are onboarded.

Theming & presentation: the handoff UI is themed to the calling partner's brand (its DataBuyer logo/color/font). Pass themeOverride to override any theme field for this link only — an API integrator that fronts multiple businesses uses this to theme the handoff to a specific business (color, font, logo, name) without that business needing its own DataBuyer. Pass mode (embedded/standalone) to hint how the UI should render; if omitted, the UI auto-detects.

Request​

Path Parameters

    categorySlug stringrequired

    Marketplace category slug issued by Ownli at integration time (e.g. insurance, tires, extended-warranty). Vendor selection is resolved during the handoff flow.

    Example: insurance

Body

required

    user

    object

    End-user context supplied by the partner when generating a marketplace link. At least one of email or phone is required so Ownli can find-or-create the underlying user — repeat calls with the same email/phone resolve to the same Ownli user. Fields are vendor-agnostic; vendor-specific extras can be added later.

    email string

    Possible values: <= 254 characters

    End-user email. Used to resolve against an existing Ownli user if one exists.

    phone string

    Possible values: <= 32 characters

    End-user phone in E.164 format.

    firstName string

    Possible values: <= 64 characters

    End-user first name.

    lastName string

    Possible values: <= 64 characters

    End-user last name.

    partnerUserId string

    Possible values: <= 128 characters

    Optional. The partner's own identifier for this end-user, stored as-is for the partner's later reference. Never used to resolve or authenticate the Ownli user — email/phone remains the required identity.

    address

    object

    End-user mailing address. The whole block is optional, but when supplied, state is the only required field — addressLine1, addressLine2, city and zip are accepted but optional. Country is assumed US.

    addressLine1 string

    Possible values: <= 128 characters

    Street address (line 1).

    addressLine2 string

    Possible values: <= 128 characters

    Street address (line 2).

    city string

    Possible values: <= 128 characters

    City.

    state stringrequired

    Possible values: Value must match regular expression [A-Za-z]{2}

    2-letter US state code. Required when an address block is supplied.

    zip string

    Possible values: <= 16 characters

    ZIP / postal code.

    vehicle

    object

    Vehicle the end user is interested in. VIN preferred; license-plate + state is a fallback. Both optional — if neither is supplied, the handoff UI collects this from the end user.

    vin string

    Possible values: <= 32 characters

    Vehicle VIN. Preferred identifier — when present we look up or create the Vehicle by VIN.

    licensePlate string

    Possible values: <= 16 characters

    Vehicle license plate. Fallback identifier; requires licensePlateState.

    licensePlateState string

    Possible values: Value must match regular expression ^$|[A-Za-z]{2}

    State that issued the license plate. Required when licensePlate is supplied.

    themeOverride

    object

    Optional per-link theme overrides. Each field overrides the minting partner's DataBuyer theme default for this handoff only.

    name string

    Possible values: <= 120 characters

    Brand display name shown in the standalone header.

    logo string

    Possible values: <= 2048 characters, Value must match regular expression ^https://.*

    Brand logo URL (https).

    primaryColor string

    Possible values: Value must match regular expression ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$

    Primary color (hex).

    secondaryColor string

    Possible values: Value must match regular expression ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$

    Secondary color (hex).

    accentColor string

    Possible values: Value must match regular expression ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$

    Accent color (hex).

    fontFamily string

    Possible values: Value must match regular expression ^[\w \-,'"]{1,120}$

    Font family token (letters, digits, spaces, comma, hyphen, quotes only).

    radius string

    Possible values: Value must match regular expression ^\d{1,3}(px|rem|em|%)$

    Corner radius token.

    mode string

    Possible values: Value must match regular expression embedded|standalone

    Optional presentation hint for the handoff UI. 'embedded' renders chromeless (for display inside the partner's own app); 'standalone' renders a brand header. If omitted, the UI auto-detects (iframe → embedded, else standalone).

    attribution

    object

    Optional free-text UTM attribution tags for analytics. Never used for identity or contributor resolution.

    utmSource string

    Possible values: <= 128 characters

    utm_source — marketing source tag.

    utmMedium string

    Possible values: <= 128 characters

    utm_medium — marketing medium tag.

    utmCampaign string

    Possible values: <= 256 characters

    utm_campaign — marketing campaign tag.

Responses​

Handoff URL generated.

Schema

    url string

    Ownli-hosted handoff URL. Short-lived — render and use within the user's session.

Loading...