Skip to main content

Generate a marketplace handoff URL for a vendor

POST 
/api/marketplace/links/:vendorSlug

Returns an Ownli-hosted handoff URL for the given vendor. 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 either with an Authorization: Bearer token from POST /api/auth/token or with the legacy PartnerId/ClientId/ClientSecret headers. 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.

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 entry points: in addition to concrete vendor slugs, category-level slugs (for example insurance) are supported. These defer vendor selection — the end user is matched to the best vendor in the category during the handoff flow.

Request​

Path Parameters

    vendorSlug stringrequired

    Vendor identifier issued by Ownli at integration time. Either a concrete vendor slug (e.g. acme-warranty) or a category-level entry point (e.g. insurance) that defers vendor selection to 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.

    state string

    Possible values: >= 2 characters and <= 2 characters

    End-user state (2-letter US code). Most vendors require this for eligibility.

    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: >= 2 characters and <= 2 characters

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

Responses​

Handoff URL generated.

Schema

    url string

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

Loading...