Kipany.VP.Client 1.0.6

Kipany.VP.Client

Official .NET client SDK for the Kipany Verification Portal API. Handles authentication, call record submission, and S3 recording uploads.

Installation

dotnet add package Kipany.VP.Client

Configuration

All four values below are provided by Kipany — contact Kipany to obtain them before integrating.

Add the following to your appsettings.json:

{
  "Kipany": {
    "IdentityUrl": "<provided by Kipany>",
    "VerificationPortalUrl": "<provided by Kipany>",
    "Email": "<provided by Kipany>",
    "Password": "<provided by Kipany>"
  }
}

Register the client in your Program.cs or Startup.cs:

using Kipany.VerificationPortal.Client;

services.AddKipanyVerificationPortalClient(options =>
{
    options.IdentityBaseUrl           = configuration["Kipany:IdentityUrl"]!;
    options.VerificationPortalBaseUrl = configuration["Kipany:VerificationPortalUrl"]!;
    options.Email                     = configuration["Kipany:Email"]!;
    options.Password                  = configuration["Kipany:Password"]!;
});

Token caching is automatic. The SDK obtains a Bearer token on the first API call and reuses it until 30 seconds before it expires. You never need to manage tokens manually.

Usage

Inject ICallRecordService and IStorageService wherever you need them.

Create a single call record

using Kipany.VerificationPortal.Client.CallRecords;
using Kipany.VerificationPortal.Client.Models.Requests;

public class MyService(ICallRecordService callRecords)
{
    public async Task SubmitAsync()
    {
        var result = await callRecords.CreateCallRecordAsync(new CreateCallRecordRequest
        {
            CallId            = "CALL-001",
            AgentName         = "Jane Smith",
            AgentId           = "AGT-42",
            CallDate          = new DateOnly(2026, 8, 27),
            CallTime          = new TimeOnly(14, 30, 0),
            CallTimezone      = "UTC",
            OutcomeCode       = "Sale",
            ExternalLeadId    = "LEAD-999",
            CustomerRef       = "CUST-123",
            PhoneNumber       = "5551234567",
            CampaignCode      = "CAMP-A",
            CampaignType      = "Insurance",
            VerificationNotes = "Customer confirmed.",
            DateCreated       = DateTime.UtcNow,
            ProductCodes      = ["PROD-001"],
            Recordings =
            [
                new RecordingRequest
                {
                    RecordingName     = "call-001.mp3",
                    RecordingFormat   = "mp3",
                    RecordingDuration = TimeSpan.FromMinutes(4),
                    RecordingSizeBytes = 2_048_000,
                    SequenceNumber    = 1
                }
            ]
        });

        Console.WriteLine($"Created: {result.CallRecordId}");
    }
}

Create multiple call records (bulk)

var results = await callRecords.CreateCallRecordsAsync(
[
    new CreateCallRecordRequest { CallId = "CALL-002", /* ... */ },
    new CreateCallRecordRequest { CallId = "CALL-003", /* ... */ }
]);

foreach (var item in results.CallRecordList)
    Console.WriteLine($"{item.CallId} → {item.CallRecordId}");

Upsert recordings on an existing call record

await callRecords.UpsertRecordingsAsync(new UpsertRecordingsRequest
{
    KipanyId   = Guid.Parse("existing-kipany-id"),
    Recordings =
    [
        new RecordingRequest
        {
            RecordingName      = "call-001-part2.mp3",
            RecordingFormat    = "mp3",
            RecordingDuration  = TimeSpan.FromMinutes(2),
            RecordingSizeBytes = 1_024_000,
            SequenceNumber     = 2
        }
    ]
});

Get a call record by ID

var detail = await callRecords.GetCallRecordAsync(callRecordId);

Console.WriteLine($"Agent: {detail.AgentName}");
Console.WriteLine($"Recordings: {detail.Recordings.Count}");

Get presigned S3 URLs for recordings

var urls = await callRecords.GetPresignedUrlsAsync(callRecordId);

foreach (var url in urls)
    Console.WriteLine($"[{url.SequenceNumber}] {url.RecordingName} → {url.PresignedS3}");

Upload a recording to S3

Use the presigned URL from GetPresignedUrlsAsync together with the local file path.

using Kipany.VerificationPortal.Client.Storage;

public class MyUploader(ICallRecordService callRecords, IStorageService storage)
{
    public async Task UploadAsync(Guid callRecordId, string localFilePath)
    {
        var urls = await callRecords.GetPresignedUrlsAsync(callRecordId);
        var target = urls.First(); // pick by SequenceNumber if multiple

        bool uploaded = await storage.UploadRecordingAsync(target.PresignedS3, localFilePath);
        Console.WriteLine(uploaded ? "Upload succeeded." : "Upload failed.");
    }
}

Error handling

All methods throw KipanyClientException on failure. It exposes an optional StatusCode property with the HTTP status code when available.

using Kipany.VerificationPortal.Client.Exceptions;

try
{
    var result = await callRecords.CreateCallRecordAsync(request);
}
catch (KipanyClientException ex) when (ex.StatusCode == 401)
{
    // Credentials rejected — check Email / Password
}
catch (KipanyClientException ex)
{
    Console.WriteLine($"Kipany error: {ex.Message} (HTTP {ex.StatusCode})");
}

Notes

• Authentication — The SDK calls POST /api/v1/auth/login automatically with the configured Email/Password. Tokens are cached and refreshed 30 seconds before expiry. No manual token management required.
• CancellationToken — Every method accepts an optional CancellationToken for cooperative cancellation.
• S3 uploads — Presigned URLs are short-lived (typically 60 minutes). Obtain them immediately before uploading.
• Bulk endpoint — CreateCallRecordsAsync processes each record independently; partial success is possible. Check CallRecordList in the response for per-record results.