How can we help?

Overview

The supplements collection contains one or more supplemental data sets. Supplements extend the Cordial data model and support a range of additional data related to your business.

• API set name: supplements

Example supplements use case
A clothing company may have a supplement named products that is meant to store records associated with each product they sell. The products supplement may have an arbitrary set of fields like SKU, name, color, category, and location to represent the attributes about clothing. Each item in the company's product catalog is then represented as a record with field/value pairs describing that item's attribute details.

Additional information

• Supplements and fields may be added at any time to your database and are immediately available to all contacts once created.
• Supplement IDs must be unique.
• Supplement IDs cannot be 24-character hex strings. This format is reserved for system use.
• Fields that will be used for search or audience building must be indexed. This is accomplished by including each field in the indexed array.
• Indexed field names within a supplement must be unique. However, the same field name can be used within different supplements.
• Individual supplement record index values cannot exceed 1024 bytes.
• Certain special characters may be interpreted as boolean operators when stored within indexed fields, which can cause supplement data query failures. We recommend omitting special characters altogether from indexed field data.
• Non-indexed fields can be entered as additional field/value pairs in the JSON or as columns within an import file.
• Indexed field definitions will enforce the type validations on record load and update. Non-indexed will not, nor will they undergo validation. This enables storing and maintaining wide latitudes of data both structured and unstructured.
• Sparse indexes are available in supplements. Learn more.

Authentication

Cordial's core APIs use HTTPS Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

• Learn more about Cordial API authentication here.

Resource associations

The following resource collections are associated to this collection.

Methods, parameters, and examples

• POST/v2/supplements
• GET/v2/supplements
• GET/v2/supplements/{key}
• PUT/v2/supplements/{key}
• DELETE/v2/supplements/{key}
• POST/v2/supplements/{supplement}/imports
• POST/v2/supplements/{supplement}/records
• GET/v2/supplements/{supplement}/records
• PUT/v2/supplements/{supplement}/clear
• GET/v2/supplements/{supplement}/records/{id}
• PUT/v2/supplements/{supplement}/records/{id}
• DELETE/v2/supplements/{supplement}/records/{id}

POST/v2/supplements

• Parameters
• Example JSON request
• Example request URL

*Required

The following will create a new supplement for products with the indexed fields of item, category, and color. This supplement is not contact attribute enabled.

{
  "key": "products",
  "name": "Products",
  "contactObject": false,
  "indexes": [
    {
      "field": "item",
      "type": "string"
    },
    {
      "field": "category",
      "type": "string"
    },
    {
      "field": "color",
      "type": "string"
    }
  ]
}

The following URL in conjunction with the JSON will perform the POST.

https://<path>/supplements

GET/v2/supplements

• Example request URLs

Return all supplements: The following URL will retrieve all supplements and include all fields.

https://<path>/v2/supplements

Return supplements filtered by page number and records per page: The following URL will retrieve all supplements starting from page 3 grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.

https://<path>/v2/supplements?page=3&per_page=10

GET/v2/supplements/{key}

• Example request URL

The following URL will retrieve the supplement with the key of products, and include all indexed fields.

https://<path>/v2/supplements/products

PUT/v2/supplements/{key}

When a supplement index field is passed, its data type (string, integer, etc.) will be recognized and searchable in the platform UI. If the field data type is later changed, any new supplement values for that field will not be searchable in the UI. It is necessary to create a new field with the updated data type if the values are to be searchable in the platform UI.

• Parameters
• Example JSON request
• Example request URL

Same requirements and schema as the POST method above.

The following will update the supplement for product with the indexed fields of item, category, color, and sales.

{
    "name": "products",
    "indexes": [
        {
            "field": "item",
            "type": "string"
        },
        {
            "field": "category",
            "type": "number"
        },
        {
            "field": "color",
            "type": "number"
        },
        {
            "field": "sales",
            "type": "array"
        }
    ]
}

The following URL in conjunction with the JSON will perform the PUT.

https://PUT/v2/supplements/products

DELETE/v2/supplements/{key}

• Example request URL

The following URL will delete the supplement with the key value of cars.

https://<path>/v2/supplements/products

POST/v2/supplements/{supplement}/imports

• Parameters
• Example JSON requests
• Example request URL

• Required

Specifying the `