VECU Custody .NET SDK

A .NET SDK for managing vehicle custody permits, transfers, and compliance tracking. Built with async-by-default patterns and native dependency injection support for modern .NET applications.

Version 3.0.0

The .NET SDK has reached v3.0.0. Breaking: RecordTransferAsync, GetCustodyStatusAsync, and GetCustodyChainAsync have been removed pending server-side BOLA controls. HTTP 403 responses are now classified as ForbiddenException / RouteNotAvailableException instead of NetworkException. See the Changelog for the full migration guide.

Features

Dependency Injection - Native AddCustodyClient() registration for ASP.NET Core and hosted services
Async-by-Default - All methods return Task for optimal performance
4 Environments - Sandbox, NonProd, PreProd, Production (all use TokenProvider)
Built-in Retry Policies - Polly-based exponential backoff for transient failures
Mock Client - Built-in MockCustodyServiceClient for testing without real API calls
Strongly Typed Exceptions - 10+ typed exceptions for precise error handling
Configuration-Based - Configure via appsettings.json, user secrets, or environment variables

Quick Links

Quick Start Guide - Get started in minutes
Installation - Setup and configuration
Configuration - Client options and environment presets
ASP.NET Core Integration - Minimal APIs, controllers, background services
API Reference - Complete API documentation

Quick Start

using CoxAuto.Vecu.CustodySdk.DependencyInjection;
using CoxAuto.Vecu.CustodySdk.Client;
using CoxAuto.Vecu.CustodySdk.Models.Enums;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

// Configure services
var host = Host.CreateDefaultBuilder()
    .ConfigureServices((context, services) =>
    {
        services.AddCustodyClient(options =>
        {
            options.Environment = CustodyEnvironment.Sandbox;
            options.TokenProvider = async (ct) =>
            {
                var token = await myAuthClient.GetTokenAsync(ct);
                return token.AccessToken;
            };
        });
    })
    .Build();

// Get client from DI
var client = host.Services.GetRequiredService<ICustodyServiceClient>();

// Create an authorization for vehicle custody
var authorization = await client.CreateAuthorizationAsync(new()
{
    Vin = "9HGBH41JXMN999999",
    Origin = "1 Auction Blvd, Bordentown, NJ 08505",
    Destination = "200 Motor Ave, Columbus, OH 43230",
    PersonIdentityKey = "DL-293-847-561",
    MakeModel = "Honda Accord",
    AuthorizedBy = "system-integration",
    Role = AuthorizationRole.DRIVER
});

Console.WriteLine($"Created: {authorization.AuthorizationId}");
Console.WriteLine($"Status: {authorization.Status}");

// Check if vehicle is releasable
var result = await client.GetReleasabilityAsync(
    "9HGBH41JXMN999999",
    origin: "1 Auction Blvd, Bordentown, NJ 08505");

Console.WriteLine($"Releasable: {result.IsReleasable}");

API Resources

The SDK provides access to 3 resource groups:

Resource	Methods	Purpose
Custody Permits	4	Create, get, wait for, and cancel custody permits
Releasability	2	Query and update vehicle releasability status
Release	1	Record vehicle releases from custody

API Terminology

In documentation, we use "Custody Permits" to describe permissions for vehicle custody. The underlying API methods are named with Authorization (e.g., CreateAuthorizationAsync()). This distinction avoids confusion with API authentication.

Requirements

.NET 8.0 or .NET 10
Access to Cox Automotive Artifactory (NuGet registry)

Installation

# Install via .NET CLI
dotnet add package CoxAuto.Vecu.CustodySdk

# Or via Package Manager Console
Install-Package CoxAuto.Vecu.CustodySdk

Artifactory Required

The SDK is hosted in Cox Automotive's Artifactory. See Installation Guide for NuGet source configuration.

Next Steps

Follow the Quick Start Guide for a step-by-step tutorial
Review Configuration options
Learn about ASP.NET Core Integration patterns
Explore Error Handling strategies
Browse the API Reference

Vehicle Custody