Data sync via Funnel API

The Funnel API lets you build your own integration and send data into Etals.

Each funnel syncs data to one content type. You can create a funnel for products, categories, articles, landing pages, or any other content type you have defined in Etals.

How funnels work

A funnel is a dedicated endpoint for one content type.

When you send data to the funnel endpoint, Etals reads the JSON payload, maps the values to system fields or properties, validates the data, and stores the result.

Setting up a funnel

A funnel usually takes about one minute to set up.

You need to enter the following information:

Mapping data to Etals

After you add a sample JSON payload, Etals shows the payload as an interactive tree.

Click a value in the tree to decide where it should be stored.

You can map a value to either:

• A system field on the content item.
• A property on the selected content type.

System fields

System fields are built-in fields that identify and describe the item itself. The available fields depend on the selected content type.

The identifier field is required. Etals uses it to know which item should be created or updated.

Mapping options

Each mapping can be configured with options:

Sending data to Etals

Send data to the endpoint shown in the funnel details.

$
curl -X POST "https://{tenant-domain}/api/v1/funnels/{endpoint-url}" \
>
  -H "Authorization: Bearer {api-token}" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "productNumber": "SKU-1001",
>
    "name": "Everyday Face Cream",
>
    "image": "https://example.com/images/sku-1001.jpg",
>
    "description": "Hydrating face cream for daily use.",
>
    "categories": ["Skincare", "Face care"]
>
  }'

You can send one object or an array of objects.

1
[
2
  {
3
    "productNumber": "SKU-1001",
4
    "name": "Everyday Face Cream"
5
  },
6
  {
7
    "productNumber": "SKU-1002",
8
    "name": "Balancing Face Serum"
9
  }
10
]

Successful response

When the data is accepted, Etals returns a success response.

1
{
2
  "status": "success",
3
  "message": "Data received successfully."
4
}

If partial validation is enabled and only some items are imported, the response includes the successful identifiers and validation errors for the failed items.

1
{
2
  "status": "success",
3
  "message": "Some items were imported; others failed validation.",
4
  "errors": {
5
    "SKU-1002": {
6
      "Meta description": "Value not found at path seo.metaDescription"
7
    }
8
  },
9
  "data": {
10
    "successIds": ["SKU-1001"]
11
  }
12
}

Validation errors

If partial validation is disabled, one invalid item causes the request to fail.

1
{
2
  "status": "error",
3
  "message": "Validation failed for one or more items.",
4
  "errors": {
5
    "SKU-1002": {
6
      "Product Image": "The image must be a valid URL."
7
    }
8
  }
9
}

Common validation issues include:

• The request body is empty.
• The funnel is inactive.
• The identifier field is not mapped.
• A required mapped value is missing.
• A value does not match the expected property type.
• A media value is not a valid URL.
• A reference value does not match an existing item.

Deleting data

You can delete synced items by sending a DELETE request to the same endpoint.

$
curl -X DELETE "https://{tenant-domain}/api/v1/funnels/{endpoint-url}" \
>
  -H "Authorization: Bearer {api-token}" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "identifiers": ["SKU-1001", "SKU-1002"]
>
  }'

For batch deletes, send an array of objects:

1
[
2
  {
3
    "identifiers": ["SKU-1001", "SKU-1002"]
4
  },
5
  {
6
    "identifiers": ["SKU-2001"]
7
  }
8
]

Request history

Etals stores recent funnel requests so you can review what was received, when it was received, whether it succeeded, and which validation errors were returned.

Use the request history when testing a new funnel or debugging a sync from another system.

Getting produced data back

Etals can also send produced or enriched data back to your system. Exports to your connected integrations happen automatically, and Etals can set up an API export that delivers produced content directly to an endpoint you control.

For the full payload structure, how your endpoint should respond, and how to customize the export, see the API export page.