Check-ins and Rewards

Check-ins are how Ownli captures verifiable signals about a user's vehicle or residence. Each confirmed check-in can earn the user a reward, and confirmed rewards can be redeemed for products from a campaign catalog. This page describes the three check-in types, the lifecycle they share, how Ownli verifies them, and how rewards and redemptions flow from there.

Check-in types

Ownli supports three check-in types, each backed by its own set of endpoints under /api/vehicles/checkin and /api/users/checkin.

Type	Purpose	Create endpoint
Mileage	Capture a vehicle's current odometer reading, optionally with a license-plate photo, to track distance travelled over time.	Create a mileage check-in
Condition	Capture a visual snapshot of the vehicle's exterior from four required angles (plus four optional enhanced angles) so Ownli can evaluate condition and detect damage.	Create a condition check-in
Proof of Address	Verify a user's residence with a supporting document and, optionally, photos of the home.	Create a proof-of-address check-in

Check-in lifecycle

Every check-in, regardless of type, moves through the same state machine:

                      ┌──────────────┐
  POST /checkin  ───► │   Pending    │ ◄─────────┐
                      └──────┬───────┘           │
                             │  Ownli verification
                  ┌──────────┼──────────┐        │
                  ▼          ▼          ▼        │
          ┌────────────┐ ┌────────┐ ┌──────────┐ │ PUT /checkin/{id}
          │ Confirmed  │ │Declined│ │ On Hold  │─┘  (change flow)
          └────────────┘ └────────┘ └──────────┘
          (terminal ok) (terminal)  (awaiting more data)

• Pending — Initial state after a successful POST to a create-check-in endpoint. The check-in has been accepted but has not yet been verified.
• Confirmed — Terminal success state. Ownli has verified the check-in and it counts toward the user's history. Any associated reward becomes eligible for redemption at this point.
• Declined — Terminal failure state. Ownli rejected the check-in (see verification for reasons). Declined check-ins do not earn rewards.
• On Hold — Non-terminal state. Ownli has paused the check-in because it needs additional or better data (for example, a clearer odometer photo or a different angle for condition photos). Surface this to the user so they can provide the missing data; the partner then submits the updated data through the change flow described below.

Partners can inspect a check-in's current state with the per-type fetch and list endpoints (e.g. Fetch a check-in, Get condition check-ins).

Change flow (updating a check-in on hold)

When a check-in enters On Hold, the partner can update it — replacing or adding the data Ownli asked for — by calling the per-type update endpoint:

• Update a mileage check-in
• Update a condition check-in
• Update a proof of address check-in

Updates are only accepted while the check-in is On Hold. A confirmed or declined check-in is terminal and cannot be changed. After a successful update, the check-in returns to Pending and goes through verification again, ending in Confirmed, Declined, or back to On Hold if further data is still needed.

How Ownli verifies check-ins

All three check-in types are evaluated against two shared criteria:

• Fraud — signals that suggest the check-in was fabricated, replayed, or submitted from a suspicious source.
• Recency — the evidence must reflect the vehicle or residence as it exists now, not a stale capture.

Condition check-ins undergo an additional step:

• Damage analysis — Ownli inspects the submitted photos and flags any detected damage on the vehicle.

Verification is performed asynchronously after the POST. The check-in stays in Pending until verification completes and then transitions to Confirmed, Declined, or On Hold (when Ownli needs more data).

Rewards

A successful check-in creates a reward associated with the user and the check-in.

• A reward's state mirrors its check-in: while the check-in is Pending or On Hold, the reward is Pending; when the check-in becomes Confirmed, the reward becomes Confirmed and is eligible for redemption. A Declined check-in yields no usable reward.
• What counts as a reward, and its value, are configured in campaigns that Ownli sets up offline in partnership with the data buyer. The API exposes rewards but not the campaign-definition surface — reach out to Ownli to create or modify a campaign.
• Rewards can be listed and inspected with Get rewards, Get rewards by user id, and Get confirmed rewards by user id.

Rewards from partner-side actions

Partners can also mint rewards directly for actions that happen in their own systems — a device purchase, an app migration, a referral their backend tracked — without going through a check-in. These are created via POST /api/rewards/grant from the partner's backend, land in Confirmed state immediately, and are claimable through the same redemption flow as check-in rewards. The endpoint takes a partner-supplied clientReference for safe retries and a free-form actionCode label for grouping. See the Integration Guide for the full flow.

Production access requires a commercial agreement

Partner-minted rewards are open in sandbox for development and testing. In production, this capability is enabled per partner under a commercial agreement with Ownli that covers budget prepayment and clawback terms — because each granted reward represents real value owed to the user. Contact Ownli to enable this on your production credentials before integrating it into a live flow.

Redemption

Confirmed rewards can be redeemed for products from the campaign catalog.

• The catalog of available products per campaign is also set up offline with Ownli. Partners can retrieve the current catalog with Get products.
• A user redeems by calling Claim rewards. Once claimed, the reward is settled into a payout representing the product or value the user is entitled to.
• Payouts can be inspected with Get payouts and Get payouts by user id.

Putting it together

A typical flow for a single check-in:

1. User performs the check-in (e.g. takes the four required photos for a condition check-in) and the partner uploads the photos via the Photo upload API.
2. Partner calls the relevant create-check-in endpoint. Response contains the check-in in Pending state.
3. Ownli runs fraud, recency, and (for condition check-ins) damage analysis asynchronously.
4. The check-in transitions to Confirmed, Declined, or On Hold. The associated reward follows the check-in's state.
5. If the check-in lands in On Hold, the partner prompts the user to supply the missing data and submits it via the appropriate update-check-in endpoint. The check-in returns to Pending and is re-verified.
6. Once a reward is Confirmed, the user claims it via Claim rewards and a payout is produced.