# ABR (Australian Business Register) Integration

## Overview

RateRight uses the ABR API to verify contractor business registrations during signup. This document explains the implementation, configuration, and future enhancements.

## Current Implementation Status

| Feature | Status | Notes |
|---------|--------|-------|
| ABN Validation (checksum) | ✅ Complete | Local validation, no API needed |
| ABR Lookup (company data) | ⚠️ Requires GUID | Free API, registration required |
| ASIC Director Verification | 🔄 Stub only | Requires paid ASIC Connect subscription |
| Manual Review Flagging | ✅ Complete | All signups flagged for review |

## Configuration

### Environment Variables

```env
# Required: ABR Web Services GUID
# Register FREE at: https://abr.business.gov.au/Tools/WebServices
ABR_GUID=your-guid-here

# Optional: Enable development mode (returns mock data when GUID not configured)
ABR_DEV_MODE=true
```

### Getting Your ABR GUID

1. Visit https://abr.business.gov.au/Tools/WebServices
2. Click "Register for web services"
3. Fill in the registration form (business details, intended use)
4. Wait for email approval (usually 1 business day)
5. Copy the GUID from the approval email
6. Add to `.env.local`: `ABR_GUID=your-guid-here`

## API Endpoints

### GET /api/abn-lookup

Looks up company details from ABR.

**Query Parameters:**
- `abn` (required): 11-digit ABN (spaces allowed)
- `email` (optional): User email for director verification

**Response (Success):**
```json
{
  "success": true,
  "data": {
    "name": "COMPANY PTY LTD",
    "abn": "51 824 753 556",
    "status": "Active",
    "statusDate": "2020-01-01",
    "state": "NSW",
    "postcode": "2000",
    "type": "Australian Private Company",
    "typeCode": "PRV",
    "gstRegistered": true,
    "acn": "123456789",
    "directorVerification": {
      "status": "pending",
      "message": "Director verification requires manual review",
      "requiresManualReview": true
    }
  }
}
```

**Response (Development Mode):**
```json
{
  "success": true,
  "data": { ... },
  "devMode": true
}
```

**Response (Error):**
```json
{
  "success": false,
  "error": "Invalid ABN format"
}
```

## ABN Validation

ABN validation uses the official modulus-89 checksum algorithm:

1. Subtract 1 from the first digit
2. Multiply each digit by its weight: [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
3. Sum all products
4. If sum % 89 === 0, ABN is valid

**Test ABNs:**
- `51 824 753 556` - Valid (passes checksum)
- `51 824 753 557` - Invalid (fails checksum)
- `34 241 177 887` - Valid (suppressed on ABR)

## Director Verification (Future)

Currently, all company signups are flagged for manual review. Future implementation will use ASIC Connect API:

1. Extract ACN from ABR response
2. Call ASIC Connect API to get director list
3. Cross-reference user email/name with director records
4. Auto-verify if match found
5. Flag for manual review if no match

**ASIC Connect:** https://connectonline.asic.gov.au/
- Requires paid subscription
- Provides director/officeholder data
- Rate-limited API access

## Development Mode

When `ABR_DEV_MODE=true` or `NODE_ENV=development` and no valid GUID is configured:

1. ABN validation still works (local checksum)
2. Lookup returns mock company data
3. Company names include "(Dev Mode)" suffix
4. Director verification shows "not_available" status

This allows development and testing without ABR registration.

## Files Modified

### rateright-v2
- `src/app/api/abn-lookup/route.ts` - API route with ABR integration
- `src/lib/abn-utils.ts` - ABN validation utilities
- `src/app/contractor/signup/page.tsx` - Signup flow using API
- `.env.local` - Environment configuration

### the-50-dollar-app
- `src/app/api/abn-lookup/route.ts` - API route (identical)
- `src/lib/abn-utils.ts` - ABN validation utilities
- `src/app/contractor/signup/page.tsx` - Signup flow using API
- `.env.local` - Environment configuration

## Next Steps

1. **Immediate:** Register for ABR GUID at https://abr.business.gov.au/Tools/WebServices
2. **This week:** Configure production environment with real GUID
3. **Future:** Implement ASIC Connect for director verification
4. **Future:** Build admin UI for manual review queue

## Security Considerations

- ABR GUID stored in environment variables (not in code)
- ABN validation prevents invalid inputs from reaching API
- All signups flagged for manual review until director verification implemented
- Rate limiting should be added for production

---

*Last updated: February 2025*