Releasability

Query and update vehicle releasability status based on origin location context.

Overview

Releasability operations determine if a vehicle can be released from custody at a given origin. The service evaluates:

• Origin Location: Geocoded address or coordinates for the release point
• Blockers: Reasons preventing release (empty when releasable)
• Source: Whether data came from cache or was not available

Methods

get()

Get the releasability status for a vehicle at a specific origin.

Returns: ReleasabilityResponse

Raises: ValidationError, AuthenticationError, ServiceUnavailableError

Example:

from vecu_custody import CustodyClient

client = CustodyClient.sandbox(token="your-jwt-token")

status = client.releasability.get(
    "1HGBH41JXMN109186",
    origin="1180 Lake Hearn Dr NE, Atlanta, GA 30342"
)

if status.is_releasable:
    print(f"Vehicle is releasable (source: {status.source})")
else:
    print("Cannot release. Blockers:")
    for blocker in status.blockers:
        print(f"  - {blocker}")

# Check geocoded origin
if status.origin_location:
    loc = status.origin_location
    print(f"Geocoded: {loc.formatted_address}")
    print(f"Coordinates: {loc.lat}, {loc.lng}")
    print(f"Geohash: {loc.geohash}")

update()

Update the releasability status for a vehicle.

Returns: UpdateReleasabilityResponse

Raises: ValidationError, AuthenticationError, ServiceUnavailableError

Example:

from datetime import datetime, timezone
from vecu_custody import CustodyClient

client = CustodyClient.sandbox(token="your-jwt-token")

# Update a vehicle as releasable
result = client.releasability.update(
    "1HGBH41JXMN109186",
    origin_address="1180 Lake Hearn Dr NE, Atlanta, GA 30342",
    releasable=True,
    detected_at=datetime.now(timezone.utc),
)

print(f"Updated: {result.message}")
print(f"VIN: {result.vin}")
print(f"Origin geohash: {result.origin_geohash}")

# Update a vehicle as NOT releasable
result = client.releasability.update(
    "1HGBH41JXMN109186",
    origin_address="33.8463,-84.3621",
    releasable=False,
    detected_at=datetime.now(timezone.utc),
    blockers=["Payment not cleared", "Title hold"]
)

Response Objects

ReleasabilityResponse

Returned by get().

OriginLocation

Geocoded origin location returned in the response.

UpdateReleasabilityResponse

Returned by update().

Common Use Cases

Pre-Transfer Check

from vecu_custody import CustodyClient

client = CustodyClient.sandbox(token="your-jwt-token")

def can_initiate_transfer(vin: str, origin: str) -> tuple[bool, str]:
    """Check if vehicle transfer can be initiated."""
    status = client.releasability.get(vin, origin=origin)

    if status.is_releasable:
        return True, "Ready for transfer"

    blocker_msg = ", ".join(status.blockers)
    return False, f"Blocked: {blocker_msg}"

# Usage
can_transfer, message = can_initiate_transfer(
    "1HGBH41JXMN109186",
    origin="1180 Lake Hearn Dr NE, Atlanta, GA 30342"
)
print(message)

Releasability Status Report

status = client.releasability.get(
    "1HGBH41JXMN109186",
    origin="1180 Lake Hearn Dr NE, Atlanta, GA 30342"
)

print(f"Releasability Report for VIN: {status.vin}")
print(f"Status: {'RELEASABLE' if status.is_releasable else 'BLOCKED'}")
print(f"Source: {status.source}")
print(f"Checked at: {status.checked_at}\n")

if not status.is_releasable:
    print("Blockers:")
    for i, blocker in enumerate(status.blockers, 1):
        print(f"  {i}. {blocker}")

if status.origin_location:
    loc = status.origin_location
    print(f"\nOrigin: {loc.formatted_address or loc.address}")
    print(f"Geohash: {loc.geohash}")

Record Releasability After Inspection

from datetime import datetime, timezone

# After an inspection confirms vehicle is ready for release
result = client.releasability.update(
    "1HGBH41JXMN109186",
    origin_address="1180 Lake Hearn Dr NE, Atlanta, GA 30342",
    releasable=True,
    detected_at=datetime.now(timezone.utc),
    release_id="REL-2026-0042"
)

print(f"Releasability recorded: {result.message}")
print(f"Origin geohash: {result.origin_geohash}")

Error Handling

from vecu_custody import CustodyClient
from vecu_custody.exceptions import (
    NotFoundError,
    ValidationError,
    AuthenticationError,
    ServiceUnavailableError
)

client = CustodyClient.sandbox(token="your-jwt-token")

try:
    status = client.releasability.get(
        "1HGBH41JXMN109186",
        origin="1180 Lake Hearn Dr NE, Atlanta, GA 30342"
    )
    print(f"Releasable: {status.is_releasable}")
except ValidationError as e:
    print(f"Invalid parameters: {e.message}")
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except ServiceUnavailableError as e:
    print(f"Service unavailable: {e.message}")

Next Steps

• Custody Permits - Create permits for releasable vehicles
• Transfers - Initiate transfers after confirming releasability