A Ruby wrapper for the FullContact API
Ruby
Clone or download
katiekeel Merge pull request #65 from fullcontact/update-faraday
Updated faraday gem version per customer request
Latest commit 564521d Jun 19, 2018
Permalink
Failed to load latest commit information.
lib
spec
.document
.gitignore
.rspec
.travis.yml
Gemfile
LICENSE.md
README.md
Rakefile
fullcontact.gemspec

README.md

FullContact Ruby Gem

A Ruby wrapper for the FullContact API

Build Status Gem Version Code Climate Test Coverage

Changes

  • 0.18.0
    • Add ability to query Company API by company name
    • Fix XML bug in Company API module
  • 0.17.0 - Upgrade Faraday plugin to ~> 0.11.0
  • 0.16.0 - Upgrade Faraday plugin to ~> 0.10.0.
  • 0.15.0 - Add header-based auth via config.auth_type = :header control.
  • 0.14.0 - Remove plissken gem to support Rails 5 (#42)
  • 0.13.0
    • Raise ArgumentError if query by Facebook ID/username is used.
    • Remove deprecated messages.
  • 0.12.0 - include_headers_in_response = true includes response headers in returned payload
    • Accessible as http_headers in response. Also accessible on thrown errors (e.g. RateLimited)
  • 0.11.0 - Plisskin transformation can be disabled by specifying a skip_rubyize = true in config block.
  • 0.10.0 - Support for FullContact Company API
  • 0.9.0 - Removed Rash gem and replaced with Mashify + Plisskin
  • 0.8.2 - Fix for 0.8.0 constant resolution issue.
  • 0.8.0
    • Hashie now allowed from [2.2, 4.0) to support a wide range of other applications
    • Default useragent includes version number for our own information
    • Useless XML mode and dep on multi_xml removed
    • Code reformatting & basic code hygiene, prep for new features in 0.9.0
  • 0.7.0 - Faraday 0.9.0
  • 0.6.0 - Removal of timeoutSeconds parameter. This parameter is automatically stripped from your request if included.

Installation

gem install fullcontact

Documentation

http://rdoc.info/gems/fullcontact

Usage Examples

    require 'fullcontact'

    # This could go in an initializer
    FullContact.configure do |config|
        config.api_key = 'fullcontact_api_key_goes_here'
    end

    # Get information about an email address
    person = FullContact.person(email: 'bart@fullcontact.com')

All returned values are Hashie structs. You can access fields as if they were fields:

    # Get person's family_name
    person.contact_info.family_name
     => "Lorang"

But you can also turn it into a normal hash

    # Get person's family_name
    person.to_hash['contact_info']['family_name']
     => "Lorang"

Authentication is done through query parameters by default. If you want to use headers instead:

    # This could go in an initializer
    FullContact.configure do |config|
        config.api_key = 'fullcontact_api_key_goes_here'
        config.auth_type = :headers # :header or :query
    end

There's other ways you can query the Person API:

    # Get information about an email address, organized by hashes vs. lists
    person2 = FullContact.person(email: 'bart@fullcontact.com', style: 'dictionary')

    # You can pass in any arbitrary parameters the Person API supports
    person3 = FullContact.person(email: 'bart@fullcontact.com', style: 'dictionary', webhookUrl: 'https://...')

    # Get information about a twitter handle
    person4 = FullContact.person(twitter: "bartlorang")

    # Get information from a phone number
    person6 = FullContact.person(phone:13037170414)

    # Get information about a twitter and ensure a 30s socket open timeout and a 15s socket read timeout
    # Can throw a Faraday::Error::TimeoutError if timeouts are exceeded
    person7 = FullContact.person({:twitter => "bartlorang"}, {:request => {:timeout => 15, :open_timeout => 30}})

Response formats can more closely mirror FullContact's APIs by disabling snake_case transformation:

    FullContact.configure do |config|
        config.api_key = "fullcontact_api_key_goes_here"
        config.skip_rubyize = true
    end

    person8 = FullContact.person(email: "bart@fullcontact.com")

    => #<Hashie::Mash contactInfo=#<Hashie::Mash chats=[#<Hashie::Mash client="gtalk" handle="lorangb@gmail.com">,
    #<Hashie::Mash client="skype" handle="bart.lorang">] familyName="Lorang" fullName="Bart Lorang" givenName="Bart...

You can also query the Company API

    # Get information about a company
    company1 = FullContact.company(domain: 'fullcontact.com')

    company1.organization.name
     => "FullContact Inc."

The Company API also supports searching by company name. Please see our API documentation for more details.

    # Gets a list of search results for a company name ordered by relevance
    companies = FullContact.company(companyName: 'FullContact')

    # Get the API url for full company profile lookup (append api key to use)
    # Note the array access, we are just grabbing the first (top) result
    companies[0].company_api_link
     => "https://api.fullcontact.com/v2/company/lookup?domain=fullcontact.com&apiKey="

    companies[0].org_name
     => "FullContact Inc."

Contributions

A full list of contributors can be found in GitHub

License

Copyright (c) 2016 FullContact Inc. and contributors

See LICENSE for details.