objects Array

App Studio supports defining Custom Object schemas and saving inbound data as records. Custom Object schemas and records offer an extremely flexible way to store custom data in ActiveCampaign.

The top-level App Studio config objects property is an array of object definitions. Each object defines the schema, fields, relationships, data transformations, and other configuration information needed to support your integration's storage requirements.

There are two types of objects: core objects and custom objects. A core object describes and connects your inbound data to a core object in the ActiveCampaign platform, such as a Contact. A custom object defines how your inbound data will be stored as a record attached to the core object.

🚧

Core and Custom Objects

A minimum of two objects are required for a valid configuration. One object must be defined as a core object using the ac_object property (more on this later), and one or more objects defined as custom objects (no ac_object property).

For concrete examples, please refer to the Zendesk Support Custom Objects Example and Calendly Custom Objects Example.

Key

JSON Type

Required for Core Object

Required for Custom Objects

name

string

yes

yes

labels

object

yes

yes

description

string

yes

yes

external_id

string

yes

yes

ac_object

string

yes

no

fields

array of objects

yes
(however, the value will be an empty array)

yes

relationships

object

no

yes

transform

object

no

no

event_type_field

string

no

no

event_types

array of objects

no

no

from_reference

object

no

no

prepare_to_transform

object

no

no

name Property

The name of the object, such as "order", "submission", or "event." This value must be unique across all objects defined in the same application. For example, you cannot have two objects named "order" in the same app config. Once set, this name will be used by the ActiveCampaign platform to identify the object during the lifecycle of the object.

labels Object

These are the customer-facing labels of the object. For example, a label might be "Stripe Order", "Typeform Submission", or "Calendly Event." The labels object must include a singular and plural property. The following is an example of a labels object.

"labels": {
  "singular": "Ticket",
  "plural": "Tickets"
},

description Property

The description property is a short sentence describing what the object is, such as "Orders through Stripe", "Form submissions from Typeform", or "Ticket Created in Zendesk Support."

external_id Property

The external_id is used to specify how records are uniquely identified in the integrating system. The value can either be a simple field id reference (e.g. id or record.id) or a valid jq expression. Object records are already guaranteed to be unique per ActiveCampaign account, per CX app, and per Custom Object definition. If a record id is already unique in the integrating system, then an id field is sufficient. Otherwise, you may need to combine multiple fields for cases where a record does not have one uniquely identifying value in your system, or its identifier is not unique across your system’s accounts.

ac_object Property

An object defined as a core object must include the ac_object property. The value of this property must be one of the supported ActiveCampaign core objects. "Contact" is the only value supported at this time.

fields Array

The fields array is a list of field objects that describe the schema of the Custom Object. Each field may include the following properties and objects.

Attribute

JSON Type

Required

id

string

yes

labels

object

yes

description

string

yes

type

string

yes

is_required

boolean

yes

scale

number

no - optional only for "number" type

options

array of strings

yes - only for "dropdown" and "multiselect" types

default_currency

string

no - optional only for "currency" type

id Property

The field id property is a unique field identifier for the field. This value must be unique among other fields in the same Custom Object. When possible, it is recommended you use the name of the equivalent field that exists in the system you are integrating. This value is used to map fields in the inbound data to the record generated in ActiveCampaign.

labels Object

User-friendly labels to display in the UI for this field. This must include both the singular and plural form of the label.

{
  "singular": "Ticket ID",
    "plural": "Ticket IDs"
}

description Property

A short sentence describing the purpose or values stored in the field.

type Property

The data type of the value stored in the field. Valid types are currency, date, datetime, number, text, and textarea.

Type Name

Description

Notes

text

A short text field

Limited to 65,535. Longer strings will not be saved.

textarea

A text field of any length

number

An integer or decimal number

Number of decimals saved can be defined with the additional scale field. Scale can be set to 0 to denote integer values - this is the default.

datetime

A valid ISO8601 date time string (e.g. 2021-08-13T17:51:44+00:00)

date

A date string in the format YYYY-MM-DD (e.g. 2011-12-23)

dropdown

A field to capture a single value from a predefined list of options.

Options need to be defined in the additional options field.

multiselect

A field to capture multiple values from a predefined list of options.

Options need to be defined in the additional options field.

currency

A value containing numbers representing a currency value.

Currency type can be defined via the additional default_currency field. Defaults to "USD".

is_required Property

The is_required property is a boolean value indicating whether the field is required. If required, and a value is not provided, the record will not be created.

scale Property

The scale property is optional and only applies to the number data type. The value represents the number of decimals to save. A value of 0 declares the number is treated as an integer.

options Array

The options array is required for multiselect and dropdown data types. The expected value is an array of strings containing all possible values for this field. Any value supplied that is not in the list will not be saved.

{
  "options": ["red", "orange", "yellow"]
}

default_currency Property

The default_currency property is only used for currency data types. The value is a three-character ISO 4217 currency code. The value defaults to "USD".

relationships Array

The relationships array is a list of relationship objects. Each relationship object describes the connection the current custom object has with other objects. For a core object, the relationships array is not required. A custom object must relate to at least one core object.

🚧

Limitations

Only one relationship is currently supported. In the future, a custom object will be able to relate to more than one core object.

Each relationship is represented by the following attributes:

Attribute

JSON Type

Required

id

string

yes

labels

object

yes

description

string

yes

object

string

yes

has_many

boolean

yes

field

string

no

type

string

yes

id Property

Identifier of a relationship. This must be unique within the same object.

labels Object

A user-friendly label for the relationship. The object must include both singular and plural properties.

object Property

This is the name of the related object.

has_many Property

This is a boolean field that describes the relationship from the current object to a related object.

  • false: The custom object record is related to only one core object.
  • true: The custom object record can be related to more than one core object (currently not supported).

field Property

This is the field in the current payload that denotes the related object, if any. Our system will try to use the value from this field to create the related object and link it to the current object.

This field can either be a simple field reference (i.e. "id" or "record.id") or a valid jq expression.

type Property

Denotes where the data for creating this object will come from. The value can either be "data" or "reference".

  • "data": The value in the field is data found in the event payload that can be used to create the related object.
  • "reference": The value is a reference id to look up more information about an object in the integrating system. This is the value that is used in the from_reference step and can be accessed using ${reference} in that step.

transform Object

The transform object is used to pair each field with a !jq command that describes how to assign the field value from the incoming data.

"transform": {
  "meeting_type": ".data.meeting_type.name",
  "start_time": ".data.meeting.start",
  "id": ".data.meeting.uuid",
  "is_canceled": ".data.meeting.canceled"
},
{
  "data": {
    "meeting_type": {
      "id": 3477,
      "name": "Conference"
    },
    "meeting": {
      "id": "9be1cb7b-c41d-4175-8af0-db8c773c1a75",
      "start": "2022-02-31T13:30:00.000-05:00",
      "canceled": false
    }
  }
}

event_type_field Property

The event_type_field is an optional property. When the system you are integrating sends data to ActiveCampaign, it may include information about which event generated the data. The value of this property should be the path to the inbound data property that specifies the type of inbound event. Dot notation is supported.

Event types are useful to customers as they may choose to sync specific types of data from your system to ActiveCampaign or rely on the event type to trigger specific actions. If you are not sure what to provide here, leave the field out.

event_types Array

The event_types array is a list of event type objects, each describing an event type and how they should appear to users. Each object contains three string properties.

key

purpose

value

The value to match on in the payload for the event type.

display

The value displayed to a customer when selecting triggers or referring to the event.

description

A short sentence describing what this event is (e.g. when it can occur).

Example:

"event_types": [
    {
      "value": "ticket_created",
      "display": "Ticket Created",
      "description": "Occurs when a ticket is created"
    },
    {
      "value": "ticket_updated",
      "display": "Ticket Updated",
      "description": "Occurs when a ticket is updated"
    }
  ],

from_reference Object

The optional from_reference can be used to retrieve additional data required to process an event. An inbound event payload from the integrating system may not include all the data needed to populate your Custom Object. For example, you can use from_reference with the !http command to make a "lookup" request to retrieve additional data.

The response returned by from_reference is made available to other steps using the ${reference} variable. When defined, the from_referencestep is applied before theprepare_to_transform` step.

prepare_to_transform Object

This optional attribute is used to modify the shape of the data to fit the mappings in the transform step. This is useful when the incoming data has a different structure, such as nested data. Each event type can have a dedicated object. If you are not using event types or the inbound data does not match an existing event type, the default object is used. If defined, the prepare_to_transform is applied before the transform.