ActiveCampaignWrapper

This library is designed to help ruby/rails based applications communicate with the publicly available REST API for ActiveCampaign. It also supports a lot of functionality which is currently undocumented in the REST API.

If you are unfamiliar with the ActiveCampaign REST API, you should first read the documentation located at https://developers.activecampaign.com/reference.

Installation

Add this line to your application's Gemfile:

gem 'active_campaign_wrapper'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install active_campaign_wrapper

Usage

Initialize
Tags
Lists
List Groups
Contacts
Contact Tags
Contact Automations
Contact Score Values
Email Activities
Custom Fields
Custom Field Options
Custom Field Values
Users
Groups
Templates
Task Types

Initialize

You can specify your Endpoint URL and API token in a config file looking like this.

ActiveCampaignWrapper.config do |config|
  config.endpoint_url = 'your-url'
  config.api_token = 'your-token'
end

and then initialize the client like

client = ActiveCampaignWrapper::Client.new

You can pass the Endpoint URL and API token directly to the client.

client = ActiveCampaignWrapper::Client.new({
  endpoint_url: 'your-url',
  api_token: 'your-token'
})

Tags - Api Reference

Create a tag

client.tags.create({
  tag: 'Tag Name',
  tag_type: 'contact',
  description: 'Tag description'
})

BODY PARAMS

tag (string) : Name of the new tag
tag_type (string): Tag-type of the new tag. Possible Values: template, contact.
description (string): Description of the new tag

Retrieve a tag

client.tags.find(tag_id)

Update a tag

client.tags.update(tag_id, {
  tag: 'Updated Tag Name'
})

Delete a tag

client.tags.delete(tag_id)

List all tags

client.tags.all

QUERY PARAMS (Optional)

search (string): Filter by name of tag(s)

Lists - Api Reference

Create a list

client.lists.create({
  name: 'New List',
  stringid: 'new-list',
  sender_url:'https://workytical.com',
  sender_reminder: 'You are getting this notification as you have subscribed to our list.'
})

BODY PARAMS

name* (string): Name of the list to create
stringid* (string): URL-safe list name. Example: 'list-name-sample'
sender_url* (string): The website URL this list is for.
sender_reminder* (string): A reminder for your contacts as to why they are on this list and you are messaging them.
send_last_broadcast (boolean): Boolean value indicating whether or not to send the last sent campaign to this list to a new subscriber upon subscribing. 1 = yes, 0 = no
carboncopy (string): Comma-separated list of email addresses to send a copy of all mailings to upon send
subscription_notify (string): Comma-separated list of email addresses to notify when a new subscriber joins this list.
unsubscription_notify (string): Comma-separated list of email addresses to notify when a subscriber unsubscribes from this list.
user (integer): User Id of the list owner. A list owner is able to control campaign branding. A property of list.userid also exists on this object; both properties map to the same list owner field and are being maintained in the response object for backward compatibility. If you post values for both list.user and list.userid, the value of list.user will be used.

Retrieve a list

client.lists.find(list_id)

Update a list

client.lists.update(list_id, {
  name: 'Updated List Name'
})

Delete a list

client.lists.delete(list_id)

Retrieve all lists

client.lists.all

QUERY PARAMS (Optional)

filtersname: Filter by the name of the list.

List Groups - Api Reference

Create a list group permission

client.list_groups.create({
  listid: list_id,
  groupid: group_id
})

BODY PARAMS

listid* (integer): ID of the list
groupid* (integer): ID of the group that list should be associated with

Retrieve a list group permission

client.list_groups.find(list_group_id)

Delete a list group permission

client.list_groups.delete(list_group_id)

Retrieve all list group permissions

client.list_groups.all

Contacts - Api Reference

Create a contact

client.contacts.create({
  email: '[email protected]',
  first_name:'first',
  last_name: 'last'
})

BODY PARAMS

email* (string): Email address of the new contact. Example: '[email protected]'
first_name (string): First name of the new contact.
last_name (string): Last name of the new contact.
phone (integer): Phone number of the contact.
field_values (array): Array of contact's custom field values [value]

Create or update contact

client.contacts.sync({
  email: '[email protected]',
  first_name:'first',
  last_name: 'last'
})

Update list status for a contact

client.contacts.update_list_status({
  list: list_id,
  contact: contact_id,
  status: 1
})

BODY PARAMS

list* (string/integer):ID of the list to subscribe the contact to
contact* (string/integer): ID of the contact to subscribe to the list
status* (string/integer): Possible Values: -1..3
- -1 Any
- 0 Unconfirmed
- 1 Active
- 2 Unsubscribed
- 3 Bounced

