🚧

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

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

Schema Fields

Fields define the types of data a record will hold.

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

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

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:

"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