Skip to main content

How do I use the API for my custom objects?

Support Team
  • Updated
The Custom Objects API in Webmecanik Automation allows you to automatically synchronize data from your ecosystem (e-commerce site, ERP, industry-specific CRM) with your marketing automation platform.
 
⚠️ Important reminder: The Custom Objects feature is exclusively available to users of the Webmecanik Premium plan. Remember to contact your Customer Success Manager (CSM) to activate it on your account before starting development.
 

💡 Understanding the API without being a developer

The API works like a secure gateway between your software and Webmecanik:
  • The Custom Object is the general model (e.g., Products or Orders). It is identified by its numeric identifier (id) or by its technical name (alias, e.g., products).
  • The Custom Item is a specific entry (e.g., the Coffee table product). It always has a default Name field (name).
  • Custom Fields are the item's characteristics (e.g., SKU, Color, Price).
To save new data, you must not provide an identifier (id). Conversely, as soon as you transmit an id, Webmecanik understands that you want to modify an existing item.
 

🔄 Synchronizing Custom Items with a Contact

This is the most common method: when a customer places an order or views a product, you send the contact's information and their associated items in one single request.
 

Available routes

  • POST api/contacts/new: Creates a contact (or updates it if it already exists) and associates custom items with it.
  • POST api/contacts/batch/new: Allows you to send multiple contacts and their items in a batch (JSON array).
  • PATCH or PUT api/contacts/[contact_id]/edit: Updates a specific contact and its associated items.
 
Webmecanik performs a complete verification before saving: it validates the conformity of the objects, fields, and contact. If all validations are successful, the contact and custom items are created or updated, and then automatically linked to one another.
 

Request example (Creating a contact with an updated item)

In this example, we send a contact with a product to be updated (since an id is provided):

JSON

{
  "email": "jean.dupont@exemple.com",
  "firstname": "Jean",
  "customObjects": {
    "data": [
      {
        "alias": "products",
        "data": [
          {
            "id": 23,
            "name": "Vélo de course Pro",
            "attributes": {
              "website": "https://mon-site.com",
              "in-stock": 12,
              "multi": ["bleu", "noir"],
              "sku": "VELO-9821",
              "color": "noir"
            }
          }
        ]
      }
    ]
  }
}

Retrieving Custom Objects in the API response

By default, the API response does not return object details in order not to slow down technical exchanges. To retrieve custom objects in the response, simply add the ?includeCustomObjects=true parameter to your call URL:POST api/contacts/new?includeCustomObjects=true
 
 

📦 Managing Custom Items independently

You can create, update, or delete items without immediately associating them with a contact (for example, to import your product catalog).
 

Creating one or more items

  • Single-item creation: POST api/custom/item/new/[custom_object_id]

JSON

{
  "name": "Machine à café",
  "data": {
    "sku": "MC-450",
    "couleur": "argent"
  }
}
  • Batch creation: POST api/custom/item/batch/new/{customObjectId}

JSON

[
  {
    "name": "Avion miniature",
    "data": {
      "couleur": "jaune"
    }
  },
  {
    "name": "Bus électrique",
    "data": {
      "couleur": "violet"
    }
  }
]

Deleting data

  • Deleting a specific item: GET api/custom/item/delete/[custom_item_id] Each custom item identifier is unique across the entire database; therefore, it is not necessary to specify the parent object.
  • Completely emptying a custom object: GET api/custom/object/empty/[custom_object_id] This action deletes all items saved in the object while preserving its structure and fields. This operation may take some time depending on the volume: running the request again will not speed up processing.
     

🔗 Linking two Custom Items to each other

You can link records from distinct objects (for example, link a physical Store to an Order) using the following route:
  • POST api/custom/item/{itemId}/link/customItem/{itemId}
 

🔍 Viewing and filtering information

To audit your configurations or retrieve lists of items, several query requests (GET) are available:
 
Objective API route Available filtering
List Custom Objects GET api/custom/objects Returns the overall list and structural metadata.
List Custom Fields GET api/custom/fields Add ?where[0][col]=customObject&where[0][expr]=in&where[0][val]={customObjectId} to target a specific object.
List saved Items GET api/custom/items Use the same filter syntax to target only the items of a given object.

🛡️ Error handling and best practices

If a custom object, field, or item identifier provided in your request does not exist, the API blocks the operation and returns an HTTP 400 (Bad Request) error code. To preserve the integrity of your database, no data is saved (neither the contact nor the custom item).
 
Example of a response in the event of an alias input error:

JSON

{
  "errors": [
    {
      "code": 400,
      "message": "Custom Object with alias = invoice was not found",
      "details": []
    }
  ]
}
Be sure to verify the exact spelling of your aliases and respect field types (for example, do not inject free-form text into a field of type Number or Date) to ensure smooth integrations.

Related articles

Comments

0 comments

Please sign in to leave a comment.