Set to "1" to subscribe the contact to the list. Set to "2" to unsubscribe the contact from the list. WARNING: If you change a status from unsubscribed to active, you can re-subscribe a contact to a list from which they had manually unsubscribed.

sourceid (integer): Set to "4" when re-subscribing a contact to a list

Retrieve a contact

client.contacts.find(contact_id)

Update a contact

client.contacts.update(contact_id, {
  first_name: 'Updated Contact Name'
})

Delete a contact

client.contacts.delete(contact_id)

Retrieve all contacts

client.contacts.all

QUERY PARAMS (Optional)

ids (string): Filter contacts by ID.
email (string): Email address of the contact you want to get
email_like (string): Filter contacts that contain the given value in the email address
exclude (integer): Exclude from the response the contact with the given ID
formid (integer): Filter contacts associated with the given form
id_greater (integer): Only include contacts with an ID greater than the given ID
id_less (integer): Only include contacts with an ID less than the given ID
listid (string): Filter contacts associated with the given list
search (string): Filter contacts that match the given value in the contact names, organization, phone or email
segmentid (integer): Return only contacts that match a list segment (this param initially returns segment information, when it is run a second time it will return contacts that match the segment)
seriesid (integer): Filter contacts associated with the given automation
tagid (integer): Filter contacts associated with the given tag
filterscreated_before Filter contacts that were created prior to this date
filterscreated_after: Filter contacts that were created after this date
filtersupdated_before: Filter contacts that were updated before this date
filtersupdated_after: Filter contacts that were updated after this date
waitid (integer): Filter by contacts in the wait queue of an automation block
orderscdate: Order contacts by creation date
ordersemail: Order contacts by email
ordersfirst_name: Order contacts by first name
orderslast_name: Order contacts by last name
ordersname: Order contacts by full name
ordersscore: Order contacts by score
in_group_lists (string): Set this to "true" in order to return only contacts that the current user has permissions to see.

Bulk import contacts

client.contacts.bulk_import({
  contacts: [
    {
      email: '[email protected]',
      first_name: 'Jane',
      last_name: 'Doe',
      phone: '123-456-7890',
      customer_acct_name: 'ActiveCampaign',
      tags: [
        'dictumst aliquam augue quam sollicitudin rutrum'
      ]
    }
  ],
  callback: {
    url: "www.your_web_server.com",
    request_type: "POST",
    detailed_results: "true",
    params: [
      { "key": "", "value": "" }
    ],
    headers: [
      { "key": "", "value": "" }
    ]
  }
})

BODY PARAMS

contacts* (array of objects): An array of objects containing information about a single contact. Up to 250 contacts may be included in a single request. The suggested minimum number of contacts is 10. If less than that, then contact/sync api request should be used.
callback (object): Callback function to notify users when an import is complete.
url (string): The URL endpoint which the importer will make a request to once the import has completed.
request_type (string): Can be set to either “GET” or “POST”. Determines the type of HTTP request which will be sent to the specified endpoint.
detailed_results (string): When set to “true” and the requestType parameter is set to “POST”, the callback will include the number of successes and failures in the originating request, as well as an array of error messages for each failed contact.
params (array of objects): A list of parameters to include in the callback request. Add each parameter in the form of a key-value pair. For a GET request, each parameter will be appended to the end of the URL in a query string. For a POST request, parameters will be included in the body of the request.
headers (array of objects): A list of headers to include in the callback request. Add each header in the form of a key-value pair.

Contact Tags - Api Reference

Retrieve all tags of a contact

client.contact_tags.all(contact_id)

Add a tag to a contact

client.contact_tags.create({
  contact: contact_id,
  tag: tag_id
})

BODY PARAMS

contact* (integer): Contact's id
tag* (integer): Tag's id

Retrieve a contact tag

client.contact_tags.find(contact_tag_id)

Remove a tag from a contact

client.contact_tags.delete(contact_tag_id)

Contact Automations - Api Reference

List all automations the contact is in

client.contact_automations.all(contact_id)

Contact Score Values - Api Reference

Retrieve a contact's score values

client.contact_score_values.all(contact_id)

Email Activities - Api Reference

Retrieve all email activities

client.email_activities.all

QUERY PARAMS (Optional)

filterssubscriberid: Set this parameter to return only email activities belonging to a given subscriber.
filtersdealId: Set this parameter to return only email activities belonging to a given deal.

Custom Fields - Api Reference

Create a custom field

client.custom_fields.create({
  type: "textarea",
  title: "Field Title",
  descript: "Field description",
  perstag: "Personalized Tag",
  defval: "Defaut Value",
  visible: 1,
  ordernum: 1
})

BODY PARAMS

