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.

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.

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.

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:

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.

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.