home / skills / cleanexpo / ato / abn_entity_lookup

abn_entity_lookup skill

This skill validates ABNs and retrieves entity details from ABR to support compliance, payroll, and tax rate decisions.

npx playbooks add skill cleanexpo/ato --skill abn_entity_lookup

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

5.6 KB

---
name: abn-entity-lookup
description: Validates Australian Business Numbers (ABN) and retrieves entity details from the Australian Business Register (ABR) for compliance verification
---

# ABN Entity Lookup Skill

Queries the Australian Business Register (ABR) to validate ABNs, retrieve entity names, determine entity types, check GST registration status, and verify active/cancelled status. Essential for contractor deeming analysis, payroll tax compliance, and entity type determination.

## When to Use

- Validating a contractor's ABN before classifying payments
- Determining entity type (company, trust, sole trader, partnership) for tax rate selection
- Checking GST registration status for input tax credit eligibility
- Verifying ABN is active (not cancelled) before processing payments
- Populating entity details for new Xero organisation connections
- Cross-referencing Xero contact ABNs for data quality checks

## ABR API Configuration

### Endpoint

```
https://abr.business.gov.au/abrxmlsearch/AbrXmlSearch.asmx/ABRSearchByABN
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `searchString` | Yes | 11-digit ABN |
| `includeHistoricalDetails` | No | `Y` or `N` (default `N`) |
| `authenticationGuid` | Yes | ABR API GUID from env `ABR_GUID` |

### Alternative Endpoints

| Endpoint | Use Case |
|----------|----------|
| `ABRSearchByABN` | Lookup by ABN (primary) |
| `ABRSearchByASIC` | Lookup by ACN (9-digit) |
| `ABRSearchByName` | Search by entity name (fuzzy) |
| `ABRSearchByNameAdvanced` | Search with state/postcode filters |

## ABN Validation Rules

### Format Validation (Client-Side)

1. Must be exactly 11 digits
2. Apply ABN weighting algorithm:
   - Subtract 1 from the first digit
   - Multiply each digit by its weighting factor: [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
   - Sum the products
   - Result must be divisible by 89

### Example Validation

```
ABN: 51 824 753 556
Step 1: Subtract 1 from first digit → [4, 1, 8, 2, 4, 7, 5, 3, 5, 5, 6]
Step 2: Multiply by weights →          [40, 1, 24, 10, 28, 63, 55, 39, 75, 85, 114]
Step 3: Sum = 534
Step 4: 534 / 89 = 6.0 (exactly divisible) → VALID
```

## Entity Type Mapping

ABR returns entity type codes that map to tax treatment:

| ABR Entity Type | Code | Tax Rate | Amendment Period | Payroll Tax Grouping |
|----------------|------|----------|-----------------|---------------------|
| Australian Private Company | PRV | 25%/30% | 4 years | Related body corporate |
| Australian Public Company | PUB | 30% | 4 years | Related body corporate |
| Individual/Sole Trader | IND | Marginal rates | 2 years | N/A |
| Family Trust | TRT | Trustee rates | 4 years | Tracing provisions |
| Unit Trust | TRT | Trustee rates | 4 years | Tracing provisions |
| Partnership | PTR | Partner rates | 4 years | Common employees |
| SMSF | SMF | 15%/0% | 4 years | N/A |
| Government Entity | GOV | Exempt | N/A | Exempt |
| Non-Profit | NPF | Varies | 4 years | Charitable exemption |

## Response Data Extraction

### Key Fields

| Field | Path | Use |
|-------|------|-----|
| Entity Name | `businessEntity/mainName/organisationName` | Display name |
| Entity Type | `businessEntity/entityType/entityTypeCode` | Tax rate selection |
| ABN Status | `businessEntity/ABN/isCurrentIndicator` | Active check |
| GST Registered | `businessEntity/goodsAndServicesTax/effectiveFrom` | Input tax credit |
| GST Status | `businessEntity/goodsAndServicesTax/isCurrentIndicator` | Current registration |
| State | `businessEntity/mainBusinessPhysicalAddress/stateCode` | Payroll tax jurisdiction |
| Postcode | `businessEntity/mainBusinessPhysicalAddress/postcode` | Location verification |
| ACN | `businessEntity/ASICNumber` | Company cross-reference |

## Output Format

```xml
<abn_lookup_result>
  <abn>51824753556</abn>
  <abn_valid>true</abn_valid>
  <abn_active>true</abn_active>
  <entity_name>Example Pty Ltd</entity_name>
  <entity_type>Australian Private Company</entity_type>
  <entity_type_code>PRV</entity_type_code>
  <gst_registered>true</gst_registered>
  <gst_effective_from>2015-07-01</gst_effective_from>
  <state>NSW</state>
  <postcode>2000</postcode>
  <acn>824753556</acn>

  <tax_implications>
    <corporate_tax_rate>0.25</corporate_tax_rate>
    <!-- Base rate entity test required (passive income <80%) -->
    <amendment_period_years>4</amendment_period_years>
    <payroll_tax_grouping_risk>related_body_corporate</payroll_tax_grouping_risk>
  </tax_implications>

  <lookup_metadata>
    <source>ABR API</source>
    <queried_at>2026-02-13T10:00:00+11:00</queried_at>
    <cache_ttl_hours>24</cache_ttl_hours>
  </lookup_metadata>
