Referentials

Referentials act as reusable lookup tables in Feedier. Each referential is bound to a primary attribute (its "key") and can declare a set of template attributes that describe the columns shared by every item it contains. On this page, we'll explore the different referential endpoints you can use to manage referentials and their items programmatically — listing, creating, updating and deleting them, as well as managing their nested items.

The referential model

The referential model contains the metadata of a referential: its name, the primary attribute it is keyed by, and the list of template attributes declared for its items.

Properties

Name
id
Type
integer
Description
Unique identifier for the referential.
Name
organization_id
Type
integer
Description
The unique identifier of the organization the referential belongs to.
Name
attribute_id
Type
integer
Description
The unique identifier of the primary attribute used as the referential key.
Name
name
Type
string
Description
The display name of the referential.
Name
attribute
Type
object
Description
The primary attribute used as the referential key. Included only when the attribute relationship is requested.
Name
template_attributes
Type
array
Description
The list of template attributes declared on the referential. Included only when the templateAttributes relationship is requested.
Name
items
Type
array
Description
The list of items belonging to the referential. Included only when the items relationship is requested.
Name
created_at
Type
timestamp
Description
Timestamp of when the referential was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the referential was last updated.

The referential item model

A referential item represents a single row stored under a referential. Its value is the actual value of the referential's primary attribute, and attribute_values stores the values of the referential's template attributes for this row.

Properties

Name
id
Type
integer
Description
Unique identifier for the referential item.
Name
referential_id
Type
integer
Description
The unique identifier of the referential the item belongs to.
Name
attribute_value_id
Type
integer
Description
The unique identifier of the attribute value backing this item's primary value.
Name
attribute_value
Type
object
Description
The primary attribute value of the item, exposing the referential's attribute name, label and the item value. Included only when the attributeValue relationship is requested.
Name
attribute_values
Type
array
Description
The list of template attribute values attached to this item. Included only when the attributeValues relationship is requested.
Name
created_at
Type
timestamp
Description
Timestamp of when the item was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the item was last updated.

GET/v3/referentials

List all referentials

This endpoint allows you to retrieve a paginated list of all the referentials of your organization. By default, a maximum of ten referentials are shown per page.

Optional attributes

Name
page
Type
integer
Description
Number of the page to display.
Name
filter
Type
string
Description
Narrow your search by using filters from JSON:API norms.
Allowed filters: name
Name
include
Type
string
Description
Include extra relationships using JSON:API norms.
Allowed includes: attribute, templateAttributes, templateAttributes.attribute, items, items.attributeValue

Request

GET

/v3/referentials

curl -G https://api.bx.feedier.com/v3/referentials \
    -H "Authorization: Bearer {token}" \
    -d "include"="attribute,templateAttributes.attribute" \
    -d "filter[name]"="Employees"

Response

{
    "data": [
        {
            "id": 12,
            "organization_id": 4,
            "attribute_id": 87,
            "name": "Employees",
            "attribute": {
                "id": 87,
                "name": "employee_id",
                "label": "Employee ID"
            },
            "template_attributes": [
                {
                    "id": 31,
                    "attribute_id": 88,
                    "attribute": {
                        "id": 88,
                        "name": "department",
                        "label": "Department"
                    },
                    "created_at": "2025-03-12T10:00:00+00:00",
                    "updated_at": "2025-03-12T10:00:00+00:00"
                }
            ],
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        }
        // ...
    ],
    "links": {
        "first": "https://api.bx.feedier.com/v3/referentials?page=1",
        "last": "https://api.bx.feedier.com/v3/referentials?page=2",
        "prev": null,
        "next": "https://api.bx.feedier.com/v3/referentials?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "path": "https://api.bx.feedier.com/v3/referentials",
        "per_page": 10,
        "to": 10,
        "total": 18
    }
}

POST/v3/referentials

Create a referential

This endpoint allows you to create a new referential. The primary attribute (attribute_name) and the template attributes (attributes) are created on the fly if they do not yet exist for your organization.

Required attributes

Name
name
Type
string
Description
The display name of the referential. Maximum length: 255 characters.
Name
attribute_name
Type
string
Description
The name of the primary attribute used as the referential key. The attribute will be created in your organization if it does not exist yet. Maximum length: 255 characters.

Optional attributes

Name
attributes
Type
array
Description
A list of attribute names to declare as template attributes for the referential. Each entry is a string with a maximum length of 255 characters.

Request

POST

/v3/referentials

