Universal.AustralianBusinessRegister 1.6.1

Universal.AustralianBusinessRegister

A .NET client library for interacting with the Australian Business Register (ABR) web services to search for Australian Business Numbers (ABN) and Australian Company Numbers (ACN).

Getting Started

Authentication

Register for free access at the ABN Lookup web services registration page. Accept the web services agreement and complete the registration form. ABN Lookup will email your authentication GUID after processing your application. Pass that GUID to AustralianBusinessRegisterClient.

Search by ABN

using Universal.AustralianBusinessRegister;

// Using default authentication GUID
using (var client = new AustralianBusinessRegisterClient())
{
    var results = await client.SearchABNAsync("50616294781");
    Console.WriteLine($"ABN: {results.Response.BusinessEntity.ABN.IdentifierValue}");
    Console.WriteLine($"Name: {results.Response.BusinessEntity.MainNames[0].OrganisationName}");
}

// Using custom authentication GUID
using (var client = new AustralianBusinessRegisterClient("your-auth-guid-here"))
{
    var results = await client.SearchABNAsync("50616294781");
    // Process results...
}

Search by ACN

using (var client = new AustralianBusinessRegisterClient())
{
    var results = await client.SearchACNAsync("010249966");
    Console.WriteLine($"ACN: {results.Response.BusinessEntity.ASICNumber}");
    Console.WriteLine($"Name: {results.Response.BusinessEntity.MainNames[0].OrganisationName}");
}

Search by Name

using (var client = new AustralianBusinessRegisterClient())
{
    // Basic name search
    var results = await client.SearchNameAsync("Commonwealth Bank");
    
    // Advanced name search with options
    var options = new NameSearchOptions
    {
        Postcode = "2000",
        LegalName = true,
        TradingName = true,
        BusinessName = true,
        ActiveABNsOnly = true,
        NewSouthWales = true,
        SearchWidth = NameSearchOptions.SearchWidths.Typical,
        MinimumScore = 50,
        MaximumSearchResults = 100
    };
    
    var results = await client.SearchNameAsync("Commonwealth Bank", options);
    
    foreach (var entity in results.Response.BusinessEntity)
    {
        Console.WriteLine($"ABN: {entity.ABN.IdentifierValue}");
        Console.WriteLine($"Name: {entity.MainNames[0].OrganisationName}");
    }
}

Include Historical Details

// Include historical details (default: true)
var results = await client.SearchABNAsync("50616294781", includeHistoricalDetails: true);

// Exclude historical details
var results = await client.SearchABNAsync("50616294781", includeHistoricalDetails: false);

When history is included, use BusinessEntity.ABNs, EntityStatuses, and GoodsAndServicesTaxes to access all returned entries. The existing singular properties (ABN, EntityStatus, and GoodsAndServicesTax) return the first entry for compatibility.

Name-search results expose the matching name through MainName, LegalName, BusinessName, MainTradingName, or OtherTradingName, depending on the name type ABR matched. Individual legal names expose FullName, GivenName, OtherGivenName, and FamilyName; organisation names expose OrganisationName. Plural properties retain multiple entries where the service returns them. A result does not necessarily contain a business name or trading name.

ABR returns "No records found" as an application exception with code Search, even when HTTP succeeds. Search methods preserve this as HttpException<ABRPayloadSearchResults.ExceptionSection>; inspect Content.ExceptionCode and Content.ExceptionDescription when handling it. Other errors, such as invalid authentication, use the same exception type with different payload details.

Working with ABN Bulk Extracts

Download Bulk Extract ZIP Archives

using (var client = new AustralianBusinessRegisterClient())
{
    // Download as streams
    await foreach (Stream zipStream in client.DownloadABNBulkExtractsAsync())
    {
        // Process each ZIP archive stream
    }
    
    // Save ZIP archives to disk
    await client.SaveABNBulkExtractsAsync("C:\\ABN\\Downloads");
}

Download and Extract Individual Files

using (var client = new AustralianBusinessRegisterClient())
{
    // Download and extract files as streams
    await foreach (Stream fileStream in client.DownloadABNBulkExtractFilesAsync())
    {
        // Process each extracted XML file stream
    }
    
    // Save extracted files to disk
    await client.SaveABNBulkExtractFilesAsync("C:\\ABN\\Extracts");
}

Parse Bulk Extract Files

using (var client = new AustralianBusinessRegisterClient())
{
    // Parse a ZIP archive
    using (FileStream zipStream = File.OpenRead("abn-bulk-extract.zip"))
    {
        foreach (Transfer transfer in client.ParseABNBulkExtractArchive(zipStream))
        {
            // Process transfer data
            foreach (var abn in transfer.ABR)
            {
                Console.WriteLine($"ABN: {abn.ABN}");
            }
        }
    }
    
    // Parse an individual XML file
    using (FileStream xmlStream = File.OpenRead("abn-extract.xml"))
    {
        Transfer transfer = client.ParseABNBulkExtractFile(xmlStream);
        // Process transfer data
    }
}

Exception Handling

using Universal.Common.Net.Http;

try
{
    var results = await client.SearchABNAsync("50616294781");
}
catch (HttpException<ABRPayloadSearchResults.ExceptionSection> ex)
{
    Console.WriteLine($"Error: {ex.Content.ExceptionDescription}");
}