Custom Object schemas

🚧

Custom Objects API

All customers may take advantage of Custom Objects provided by apps and integrations. Creating private Custom Objects for production use is a feature available only to Enterprise ActiveCampaign plan tiers. If you are a developer building an application or integration to be used by other ActiveCampaign customers, please read our documentation on how to create a public schema.

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

Property

Description

id

Automatically generated globally unique identifier for the schema

slug

A human-readable identifier, typically a combination of lower-case words, numbers, and dashes. For example my-schema-1. The value must be unique among any other schemas that exist on the account.

labels

An object with two properties, singular and plural that are human-readable names of the Custom Object. For example:

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

Labels must be unique (case-insensitive) across all fields within a schema to eliminate any confusion when navigating the UI.

description

Human-readable description of the Custom Object schema (optional)

fields

An array of user-defined data for the schema

relationships

An array of custom and standard schemas related to this schema

createdTimestamp

A timestamp indicating when the schema was created

updatedTimestamp

A timestamp indicating when the schema was last modified

icons

A collection of icons used by the interface. Currently read-only. Future behavior may include customizing icons.

Schema Fields

Fields define the types of data a record will hold.

Note: The full list of supported data types is still being finalized.

Property

Description

id

A unique identifier for the field. An id value may contain lower- and upper-case letters, numbers, dashes (-), and underscores (_). With regards to unique validation, a dash and underscore are considered the same. For example, test-field and test_field are treated as the same identifier.

labels

An object with two properties, singular and plural, and are human-readable names of the field. For example:

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

type

The data type for this field: text, textarea, number, date, datetime, currency, dropdown, multiselect

required

Boolean indicating if the field is required for every record

scale

For number fields, the scale defines how many decimals to store. If the number of decimals provided exceeds the scale, then the digits will be rounded to fit the number of decimal places.

description

(Optional) Human-readable description of the field, to help express usage or intent.

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

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:
  • 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.
  • 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:

Property

Description

id

A unique identifier for the relationship.
Contact objects: primary-contact
Account objects: account
Deal objects: deal

labels

An object with two properties, singular and plural, and are human-readable names of the relationship. For example:

Contact:

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

description

(Optional) Human-readable description of the relationship, to help express usage or intent.

namespace

Name of standard ActiveCampaign object.
Contact objects: contacts
Account objects: accounts
Deal objects: deals

hasMany

Currently only false is supported. In future, this will dictate one-to-many vs. many-to-many relationships between objects.

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