Custom Objects API Guide

This guide will show you how to use the ActiveCampaign API to create and manage Custom Objects for your Contacts. For a deep-dive into Custom Objects, check out "What Are Custom Objects?"

🚧

Private custom objects are free for all enterprise accounts.

If your account is not an enterprise account, you may need to upgrade.

When to use Custom Objects

Custom Objects enable you to model and manage your data in a way that reflects your unique business, giving you unparalleled flexibility to track interactions with your Contacts.

When you want to track a single data point ((e.g., customer id, job title), A custom field might be what you need. Custom Objects are perfect for tracking sets of corresponding data. Examples of data sets Custom Objects can be used for:

  • Website Orders
  • Sports Team Signups
  • Employee information

Custom Object data can be interacted with seamlessly through the API, or by your employees, using the ActiveCampaign web interface.

In this tutorial are going to use Custom Objects to track our Customer's purchase history, making customer service and future direct marketing easier!

Creating and Managing Custom Schemas

Schemas are how ActiveCampaign stores sets of data on a Contact's record. Think of it as the "specialized filing cabinet" for data. The schema expects certain data to be provided, will validate it, and display it how you want. To start writing data to a contact, you must first create a schema for that data.

Create a Schema

The first step for tracking our orders is to create a schema to store the expected data.
A Custom Object "Schema" sets up what kind of data will be expected for each Custom Object record.

Here's the data we'd like to track for our example online store:

  • order number
  • date of the order
  • special instructions from the customer
  • total price of the order
  • link to the purchase receipt
  • shipping status of the order
  • link to the package tracking website

To create a schema to store these orders, we must understand what the data type will be. There are several options: text, textarea, number, date, datetime, currency, dropdown, and multiselect. You can find more information on data types here: Custom Object schemas

Here's what each data point will be:

  • order number (number)
  • date of the order (date)
  • special instructions from the customer (textarea)
  • total price of the order (currency)
  • link to the purchase receipt (text)
  • shipping status of the order (dropdown)
  • link to the package tracking website (text)

Create the schema with the following call: POST: https://{{yourAccountName}}.api-us1.com/api/3/customObjects/schemas

{
    "schema": {
        "labels": {
            "singular": "Online Order",
            "plural": "Online Orders"
        },
        "slug": "orders",
        "description": "Example of custom objects for tracking orders",
        "fields": [
            {
                "description": "Unique order number assigned to the purchase",
                "id": "order-number",
                "slug": "order-number",
                "labels": {
                    "singular": "Number",
                    "plural": "Numbers"
                },
                "type": "number",
                "scale": 0,
                "isRequired": true
            },
            {
                "description": "Date of the purchase",
                "id": "order-date",
                "slug": "order-date",
                "labels": {
                    "singular": "Date",
                    "plural": "Dates"
                },
                "type": "date",
                "isRequired": true
            },
            {
                "description": "Shipping status of the order",
                "id": "order-ship-status",
                "slug": "order-ship-status",
                "labels": {
                    "singular": "Shipping Status",
                    "plural": "Shipping Statuses"
                },
                "type": "dropdown",
                "isRequired": true,
                "options": [
                    {
                        "id": "shipping-status-received",
                        "value": "Received"
                    },
                    {
                        "id": "shipping-status-processing",
                        "value": "Processing"
                    },
                    {
                        "id": "shipping-status-shipped",
                        "value": "Shipped"
                    }
                ]
            },
            {
                "description": "Total price of the purchase",
                "id": "order-total",
                "slug": "order-total",
                "labels": {
                    "singular": "Total",
                    "plural": "Totals"
                },
                "type": "currency",
                "defaultCurrency": "USD",
                "isRequired": true
            },
            {
                "description": "Link to the PDF purchase receipt",
                "id": "order-link",
                "slug": "order-link",
                "labels": {
                    "singular": "Receipt",
                    "plural": "Receipt"
                },
                "type": "text",
                "isRequired": true
            },
            {
                "description": "Customer-provided special instructions",
                "id": "order-instructions",
                "slug": "order-instructions",
                "labels": {
                    "singular": "Instruction",
                    "plural": "Instructions"
                },
                "type": "textarea",
                "isRequired": false
            }
        ],
        "relationships": [
            {
                "id": "primary-contact",
                "labels": {
                    "singular": "Primary Contact",
                    "plural": "Primary Contacts"
                },
                "description": "Primary contact for this order",
                "namespace": "contacts",
                "hasMany": false
            }
        ]
    }
}

We created the schema correctly, so we received a 201: Created response from the API with the following response body (note the assigned ID for this schema):

{
    "schema": {
        "id": "a6e20485-911e-4fcf-b2a4-0aa6cf4e9071",
        "slug": "orders",
        "visibility": "private",
        "labels": {
            "singular": "Online Order",
            "plural": "Online Orders"
        },
        "description": "Example of custom objects for tracking orders",
        "createdTimestamp": "2022-08-24T17:01:23.393819292Z",
        "updatedTimestamp": "2022-08-24T17:01:23.393819292Z",
        "fields": [
            {
                "id": "order-number",
                "labels": {
                    "singular": "Number",
                    "plural": "Numbers"
                },
                "description": "Unique order number assigned to the purchase",
                "type": "number",
                "required": false,
                "scale": 0,
                "inherited": false
            },
            {
                "id": "order-date",
                "labels": {
                    "singular": "Date",
                    "plural": "Dates"
                },
                "description": "Date of the purchase",
                "type": "date",
                "required": false,
                "inherited": false
            },
            {
                "id": "order-ship-status",
                "labels": {
                    "singular": "Shipping Status",
                    "plural": "Shipping Statuses"
                },
                "description": "Shipping status of the order",
                "type": "dropdown",
                "required": false,
                "options": [
                    {
                        "id": "88ff15e6-d4cc-4ad4-a07e-41dc35183c63",
                        "value": "Received"
                    },
                    {
                        "id": "30818d80-33dd-4068-ae40-f8580a7458f2",
                        "value": "Processing"
                    },
                    {
                        "id": "1dd8c587-d3ca-4388-abce-2ebba84c9ec6",
                        "value": "Shipped"
                    }
                ],
                "inherited": false
            },
            {
                "id": "order-total",
                "labels": {
                    "singular": "Total",
                    "plural": "Totals"
                },
                "description": "Total price of the purchase",
                "type": "currency",
                "required": false,
                "defaultCurrency": "USD",
                "inherited": false
            },
            {
                "id": "order-link",
                "labels": {
                    "singular": "Receipt",
                    "plural": "Receipt"
                },
                "description": "Link to the PDF purchase receipt",
                "type": "text",
                "required": false,
                "inherited": false
            },
            {
                "id": "order-instructions",
                "labels": {
                    "singular": "Instruction",
                    "plural": "Instructions"
                },
                "description": "Customer-provided special instructions",
                "type": "textarea",
                "required": false,
                "inherited": false
            }
        ],
        "icons": {
            "default": "https://d226aj4ao1t61q.cloudfront.net/n9mayqo2d_customobject.png"
        },
        "relationships": [
            {
                "id": "primary-contact",
                "labels": {
                    "singular": "Primary Contact",
                    "plural": "Primary Contacts"
                },
                "description": "Primary contact for this order",
                "namespace": "contacts",
                "hasMany": false,
                "inherited": false
            }
        ]
    }
}

📘

Copy the schema ID, you'll be using it in all future calls

The schema id is how you will notify ActiveCampaign that a set of data should be written to your Custom Object Schema.

The id of this new Custom Objects schema is a6e20485-911e-4fcf-b2a4-0aa6cf4e9071 and we will be using it in all future calls to populate Custom Object data on our Contacts.

List all Your Schemas

  • You can get a list of all your schemas with this GET call:
    GET: https://{{yourAccountName}}.api-us1.com/api/3/customObjects/schemas
  • Get a copy of an individual schema:
    GET: https://{{yourAccountName}}.api-us1.com/api/3/customObjects/schemas/{{schemaID}}

Removing a Schema

Deleting a schema is easily done with a DELETE call:
DELETE: https://{{yourAccountName}}.api-us1.com/api/3/customObjects/schemas/{{schemaID}}

❗️

Deleting a schema removes ALL records in the schema!

Maybe update the schema instead?

Updating a Schema

Updating a schema can be done with a PUT call to:
PUT: https://{{yourAccountName}}.api-us1.com/api/3/customObjects/schemas/{{schemaID}}
More information here: Update a schema
Need to delete a field in a schema? Delete a field

Populate Custom Object Records Using The Web Interface

Now that we've created our Schema, we can start sending data to store as Custom Objects on our Contacts.

On the ActiveCampaign web interface, you will immediately see your schema, and your employees can immediately start saving records on contacts:

10981098
11221122

You can immediately start saving records using the ActiveCampaign web interface.

Populate Custom Object Records Using The API

Your system can automatically populate custom object records as you receive orders through simple API calls.

📘

If this customer is new, you might need to create a contact record first

This can be easily done:
POST: https://{{yourAccountName}}.api-us1.com/api/3/contact/sync

JSON BODY:

{
    "contact": {
        "email": "[email protected]",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "555-555-5555"
    }
}

ActiveCampaign will create or update the contact, and will return an id for this Contact.

Using the schema id we received from when we created the schema, and populate a custom object for a Customer with the id of 32.

We populate a JSON object that satisfies the expected data points for the schema we created, and with a POST to https://{{yourAccountName}}.api-us1.com/api/3/customObjects/records/a6e20485-911e-4fcf-b2a4-0aa6cf4e9071 (the id of the schema created earlier)

📘

"id" and "externalId" are optional fields

It is recommended to use externalId when creating records because it makes future updates easier.

Any value in id will be ignored if there is no record matching that id, and a new record will be created with an assigned, new id (not the one provided in the POST payload). If an existing record has a matching id provided in the request body, the existing record with that same id will be updated to the new record.

externalId is optional, and can used for updating and reference, externalId can be updated.

id can be used for updating and reference, but are automatically assigned on record creation and can not be changed.

{ 
    "record": {
        "externalId": "online-order-1234",
        "fields": [ 
        {
            "id": "order-number",
            "value": 1234
        },
        {
            "id": "order-date",
            "value": "2022-08-30"
        },
        {
            "id": "order-instructions",
            "value": "Please pack extra carefully, it is a gift for my nephew."
        },
        {
            "id": "order-total",
            "value": 15.12
        },
        {
            "id": "order-link",
            "value": "https://www.example.com/receipt"
        },
        {
            "id": "order-ship-status",
            "value": "Received"
        }
    ],
        "relationships": {
            "primary-contact": [ 32 ]
        }
    }
}

If the POST is successful, we get a response with the id of the Custom Object record:

{
    "record": {
        "externalId": "online-order-1234",
        "schemaId": "a6e20485-911e-4fcf-b2a4-0aa6cf4e9071",
        "fields": [
            {
                "id": "order-number",
                "value": 1234
            },
            {
                "id": "order-date",
                "value": "2022-08-30"
            },
            {
                "id": "order-instructions",
                "value": "Please pack extra carefully, it is a gift for my nephew."
            },
            {
                "id": "order-total",
                "value": 15.12
            },
            {
                "id": "order-link",
                "value": "https://www.example.com/receipt"
            },
            {
                "id": "order-ship-status",
                "value": "Received"
            }
        ],
        "relationships": {
            "primary-contact": [
                "32"
            ]
        }
    }
}

This Custom Object is immediately viewable in the ActiveCampaign web interface:

16191619

Retrieve a Custom Object Record

  • If you provided an externalId when creating the record, you can use this call to retrieve a record:
    GET: https://{{yourAccountName}}.api-us1.com/api/3/customObjects/records/:schemaId/external/{{your-external-ID}}

  • If you do not provide an id when creating a record, and want to use the ActiveCampaign creates and returns in the response payload:
    GET: https://{{yourAccountName}}.activehosted.com/api/3/customObjects/records/{{schemaID}}/{{recordID}}

Updating a Custom Object Record

  • Records are "upserted." This means that if you create a record with an externalId that hasn't been used before, ActiveCampaign will save a new record on the Contact. If you send a payload with an externalId that already exists, the existing record will be updated to the contents of the payload.

In the example above, we created an order with the order-ship-status of Received. If we want to update that record (online-order-1234) to an order-ship-status of Shipped, we would simply make another POST to the same endpoint as we did when creating it. If we use the same externalId, the record will be updated.

Deleting a Custom Object Record

DELETE: https://{{yourAccountName}}.activehosted.com/api/3/customObjects/records/{{schemaID}}/external/{{externalId}}
In our example's case, that call would look like this:
DELETE: https://{{yourAccountName}}.activehosted.com/api/3/customObjects/records/a6e20485-911e-4fcf-b2a4-0aa6cf4e9071/external/online-order-1234

Use Custom Data in an Automation

Now that we can manage Custom Objects with the API, lets use those Custom Objects in an automation, sending a confirmation email to a customer with their order details.

First, create an automation in the ActiveCampaign web interface:

33163316

Create an automation by clicking “automations” and “Create and Automation”:

Second, select "Add a start trigger"

17171717

Adding a start trigger

Third, select "Objects" then the name of your custom object (ours is "Online Orders" then select "Online Order is created"

12841284

Select "Online Order is created"

Fourth, select "All Online Orders" and "save"

📘

Check out Segmenting!

This tutorial won't cover segmenting, but if you select "Segment," you can start automations based on data points inside of your Custom Object Records, you can use this for sending coupons if a website order is over a certain amount, or shipping notifications for when a shipping status changes.

At this point, you can have an almost unlimited amount of future automation options. Next, we'll be sending emails with this automation.

Use Custom Data in Email Campaigns

We will be using Custom Objects to send order confirmation emails. Earlier, we created an automation for when an Online Order Custom Object record was created. Let's send an email to our customer using that automation.

Inside of our automation, click the "+" sign to add an action in the automation:

10021002

Create a step to add an action

Select "Send an Email"

12221222

Create a new email, and name it whatever you would like. Inside the email/campaign designer, we will choose to "start from scratch:"

15171517

You can create an email to look however you would like, but for this example, we'll keep it very simple:

12021202

We've created our email, but now we need to populate it with the right tags, so the email is sent with the right content. Select "Settings," then "Manage Data," and select the name of your Custom Object schema:

14291429

Here you will find the "personalization tags" for every data point in your Custom Object. You can use these tags in your emails:

12891289

Place those personalization tags into the email body:

10921092

With our personalization tags in place, we're ready to send emails. After checking that your email is in the automation and the automation is set to "active:"

15911591

Now if we send an Online Order Custom Object Record with the API, the system immediately creates the record on the Contact...

998998

...and sends an email:

12291229 498498