title* (string): Title of the field being created
type* (string): Possible Values: dropdown, hidden, checkbox, date, text, datetime, textarea, NULL, listbox, radio
descript (string): Description of field being created
perstag (string): The perstag that represents the field being created
defval (string): Default value of the field being created
show_in_list (boolean): Show this field in the contact list view (Deprecated - no longer used)
visible (boolean): Show or hide this field when using the Form Builder
service (string): Possible Vales: nimble, contactually, mindbody, salesforce, highrise, google_spreadsheets, pipedrive, onepage, google_contacts, freshbooks, shopify, zendesk, etsy, NULL, bigcommerce, capsule, bigcommerce_oauth, sugarcrm, zohocrm, batchbook
ordernum (integer): Order of appearance in ‘My Fields’ tab.

Retrieve a custom field

client.custom_fields.find(field_id)

Update a custom field

client.custom_fields.update(field_id, {
  title: 'Updated Field Title'
})

Delete a custom field

client.custom_fields.delete(field_id)

Retrieve all custom fields

client.custom_fields.all

QUERY PARAMS (Optional)

limit (integer): The number of fields returned per request.

Link a custom field to a list

client.custom_fields.link_to_list(field_id, list_id)

Custom Fields Options - Api Reference

Create custom field options

client.custom_field_options.create([
  {
    field: custom_field_id,
    label: option_1_title,
    value: option_1_value
  },
  {
    field: custom_field_id,
    label: option_2_title,
    value: option_2_value
  }
])

BODY PARAMS

field* (integer): ID of the custom field to add options to
label (string): Name of the option
value* (string): Value of the option
orderid (integer): Order for displaying the custom field option
isdefault: Whether or not this option is the default value

Retrieve a custom field option

client.custom_field_options.find(field_option_id)

Delete a custom field option

client.custom_field_options.delete(field_option_id)

Custom Fields Values - Api Reference

Create a custom field value

client.custom_field_values.create({
  contact: contact_id,
  field: field_id,
  value: value
}, use_defaults: true)

BODY PARAMS

contact* (string/integer): ID of the contact whose field value you're updating
field* (string/integer): ID of the custom field whose value you're updating for the contact
value* (string): Value for the field that you're updating. For multi-select options this needs to be in the format of ||option1||option2||
use_defaults: If true, this will populate the missing required fields for this contact with default values

Retrieve a custom field value

client.custom_field_values.find(field_value_id)

Update a custom field value

client.custom_field_values.update(
  field_value_id,
  { value: value },
  use_defaults: false
)

Delete a custom field value

client.custom_field_values.delete(field_value_id)

Retrieve all custom field values

client.custom_field_values.all

Users - Api Reference

Create a user

client.users.create({
  first_name: 'Phoebe',
  last_name: 'Buffay',
  username: 'raginaphalange',
  password: 'smellycat',
  email: '[email protected]'
})

BODY PARAMS

username* (string): Username
email (string): Email address
first_name (string): First name
last_name (string): Last name
group (string/integer): Group ID
password (string): Plain text password

Retrieve a user

client.users.find(user_id)

Retrieve logged in user

client.users.logged_in

Retrieve a user by email

client.users.find_by_email(email)

Retrieve a user by username

client.users.find_by_username(username)

Update a user

client.users.update(user_id, {
  password: 'newsmellycat',
  group: group_id
})

Note: Group ID is mandatory in update.

Delete a user

client.users.delete(user_id)

List all users

client.users.all

Groups - Api Reference

Create a group

client.groups.create({
  title: 'Admin',
  descript: 'This is a group for admin users (people that can manage content)'
})

BODY PARAMS

