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.

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.

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 Type(s)	Max Field Count (combined)
Text / Text Area	350
Dropdown / Multi-select	350 (combined limit of 1000 options across all dropdown/multi-select fields)
Date / Datetime	100
Number	100
Currency	100

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

🚧Custom Objects API

Schema Properties

Schema Fields

Max Field Counts

Field Types

Text

Text Area

Number

Date

Date Time

Currency

Single and Multi-Select Dropdown

Multi-Select

Schema Relationships

🚧
Custom Objects API