How to create, read, update, and delete Custom Object records on your Contacts
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:
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/syncJSON BODY:
{ "contact": { "email": "[email protected]", "firstName": "John", "lastName": "Doe", "phone": "555-555-5555" } }ActiveCampaign will create or update the contact, and will return an
idfor 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 anid. 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, useexternalId.externalIdis optional, and if omitted when a record is created, the record can only be retrieved using the autogenerated and assignedidfield.It is recommended to use
externalIdwhen creating records because it makes future updates easier.Updating Records
Any value inidwill be ignored if there is no record matching that id, and a new record will be created with an assigned, newid. If an existing record has a matchingidprovided in the request body, the existing record with that sameidwill be updated.Summary:
externalIdis an optional, user-defined field. It is used for updating and reference, and can be updated.
- idcan 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
externalIdwhen 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
externalIdthat hasn't been used before, ActiveCampaign will save a new record on the Contact. If you send a payload with anexternalIdthat 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:
Create an automation by clicking “automations” and “Create and Automation”:
Second, select "Add a start trigger"
Adding a start trigger
Third, select "Objects" then the name of your custom object (ours is "Online Orders" then select "Online Order is created"
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:
Create a step to add an action
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:
