Custom Object schemas

🚧

Building with Custom Objects

Custom Objects can be built in two ways:

• Inside App Studio (recommended)
• With the ActiveCampaign API (V3)

Custom Objects inside App Studio
Apps built with App Studio have their authentication managed within ActiveCampaign, and natively embedded into the Automation builder. Building with Custom Objects - Custom Objects Overview

Custom Objects with the API
API-based integrations require customer authentication be managed on your platform. API integrations do not natively embedded into the Automation builder. Custom Objects API Guide

Building a private Custom Object App Studio application is only available for customers on Enterprise plan tiers. API-based, private integrations require use of the ActiveCampaign V3 api. Private vs Public Apps - Public vs Private Custom Object Schemas.

The first step to using Custom Objects is creating a schema that will define the fields and relationships for your records. A Custom Objects schema is a blueprint for creating new records. It defines the types of data a record will contain as well as how it relates to other records.

Schema Properties

"labels": {
  "singular": "My Object"
  "plural": "My Objects"
}

Schema Fields

Fields define the types of data a record will hold.

"labels": {
  "singular": "Phone Number"
  "plural": "Phone Numbers"
}

Max Field Counts

Field limits by type - this is the total count of fields available to specify for a single Private Custom Object Schema (public and child schemas have different limits):

Field Types

Text

• Type: text
• Description: A short string of text
• Limitations: TBD
• Max size: TBD
• Operators: is, is not, empty, not empty, contains, does not contains
  (note: for text "contains", try using wildcard characters * in your value string for intended results)

Schema Example:

{
  "id": "zipcode",
  "labels": {
    "singular": "Zipcode",
    "plural": "Zipcodes"
  },
  "description": "Zipcode for the listing",
  "required": false,
  "type": "text"
}

Record Example:

{
  ...
  "fields": [
    { 
      "id": zipcode",
      "value": "60602"
    }
  ]
}

Text Area

• Type: textarea
• Description: A longer string of text
• Limitations:
• Max size: TBD
• Operators: TBD

Schema Example:

{
  "id": "description",
  "labels": {
    "singular": "Listing description",
    "plural": "Listing descriptions"
  },
  "description": "Description of the listing",
  "required": false,
  "type": "textarea"
}

Record Example:

{
  ...
  "fields": [
    {
      "id": "description", 
      "value": "Lorem ipsum dolor sit amet, consectetur ..."
    }
  ]
}

Number

• Type: number
• Description: A single numeric data value that is an integer or decimal number
• Limitations: A double-precision 64-bit IEEE 754 floating-point number, restricted to finite values
• Max size: Up to 53 decimal places - defined as scale property on the Schema field definition. If the number of decimals provided exceeds the scale, then the digits will be rounded to fit the number of decimal places.
• Operators: TBD

Schema Example:

{
  "id": "rating",
  "labels": {
    "singular": "Product rating",
    "plural": "Product ratings"
  },
  "description": "Rating of the product",
  "required": false,
  "type": "number",
  "scale": 2
}

Record Example:

{
  ...
  "fields": [
    {
      "id": "rating",
      "value": 4.23
    }
  ]
}

Date

• Type: date
• Description: A single date string that follows the ISO 8601 standard for dates (YYYY-MM-DD)
• Limitations:
• Max size:
• Operators: TBD

Schema Example:

{
  "id": "delivery-date",
  "labels": {
    "singular": "Delivery date",
    "plural": "Delivery dates"
  },
  "description": "Date the purchase was delivered",
  "required": false,
  "type": "date"
}

Record Example:

{
  ...
  "fields": [
    {
      "id": "delivery-date",
      "value": "2020-11-02"
    }
  ]
}

Date Time

• Type: datetime
• Description: A single date/time string that follows the ISO 8601 standard for dates. This field will be stored with the timezone provided when the field was created, therefore no conversions to and from UTC will be performed.
• Limitations: datetime fields must be a full date+time+timezone string such as 2020-11-02T14:51:12Z or 2020-11-02T14:51:12-00:00.
• Max size:
• Operators: TBD

Schema Example:

{
  "id": "purchase-datetime",
  "labels": {
    "singular": "Purchase date",
    "plural": "Purchase dates"
  },
  "description": "Date the purchase was made",
  "required": false,
  "type": "datetime"
}

Record Example:

{
  ...
  "fields": [
    {
      "id": "purchase-datetime",
      "value": "2020-11-02T14:51:12Z"
    }
  ]
}

Currency

• Type: currency
• Description: The currency type stores a numeric value with a scale. If more than 2 digits are provided with a currency value, then those digits will be rounded to fit into 2 decimal places. Each currency field type must also define a default currency using the defaultCurrency property. The expected value for defaultCurrency must be an ISO 4217 standard 3-character currency code (case-sensitive).
• Limitations: TBD
• Max size: TBD
• Operators: TBD

