Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Ruby Client for Ontraport JSON API

Subscribe to updates I use ontraport_api

Statistics on ontraport_api

Number of watchers on Github 7
Number of open issues 2
Main language Ruby
Open pull requests 1+
Closed pull requests 0+
Last commit over 4 years ago
Repo Created over 4 years ago
Repo Last Updated over 3 years ago
Size 35 KB
Organization / Authorjimmynguyc
Page Updated
Do you use ontraport_api? Leave a review!
View open issues (2)
View ontraport_api activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating ontraport_api for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Ontraport API

Gem Version

A Ruby Client for Ontraport's REST JSON API


Add this line to your application's Gemfile:

gem 'ontraport_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ontraport_api

Supported APIs


client.get_object(id, object_id)                              # Get an Object's Data
client.new_object(object_params, object_id)                   # Create new Object
client.update_object(id, object_params, object_id)            # Update Object Details
client.get_objects(search_criteria, object_id)                # Get List of Objects based on Search Criteria


client.get_contact(id)                                        # Get a Contact's Data
client.new_contact(contact_params)                            # Create new Contact
client.update_contact(id, contact_params)                     # Update Contact Details
client.contact_fields(format)                                 # Fetch Contact Meta Fields
client.add_sequences_to_contact(id, sequence_ids)             # Add Sequences (Array / String) to Contact
client.add_tags_to_contact(id, tag_ids)                       # Add Tags (Array / String) to Contact
client.add_tags_to_contacts(tag_ids, contacts_criteria)       # Add Tags (Array / String) to Selected Contacts
client.remove_tags_from_contacts(tag_ids, contacts_criteria)  # Remove Tags from Selected Contacts
client.get_contacts(search_criteria)                          # Get List of Contacts based on Search Criteria
client.get_contacts_by_<field_name>(value)                    # Wildcard alias to client.get_contacts("<field_name> = 'value'")


client.get_tags(conditions)                 # Get Tags by condition
client.new_tag(tag_name)                    # Create new Tag with tag_name
client.get_tags_by_<field_name>(value)      # Wildcard alias to client.get_tags("<field_name> = 'value'")


client.get_sequences(conditions)                # Get all sequences
client.get_sequences_by_<field_name>(value)     # Wildcard alias to client.get_sequences("<field_name> = 'value'")

See on details of parameters.


Basic example:

require 'ontraport_api'

client ='app-id','app-key')

search_results = client.get_contacts("email = '' AND lastname = 'Ngu'")
puts search_results

# Error handling
puts search_results['error']    # true if error
puts search_results['message']  # API response body when error

Finding Contacts:

contact = client.get_contacts_by_email('').first
contact = client.get_contacts_by_city('Kuala Lumpur').first
contact = client.get_contacts_by_sms_number('+60123456789').first

Create New Contact:

contact = client.new_contact({ firstname: 'Jimmy', lastname: 'Ngu', email: '' })
puts 'Success' if contact['error'].nil?

Adding Tags to Contacts:

tag_name = 'Customer'
tag = client.get_tags_by_tag_name(tag_name).first
if tag.nil?
    tag = client.new_tag(tag_name)

result = client.add_tags_to_contacts(tag['tag_id'], { ids: contact['id'] })
puts 'Success' if result['error'].nil?

# Multiple tags & contacts
client.add_tags_to_contacts('<tag_id_1>,<tag_id_2>,<tag_id_3>', { ids: '<contact_id_1>,<contact_id_2>,<contact_id_3>' })

# Tag contacts with conditions
client.add_tags_to_contacts('<tag_id>', "city = 'Kuala Lumpur'" )

Adding Sequence to Contact:

sequence = client.get_sequences_by_name('Sales Funnel')
result = client.add_sequences_to_contact(contact['id'], sequence['drip_id'])
puts 'Success' if result['error'].nil?


  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 a new Pull Request

TODO Lists

  • Forms API
  • Transactions API
  • Messages API
  • Tasks API
  • Products API

Experimental / Missing Endpoints

Many element endpoints are experimental since the JSON API is so new and documentation is lacking in general. I'm working with the objects API endpoint mostly for those. Will update as they become available.

Otherwise, they're missing because I haven't got to them yet. Check the TODO list and let me know if I've missed anything.

Release Notes


  • Deprecated #add_sequence_to_contact in favour of #add_sequences_to_contact since it did not trigger sequence immediately
  • Breaks v0.2.2 implementation


  • Added generic Object query


  • Return ['data'] as default (breaking v0.1 implementations with ['data'])


  • Add Contact Sequence API


  • Fix bug on PUT methods
  • Fix bug on add / remove Contact Tags
  • Bump minor version


  • Add Tags API
  • Wildcard field_name search
  • Error handling with error message hash


  • Add Sequences API


  • Contacts API
ontraport_api open pull requests (View All Pulls)
  • Implement new endpoints for sequences
ontraport_api list of languages used
Other projects in Ruby