curl https://api.bx.feedier.com/v3/referentials \
    -H "Authorization: Bearer {token}" \
    -d name="Employees" \
    -d attribute_name="employee_id" \
    -d "attributes[]"="department" \
    -d "attributes[]"="region"

Response

{
    "id": 12,
    "organization_id": 4,
    "attribute_id": 87,
    "name": "Employees",
    "template_attributes": [
        {
            "id": 31,
            "attribute_id": 88,
            "attribute": {
                "id": 88,
                "name": "department",
                "label": "Department"
            },
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        },
        {
            "id": 32,
            "attribute_id": 89,
            "attribute": {
                "id": 89,
                "name": "region",
                "label": "Region"
            },
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        }
    ],
    "created_at": "2025-03-12T10:00:00+00:00",
    "updated_at": "2025-03-12T10:00:00+00:00"
}

GET/v3/referentials/:id

Retrieve a referential

This endpoint allows you to retrieve a single referential by providing its unique identifier. The response always embeds the primary attribute, the template attributes and the items along with their attribute values.

Request

GET

/v3/referentials/12

curl https://api.bx.feedier.com/v3/referentials/12 \
    -H "Authorization: Bearer {token}"

Response

{
    "id": 12,
    "organization_id": 4,
    "attribute_id": 87,
    "name": "Employees",
    "attribute": {
        "id": 87,
        "name": "employee_id",
        "label": "Employee ID"
    },
    "template_attributes": [
        {
            "id": 31,
            "attribute_id": 88,
            "attribute": {
                "id": 88,
                "name": "department",
                "label": "Department"
            },
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        }
    ],
    "items": [
        {
            "id": 501,
            "referential_id": 12,
            "attribute_value_id": 9001,
            "attribute_value": {
                "name": "employee_id",
                "label": "Employee ID",
                "value": "EMP-001"
            },
            "attribute_values": [
                {
                    "id": 1201,
                    "attribute_value_id": 9101,
                    "attribute_value": {
                        "name": "department",
                        "label": "Department",
                        "value": "Engineering"
                    },
                    "created_at": "2025-03-12T10:00:00+00:00",
                    "updated_at": "2025-03-12T10:00:00+00:00"
                }
            ],
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        }
    ],
    "created_at": "2025-03-12T10:00:00+00:00",
    "updated_at": "2025-03-12T10:00:00+00:00"
}

PUT/v3/referentials/:id

Update a referential

This endpoint allows you to update an existing referential. You can update its name, switch its primary attribute, or redefine the list of template attributes. When the attributes field is provided, the referential's template attributes are fully replaced by the new list.

Optional attributes

Name
name
Type
string
Description
The new display name of the referential.
Name
attribute_name
Type
string
Description
The name of the primary attribute to use as the referential key. The attribute will be created in your organization if it does not exist yet.
Name
attributes
Type
array
Description
The full list of template attribute names. Sending this field replaces the existing template attributes.

Request

PUT

/v3/referentials/12

curl -X PUT https://api.bx.feedier.com/v3/referentials/12 \
    -H "Authorization: Bearer {token}" \
    -d name="Employees (EU)" \
    -d "attributes[]"="department" \
    -d "attributes[]"="country"

Response

{
    "id": 12,
    "organization_id": 4,
    "attribute_id": 87,
    "name": "Employees (EU)",
    "template_attributes": [
        {
            "id": 31,
            "attribute_id": 88,
            "attribute": {
                "id": 88,
                "name": "department",
                "label": "Department"
            },
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T11:00:00+00:00"
        },
        {
            "id": 33,
            "attribute_id": 92,
            "attribute": {
                "id": 92,
                "name": "country",
                "label": "Country"
            },
            "created_at": "2025-03-12T11:00:00+00:00",
            "updated_at": "2025-03-12T11:00:00+00:00"
        }
    ],
    "created_at": "2025-03-12T10:00:00+00:00",
    "updated_at": "2025-03-12T11:00:00+00:00"
}

DELETE/v3/referentials/:id

Delete a referential

This endpoint allows you to delete a referential by its unique identifier. The referential is soft-deleted along with its items.

Request

DELETE

/v3/referentials/12

curl -X DELETE https://api.bx.feedier.com/v3/referentials/12 \
    -H "Authorization: Bearer {token}"

GET/v3/referentials/:id/items

List all items of a referential

This endpoint allows you to retrieve a paginated list of all items belonging to a referential. By default, a maximum of ten items are shown per page.

