Contact 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?"

❓

Is your integration creating private, or public Custom Objects?

🔓 Everyone is welcome to develop cx applications that creates public Custom Objects on any account that integrates that public CX app into their account. The Custom Objects a public CX writes will be written to the Contact records of any ActiveCampaign customer using that integration.

🔒 Custom Object Records that will be written via Private CX apps or API calls are only available for enterprise accounts.

💡 Example 1: Your company's system calls the ActiveCampaign API to create and update Custom Objects on your company's ActiveCampaign account. This requires an enterprise ActiveCampaign account.

💡 Example 2: Your public website offers a service that will write Custom Object records to any of your user's ActiveCampaign accounts, if those users provide your system with their api credentials. These custom objects will only be written to users who have enterprise ActiveCampaign accounts.

💡Example 3: Your website creates a publicly released CX application, available on the ActiveCampaign app marketplace. Any user of this public CX app will have Custom Object records written to their account, and does not require an enterprise ActiveCampaign account.

💡Example 4: Your company creates a private CX App that communicates with your system's api to create and update Custom Objects on your company's ActiveCampaign account. This requires an enterprise ActiveCampaign account.

If you have questions regarding Custom Object entitlements, please reach out to ActiveCampaign Developer Relations at [email protected]

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:

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)

📘

How to id your records

Creating Records
When a record is created, it will be automatically assigned an id. You can create your own ids as well, to match your system. For example, you could create custom object records that match the order numbers created in your online store. To assign your own custom id, use externalId. externalId is optional, and if omitted when a record is created, the record can only be retrieved using the autogenerated and assigned id field.

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

Updating Records
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. If an existing record has a matching id provided in the request body, the existing record with that same id will be updated.

Summary:

• externalId is an optional, user-defined field. It is used for updating and reference, and can be updated.

- id can be used for updating and referencing records, 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:

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:

Second, select "Add a start trigger"

Third, select "Objects" then the name of your custom object (ours is "Online Orders" then 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:

Select "Send an Email"

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

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

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:

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

Place those personalization tags into the email body:

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

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

...and sends an email: