A Ruby gem for interacting with the New Zealand Business Number (NZBN) API v5.
Add this line to your application's Gemfile:
gem 'nzbn-ruby'And then execute:
bundle installOr install it yourself as:
gem install nzbn-ruby- ...
Configure the gem with your NZBN API key (obtain from api.business.govt.nz):
require 'logger'
Nzbn.configure do |config|
config.api_key = 'your-api-key'
config.base_url = 'https://api.business.govt.nz/gateway/nzbn/v5' # default
config.timeout = 30 # optional, default 30 seconds
config.logger = Logger.new(STDOUT) # optional, enables request/response logging
endclient = Nzbn::Client.new
# Or with inline configuration
client = Nzbn::Client.new(api_key: 'your-api-key')# Search by name
results = client.entities.search(search_term: 'Company Name')
results.each do |entity|
puts "#{entity.entity_name} (#{entity.nzbn})"
end
# With filters
results = client.entities.search(
search_term: 'Wellington',
entity_status: 'Registered',
entity_type: 'NZCompany',
page: 0,
page_size: 20
)entity = client.entities.get(nzbn: '9429041925676')
puts entity.entity_name
puts entity.entity_status_description
puts entity.registration_date# Search for changes
changes = client.entities.changes(
change_event_type: 'ALL',
date_time_from: '2024-01-01T00:00:00',
date_time_to: '2024-12-31T23:59:59'
)# List addresses
addresses = client.addresses.list(nzbn: '9429041925676')
# Add an address
new_address = client.addresses.create(
nzbn: '9429041925676',
address: {
addressType: 'POSTAL',
address1: '123 Main Street',
address2: 'Wellington',
postCode: '6011',
countryCode: 'NZ'
}
)# List roles (directors, partners, etc.)
roles = client.roles.list(nzbn: '9429041925676')
roles.each do |role|
puts "#{role.role_type}: #{role.role_person&.first_name} #{role.role_person&.last_name}"
endtrading_names = client.trading_names.list(nzbn: '9429041925676')# Create a watchlist for change notifications
watchlist = client.watchlists.create(watchlist: {
name: 'My Watchlist',
channel: 'EMAIL',
frequency: 'DAILY',
changeEventTypes: 'ALL',
adminEmailAddress: '[email protected]'
})
# Add NZBNs to watch
client.watchlists.add_nzbns(
watchlist_id: watchlist.watchlist_id,
nzbns: ['9429041925676', '9429000001234']
)
# List watchlists
my_watchlists = client.watchlists.list# Get privacy settings
settings = client.privacy_settings.get(nzbn: '9429041925676')
# Update privacy settings
client.privacy_settings.update(
nzbn: '9429041925676',
settings: { phonePrivateInformation: true }
)# Get company-specific details
company = client.company_details.get(nzbn: '9429041925676')
puts company.annual_return_filing_month
puts company.has_constitution_filed# Get historical data
historical_names = client.history.entity_names(nzbn: '9429041925676')
historical_addresses = client.history.addresses(nzbn: '9429041925676')begin
entity = client.entities.get(nzbn: 'invalid')
rescue Nzbn::NotFoundError => e
puts "Entity not found"
rescue Nzbn::AuthenticationError => e
puts "Invalid API key"
rescue Nzbn::ValidationError => e
puts "Invalid request: #{e.message}"
e.errors.each { |err| puts " #{err['field']}: #{err['message']}" }
rescue Nzbn::ApiError => e
puts "API error: #{e.message} (#{e.error_code})"
end| Resource | Description |
|---|---|
entities |
Search, get, create entities |
addresses |
Manage entity addresses |
roles |
Manage directors, partners, etc. |
trading_names |
Manage trading names |
phone_numbers |
Manage phone numbers |
email_addresses |
Manage email addresses |
websites |
Manage websites |
industry_classifications |
Manage ANZSIC codes |
privacy_settings |
Manage privacy settings |
company_details |
Get company/non-company details |
watchlists |
Manage change notification watchlists |
organisation_parts |
Manage OPN/GLN |
history |
Access historical data |
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.
bundle install
bundle exec rspecBug reports and pull requests are welcome on GitHub.
The gem is available as open source under the terms of the MIT License.