</abn_lookup_result>
```

## Privacy Considerations

- ABR data is **public information** — no consent required for lookup
- However, **caching** ABR responses containing sole trader names has privacy implications under APP 11
- Sole trader lookups return individual names — handle with same care as personal information
- Cache ABR responses for 24 hours maximum, then re-query
- RLS policies on `abn_lookup_cache` table must restrict access to authenticated users only

## Best Practices

- **Always validate ABN format** client-side before making API call
- **Cache responses** for 24 hours to reduce ABR API load
- **Handle ABN not found** gracefully — entity may have recently registered or cancelled
- **Check GST status** separately from ABN status — ABN can be active with cancelled GST
- **Entity type determines** tax rate, amendment period, and payroll tax grouping — always extract
- **Rate limit** ABR API calls — no published limit but be respectful (max 1 req/second)

Overview

This skill validates Australian Business Numbers (ABNs) and retrieves authoritative entity details from the Australian Business Register (ABR) for compliance, payroll tax, and contractor classification workflows. It combines client-side ABN format checks with ABR API lookups to return entity name, type, GST status, active/cancelled state, and jurisdictional data. The output is designed for integration into onboarding, payroll, and accounting systems.

How this skill works

The skill first runs a local ABN format and checksum validation (11 digits + weighting algorithm). If valid, it calls the ABRSearchByABN endpoint using an authentication GUID and optional historical flag. It extracts key fields such as entity name, entity type code, ABN active indicator, GST registration and effective dates, state/postcode, and ACN, then formats a concise compliance-ready response.

When to use it

Validate a contractor's ABN before payroll or payment classification
Determine entity type for corporate tax, trust, or partnership treatment
Check GST registration and effective dates for input tax credit eligibility
Verify the ABN is active (not cancelled) before processing payments
Populate entity details when connecting a new organisation in accounting software

Best practices

Always perform client-side ABN format and weighting checksum before calling the ABR API
Cache ABR responses for up to 24 hours to reduce API requests and respect rate limits
Treat sole trader results as personal information and apply access controls and short cache TTLs
Handle ABN-not-found and cancelled statuses gracefully in UI and workflows
Extract and map entityTypeCode to tax/treatments and payroll-tax grouping rules

Example use cases

Pre-payroll validation to block payments to cancelled ABNs
Automated contractor onboarding that sets tax treatment by entity type
Cross-referencing Xero contact ABNs to improve data quality before reporting
Determining GST registration windows when assessing input tax credits
Building compliance dashboards that surface amendment periods and payroll-tax grouping risks

FAQ

Do I need consent to query the ABR?

No. ABR data is public and can be queried without individual consent, but cached personal data (e.g., sole trader names) must be handled under privacy controls.

What client-side checks should I run before the API call?

Validate the ABN is exactly 11 digits and passes the ABN weighting checksum (subtract 1 from first digit, multiply by weights, sum divisible by 89).

How long should I cache results?

Cache responses for up to 24 hours; reduce cache time for sole trader records to limit privacy exposure.