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 |
labels | An object with two properties,
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 |
labels | An object with two properties,
|
type | The data type for this field: |
required | Boolean indicating if the field is required for every record |
scale | For |
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 thescale
, 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. Eachcurrency
field type must also define a default currency using thedefaultCurrency
property. The expected value fordefaultCurrency
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. |
labels | An object with two properties, Contact:
|
description | (Optional) Human-readable description of the relationship, to help express usage or intent. |
namespace | Name of standard ActiveCampaign object. |
hasMany | Currently only |
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