Optional attributes

Name
page
Type
integer
Description
Number of the page to display.
Name
include
Type
string
Description
Include extra relationships using JSON:API norms.
Allowed includes: attributeValue, attributeValues, attributeValues.attributeValue

Request

GET

/v3/referentials/12/items

curl -G https://api.bx.feedier.com/v3/referentials/12/items \
    -H "Authorization: Bearer {token}" \
    -d "include"="attributeValue,attributeValues.attributeValue"

Response

{
    "data": [
        {
            "id": 501,
            "referential_id": 12,
            "attribute_value_id": 9001,
            "attribute_value": {
                "name": "employee_id",
                "label": "Employee ID",
                "value": "EMP-001"
            },
            "attribute_values": [
                {
                    "id": 1201,
                    "attribute_value_id": 9101,
                    "attribute_value": {
                        "name": "department",
                        "label": "Department",
                        "value": "Engineering"
                    },
                    "created_at": "2025-03-12T10:00:00+00:00",
                    "updated_at": "2025-03-12T10:00:00+00:00"
                }
            ],
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        }
        // ...
    ],
    "links": {
        "first": "https://api.bx.feedier.com/v3/referentials/12/items?page=1",
        "last": "https://api.bx.feedier.com/v3/referentials/12/items?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.bx.feedier.com/v3/referentials/12/items",
        "per_page": 10,
        "to": 1,
        "total": 1
    }
}

POST/v3/referentials/:id/items

Create a referential item

This endpoint allows you to create a new item in a referential. The value represents the primary attribute value of the item; if an item with the same value already exists in this referential, it is reused. When attribute_values is provided, the item's template attribute values are fully replaced by the new list.

Required attributes

Name
value
Type
string
Description
The value of the referential's primary attribute for this item. Maximum length: 750 characters.

Optional attributes

Name
attribute_values
Type
array
Description
A list of { "name": string, "value": string } objects describing the values of the template attributes attached to this item. Each value is limited to 750 characters.

Request

POST

/v3/referentials/12/items

curl https://api.bx.feedier.com/v3/referentials/12/items \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{
        "value": "EMP-001",
        "attribute_values": [
            { "name": "department", "value": "Engineering" },
            { "name": "region", "value": "EU" }
        ]
    }'

Response

{
    "id": 501,
    "referential_id": 12,
    "attribute_value_id": 9001,
    "attribute_value": {
        "name": "employee_id",
        "label": "Employee ID",
        "value": "EMP-001"
    },
    "attribute_values": [
        {
            "id": 1201,
            "attribute_value_id": 9101,
            "attribute_value": {
                "name": "department",
                "label": "Department",
                "value": "Engineering"
            },
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        },
        {
            "id": 1202,
            "attribute_value_id": 9102,
            "attribute_value": {
                "name": "region",
                "label": "Region",
                "value": "EU"
            },
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        }
    ],
    "created_at": "2025-03-12T10:00:00+00:00",
    "updated_at": "2025-03-12T10:00:00+00:00"
}

GET/v3/referentials/:id/items/:value

Retrieve a referential item

This endpoint allows you to retrieve a single referential item by providing its primary attribute value within the parent referential. Make sure to URL-encode the value when it contains special characters.

Request

GET

/v3/referentials/12/items/EMP-001

curl https://api.bx.feedier.com/v3/referentials/12/items/EMP-001 \
    -H "Authorization: Bearer {token}"

Response

{
    "id": 501,
    "referential_id": 12,
    "attribute_value_id": 9001,
    "attribute_value": {
        "name": "employee_id",
        "label": "Employee ID",
        "value": "EMP-001"
    },
    "attribute_values": [
        {
            "id": 1201,
            "attribute_value_id": 9101,
            "attribute_value": {
                "name": "department",
                "label": "Department",
                "value": "Engineering"
            },
            "created_at": "2025-03-12T10:00:00+00:00",
            "updated_at": "2025-03-12T10:00:00+00:00"
        }
    ],
    "created_at": "2025-03-12T10:00:00+00:00",
    "updated_at": "2025-03-12T10:00:00+00:00"
}

DELETE/v3/referentials/:id/items/:value

Delete a referential item

This endpoint allows you to delete a single item from a referential by providing its primary attribute value within the parent referential.

Request

DELETE

/v3/referentials/12/items/EMP-001

curl -X DELETE https://api.bx.feedier.com/v3/referentials/12/items/EMP-001 \
    -H "Authorization: Bearer {token}"