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.

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.