title* (string): Title of the group to be created
descript (string): Group description
pg_message_add (boolean): Permission for adding messages
unsubscribelink (boolean): Whether or not to force unsubscribe links
optinconfirm (boolean): Whether or not to force optin confirm for this group
pg_list_add (boolean): Permission for adding lists
pg_list_edit (boolean): Permission for editing lists
pg_list_delete (boolean): Permission for deleting lists
pg_list_headers (boolean): Permission for managing custom email headers
pg_list_emailaccount (boolean): Permission for managing Unsubscribe By Email
pg_list_bounce (boolean): Permission for accessing list bounce settings
pg_message_edit (boolean): Permission for editing messages
pg_message_delete (boolean): Permission for deleting messages
pg_message_send (boolean): Permission for sending messages
pg_contact_add (boolean): Permission for adding contacts
pg_contact_edit (boolean): Permission for editing contacts
pg_contact_delete (boolean): Permission for deleting contacts
pg_contact_merge (boolean): Permission for merging contacts
pg_contact_import (boolean): Permission for importing contacts
pg_contact_approve (boolean): Permission for approving contacts
pg_contact_export (boolean): Permission for exporting contacts
pg_contact_sync (boolean): Permission for syncing contacts
pg_contact_filters (boolean): Permission for managing contact list segments
pg_contact_actions (boolean): Permission for managing contact actions
pg_contact_fields (boolean): Permission for managing contact custom fields
pg_user_add (boolean): Permission for adding users
pg_user_edit (boolean): Permission for editing users
pg_user_delete (boolean): Permission for deleting users
pg_group_add (boolean): Permission for adding groups
pg_group_edit (boolean): Permission for editing groups
pg_group_delete (boolean): Permission for deleting groups
pg_template_add (boolean): Permission for adding templates
pg_template_edit (boolean): Permission for editing templates
pg_template_delete (boolean): Permission for deleting templates
pg_personalization_add (boolean): Permission for adding personalization tags
pg_personalization_edit (boolean): Permission for editing personalization tags
pg_personalization_delete (boolean): Permission for deleting personalization tags
pg_automation_manage (boolean): pgFormEdit (boolean): Permission for editing subscription forms
pg_reports_campaign (boolean): Permission for viewing campaign reports
pg_reports_list (boolean): Permission for viewing list reports
pg_reports_user (boolean): Permission for viewing user reports
pg_startup_reports (boolean): Campaign ID of last campaign report viewed to decide whether to show link on startup
pg_reports_trend (boolean): Permission for viewing trend reports
pg_startup_gettingstarted (boolean): Whether or not to show the "getting started" tutorial on overview page
pg_deal (boolean): Permission for viewing deals
pg_deal_delete (boolean): Permission for deleting deals
pg_deal_reassign (boolean): Permission for reassigning deals
pg_deal_group_add (boolean): Permission for adding deal groups
pg_deal_group_edit (boolean): Permission for editing deal groups
pg_deal_group_delete (boolean): Permission for deleting deals groups
pg_saved_responses_manage (boolean): Permission for managing saved responses
pg_tag_manage (boolean): Permission for managing tags
req_approval (boolean): Whether or not this group requires all campaigns to be approved
req_approval_1st (boolean): Whether or not this group requires first campaign to be approved
req_approval_notify_string (string): Who to notify for approval related issues (email)
socialdata (boolean): Whether or not to show social links in campaigns sent from this group

Retrieve a group

client.groups.find(group_id)

Update a group

client.groups.update(group_id, {
  title: 'Updated Group Title'
})

Delete a group

client.groups.delete(group_id)

List all groups

client.groups.all

Templates - Api Reference

Retrieve a template

client.templates.find(template_id)

Delete a template

client.templates.delete(template_id)

List all templates

client.templates.all

Task Types - Api Reference

Create a task type

client.task_types.create({
  title: 'Call'
})

BODY PARAMS

title* (string): Deal task type's title. The title should be unique among deal task types.

Retrieve a task type

client.task_types.find(task_type_id)

Update a task type

client.task_types.update(task_type_id, {
  title: 'New super cool title'
})

Delete a task type

client.task_types.delete(task_type_id)

List all task types

client.task_types.all

Move tasks to another task type

client.task_types.move_tasks(from_task_type_id, to_task_type_id)

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/anmol-yousaf/active_campaign_wrapper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

See the LICENSE file for more info.

Code of Conduct

Everyone interacting in the ActiveCampaignWrapper project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

ActiveCampaignWrapper

Installation

Usage

Table of Contents

Initialize

Create a tag

Retrieve a tag

Update a tag

Delete a tag

List all tags

Create a list

Retrieve a list

Update a list

Delete a list

Retrieve all lists

Create a list group permission

Retrieve a list group permission

Delete a list group permission

Retrieve all list group permissions

Create a contact

Create or update contact

Update list status for a contact

Retrieve a contact

Update a contact

Delete a contact

Retrieve all contacts

Bulk import contacts

Retrieve all tags of a contact

Add a tag to a contact

Retrieve a contact tag

Remove a tag from a contact

List all automations the contact is in

Retrieve a contact's score values

Retrieve all email activities

Create a custom field

Retrieve a custom field

Update a custom field

Delete a custom field

Retrieve all custom fields

Link a custom field to a list

Create custom field options

Retrieve a custom field option

Delete a custom field option

Create a custom field value

Retrieve a custom field value

Update a custom field value

Delete a custom field value

Retrieve all custom field values

Create a user

Retrieve a user

Retrieve logged in user

Retrieve a user by email

Retrieve a user by username

Update a user

Delete a user

List all users

Create a group

Retrieve a group

Update a group

Delete a group

List all groups

Retrieve a template

Delete a template

List all templates

Create a task type

Retrieve a task type

Update a task type

Delete a task type

List all task types

Move tasks to another task type

Contributing

License

Code of Conduct