Schema Example:

{
  "id": "total-price",
  "labels": {
    "singular": "Total price",
    "plural": "Total prices"
  },
  "description": "Total price of the purchase",
  "required": false,
  "type": "currency",
  "defaultCurrency": "USD"
}

Record Example:

{
  ...
  "fields": [
    {
      "id": "total-price",
      "value": 15.19,
      "currency": "EUR"
    }
  ]
}

Single and Multi-Select Dropdown

• Type: dropdown
• Description: An array of available options and each object can be one or more options from that list
• Limitations: Each option must be unique
• Max size: TBD
• Operators: TBD

Schema Example:

{
  "id": "payment-type",
  "labels": {
    "singular": "Payment type",
    "plural": "Payment types"
  },
  "description": "Payment type for the order",
  "required": false,
  "type": "dropdown",
  "options": [ 
    { "id": "cb84d92c-e6f1-4468-a128-09bbded1e90a", "value": "Visa" }, 
    { "id": "9bb74866-c68d-43cd-9b53-b9cf3f9b1500", "value": "Mastercard" }, 
    { "id": "745f9fa1-b53b-44a0-85fb-871d56b4ac26", "value": "Paypal" }
  ]
}

Record Example:

{
  ...
  "fields": [
    {
      "id": "payment-type",
      "value": "Visa"
    }
  ]
}

Multi-Select

• Type: multiselect
• Description: An array of options. Each object can choose all, none, or some of the options from that list.
• Limitations: Each option must be unique
• Max size: TBD
• Operators: TBD

Schema Example:

{
  "id": "amenities",
  "labels": {
    "singular": "Amenity",
    "plural": "Amenities"
  },
  "description": "Amenities included the listing",
  "required": false,
  "type": "multiselect",
  "options": [
    { "id": "944a7737-3174-410c-a34d-94019fc4c9de", "value": "parking" },
    { "id": "4fb47ca9-eab4-4563-b21e-b56d1c337759", "value": "pet-friendly" },
    { "id": "031c9683-3113-4b2d-a242-20f82f9cc0e9", "value": "dishwasher" }
  ]
}

Record Example:

{
  ...
  "fields": [
    {
      "id": "amenities", 
      "value": [ 
        "parking", 
        "dishwasher" 
      ]
    }
  ]
}

Schema Examples:

Create new schema for dropdown field

API call to create a new schema

{
  "id": "payment-type",
  "type": "dropdown",
  "options": [ 
    {"value": "Visa"}, 
    {"value": "Mastercard"}, 
    {"value": "Paypal"}
  ]
}

Update schema by adding and deleting options for the dropdown field

API call to add Discover and delete Paypal

{
  "id": "payment-type",
  "name": "Payment Type"
  "description": "Payment type for the order",
  "required": false,
  "type": "dropdown",
  "options": [ 
    { "id": "cb84d92c-e6f1-4468-a128-09bbded1e90a", "value": "Visa" }, 
    { "id": "9bb74866-c68d-43cd-9b53-b9cf3f9b1500", "value": "Mastercard" }, 
    { "value": "Discover" }
  ]
}

Record Examples:

Create a new record for a dropdown field

API call to create a new record

{
  ...
  "fields": [
    {"id": "payment-type", "value": "Paypal"}
  ]
}

Schema Relationships

Relationships are used to define a relationship from one record to an ActiveCampaign standard record. Today, the only relationships supported are between ActiveCampaign's standard objects: Contact, Account, or Deal. A custom object can also only be related to one standard object at a time.

To create a relationship between a schema and another object, you must specify the namespace property as well as the id as exactly as defined below:

"labels": {
  "singular": "Contact"
  "plural": "Contacts"
}

Example relationship block within a schema (note that these relationship blocks must be used within a call to a schema):

"relationships": [{
            "id": "primary-contact",
            "labels": {
                "singular": "Contact",
                "plural": "Contacts"
            },
            "description": "Primary contact related to this object",
            "namespace": "contacts",
            "hasMany": false
        }]

"relationships": [{
            "id": "account",
            "labels": {
                "singular": "Account",
                "plural": "Accounts"
            },
            "description": "Accounts related to this object",
            "namespace": "accounts",
            "hasMany": false
        }]

"relationships": [{
            "id": "deal",
            "labels": {
                "singular": "Deal",
                "plural": "Deals"
            },
            "description": "Deals related to this object",
            "namespace": "deals",
            "hasMany": false
        }]

For additional examples of using the relationship block within a schema, reference: https://developers.activecampaign.com/reference/create-a-schema