Citizenship provides easy validations on personal documents, addresses, bank account numbers and other personal information, in Portugal.
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Join the chat at

Gem Version Build Status Code Climate Dependency Status security Coverage Status

Citizenship provides a set of easy validations on personal documents, addresses, bank account numbers and other personal information, of Portuguese citizens or of citizens living in Portugal ;)

It supports validation of:

  • NIB (i.e. "banking account number")
  • NIF (i.e. "fiscal number")
  • local phone numbers
  • identification card ('bilhetes de identidade'), were the old id Portuguese id documents. They are no longer issue, but many haven't yet expired, so are still used alongside the Citizen Card.
  • citizen card ('cartão do cidadão'), are the new ID cards currently in use
  • zip code (partial validation)
  • e-mail (well, just because :) )


Add this line to your Rails application's Gemfile:

gem 'citizenship'

And then execute:

$ bundle

Or install it yourself as:

$ gem install citizenship

and use it standalone.



result=Citizenship.valid_nib?("003503730000539151280") # returns true
result=Citizenship.valid_nib?('0035.03730000539.1512.80') # returns true
result=Citizenship.valid_nib?('38476129847') # returns false (since it fails proper size and CRC)
result=Citizenship.valid_nib?('0035.03730000539.1512.80', strict: true) # returns false
Citizenship.valid_nib!(nib) # raises Citizenship::Error if invalid


result=Citizenship.valid_nif?("123456789") # returns true
Citizenship.valid_nif!(nif) # raises Citizenship::Error if invalid
nif=Citizenship.valid_nif!("123456789") # returns "123456789"
result=Citizenship.valid_nif?(' 123456789', strict: true) # returns false (strict validation disallows whitespaces and others)

Phone Number

phone=Citizenship.valid_phone!('+351 96 933 2233', only_prefixes: ['93', '96']) # returns "+351 96 933 2233"
phone=Citizenship.valid_phone!('262-999-666') # returns "262-999-666"
result=Citizenship.valid_phone?('262999666', strict: true) # returns true
result=Citizenship.valid_phone?('+351 93 933 2233', allow_country_prefix: false) # returns false (since country prefix was used)
phone=Citizenship.valid_phone!('+351 93 933 2233') # returns "+351 93 933 2233"

Identification Card

result=Citizenship.valid_identification_card?('156 944 80', '4') # returns true
id=Citizenship.valid_identification_card!('156 944 8', '8') # returns '156 944 8'

Citizen Card

result=Citizenship.valid_citizen_card?('00000000 0 ZZ 4') # returns true
id=Citizenship.valid_citizen_card('00000000-0-ZZ-4') # returns '00000000-0-ZZ-4'

Zip Code

result=Citizenship.valid_zip_code?('1000-100') # returns true


result=Citizenship.valid_email?("") # returns true
result=Citizenship.valid_email?(" ") # returns false (due to whitespaces)
result=Citizenship.valid_email?("") # returns false (due to missing user)

Rails Validators

We provide a useful range of Rails validators that you can include in your models, namely:

  • NifValidator ("nif")
  • NibValidator ("nib")
  • PhoneValidator ("phone")
  • EmailValidator ("email")
  • ZipCodeValidator ("zip_code")


class User < ActiveRecord::Base
  validates :fiscal_number, nif: true
  validates :mobile, phone: { allow_country_prefix: false }

Future Developments

  • Support full zip code validation
  • Support IBAN
  • Support validating documents for other EU countries



  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


Copyright © 2015 Runtime Revolution, released under the MIT license.

About Runtime Revolution

Runtime Revolution

Citizenship is maintained by Runtime Revolution. See our other projects and check out our blog for the latest updates.