Overview

The Supplements Collection contains one or more supplemental data sets. Supplements extend the Cordial data model and support additional data related to your business.

• API set name: supplements

Use case

A rental car company may have a supplement named cars that is meant to store records associated with each vehicle they operate. The cars supplement may have an arbitrary set of fields like VIN, manufacturer, model, color, class, mileage, and location to represent the attributes about vehicles. Each vehicle is then represented as a record with field/value pairs describing that vehicle'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 altogether omitting special characters 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.

Resource associations

The following resource collections are associated to this collection.

Methods, parameters, and examples

POST /supplements

Parameters

*Required

Example JSON requests

The following will create a new supplement for cars with the indexed fields of model, year, and mileage. This supplement is not contact attribute enabled.

{
  "key": "cars",
  "name": "Cars",
  "contactObject": false,
  "indexes": [
    {
      "field": "model",
      "type": "string"
    },
    {
      "field": "year",
      "type": "number"
    },
    {
      "field": "mileage",
      "type": "number"
    }
  ]
}

Example request URIs

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

http://<path>/supplements

GET /supplements

Example request URIs

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

http://<path>/supplements

Return supplements filtered by page number and records per page: The following URI 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.

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

GET /supplements/{key}

Example request URIs

The following URI will retrieve the supplement with the key of cars, and include all fields.

http://<path>/supplements/cars

PUT /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

Same requirements and schema as the POST method above.

Example JSON requests

The following will update the supplement for cars with the indexed fields of model, year, mileage, and upgrades.

{
	"name": "Cars",
	"indexes": [{
			"field": "model",
			"type": "string"
		},
		{
			"field": "year",
			"type": "number"
		},
		{
			"field": "mileage",
			"type": "number"
		},
		{
			"field": "upgrades",
			"type": "array"
		}
	]
}

Example request URIs

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

http://<path>/supplements/cars

DELETE /supplements/{key}

Example request URIs

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

http://<path>/supplements/cars

POST /supplements/{supplement}/imports

Parameters

*Required

Specifying the "hasHeader": true parameter allows you to use the header row in the CSV as is, meaning it should match the indexed keys in a supplement file exactly. Whereas columns allows you to re-map columns based on their order in the file to the appropriate keys, so the names in the header row do not need to match, or the header row can be omitted entirely. You must include either "hasHeader": true, OR a "columns" array to map the columns.

Example JSON requests

The following will initiate an import job to load a CSV file with a header row from a secure HTTP location. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a job id for checking job status if needed.

{
	"importName": "ContactImport-7-31",
	"source": {
		"transport": "http",
		"url": "https://files.example.com/new_data.csv"
	},
	"confirmEmail": "msmith@example.com",
	"hasHeader": true
}

When import file type is JSONL, the use of "hasHeader": true parameter is currently required in order to satisfy file type validation checks.

The following will initiate an import job to load a CSV file with a header row via a secure SFTP connection over port 22. It is configured to update existing data only. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a job id for checking job status if needed.

{
	"importName": "ContactImport-7-31",
	"source": {
		"transport": "sftp",
		"server": "sftp.example.com",
		"username": "myaccountid",
		"password": "Msm1th$99!",
		"port": 22,
		"path": "/files/supp_data.csv"
	},
	"confirmEmail": "msmith@example.com",
	"strategy": "updateOnly",
	"hasHeader": true
}

The following will initiate an import job to load a CSV file with a header row via a secure s3 connection. It is configured to update existing data only. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a job id for checking job status if needed.

{
	"importName": "ContactImport-7-31",
	"source": {
		"transport": "s3",
		"aws_access_key_id": "AAAAAAAAAAAAAAAAAAAA",
		"aws_secret_access_key": "dudhKDDHE476383kdsdhdkasKDHDKDeiuealskjD",
		"aws_bucket": "a-bucket",
		"aws_region": "us-west-2",
		"path": "folder/supplement.csv"
	},
	"confirmEmail": "msmith@example.com",
	"strategy": "updateOnly",
	"hasHeader": true
}

Example request URIs

The following URI in conjunction with the JSON will perform the POST to the supplement cars.

http://<path>/supplements/cars/imports

POST /supplements/{supplement}/records

Parameters

*Required

Additional parameters or fields can be added to the JSON based on your data. This includes the indexed fields previously defined for the supplement and any fields you add as additional fields or fields declared on the fly.

Example JSON requests

The following will add a supplements record for the supplement with the key of cars. Note that these fields were all indexed fields.

{
  "id": "3324",
  "make": "Jeep",
  "model": "Liberty",
  "year": "2007"
}

The following will do the same as above, but will also add a new non-indexed field labeled comment.

{
  "id": "3324",
  "make": "Jeep",
  "model": "Liberty",
  "year": "2007",
  "comment": "vehicle is accident free"
}

Example request URIs

The following URI in conjunction with the JSON will perform the POST to the supplement cars.

http://<path>/supplements/cars/records

GET /supplements/{supplement}/records

Example request URIs

Return all records of a supplement: The following URI will retrieve all supplement records for the supplement with a key of cars and include all fields.

http://<path>/supplements/cars/records

Return records filtered by field name: The following URI will retrieve all supplement records for the supplement with a key of cars, but only include the field data for model.

http://<path>/supplements/cars/records?fields=model

Return records filtered by multiple field names: The following URI will retrieve all supplement records for the supplement with a key of cars, and include the field data for both model and year.

http://<path>/supplements/cars/records?fields=model,year

Return records filtered by field value: The following URI will retrieve all supplement records for the supplement with a key of cars, and where the value for model is prius.

http://<path>/supplements/cars/records?model=prius

Return records filtered by field value and multiple field names: The following URI will retrieve all supplement records for the supplement with a key of cars, where the value for model is prius, and include the field data for both model and price.

http://<path>/supplements/cars/records?model=prius&fields=model,price

Return records filtered by page number and records per page: The following URI will retrieve all supplement records for the supplement with a key of cars 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.

http://<path>/supplements/cars/records?page=3&per_page=10

Return records filtered by last modified date: The following URI will retrieve all supplement records for the supplement with a key of cars by last modified date in ascending order. 

http://<path>/supplements/cars/ecords?sort_by=ct&sort_dir=asc

Return records filtered by created date: The following URI will retrieve all supplement records for the supplement with a key of cars by date created in descending order.

http://<path>/supplements/cars/records?sort_by=ct&sort_dir=desc

PUT /v2/supplements/{supplement}/clear

Supplements used as contact attributes cannot be cleared using this method.

Example request URIs

Clear all supplement field entries: The following URI will clear all supplement field values for the supplement with a key of cars.

http://<path>/supplements/cars/clear

GET /supplements/{supplement}/records/{id}

Example request URIs

Return records filtered by ID: The following URI will retrieve a supplement record for the supplement with a key of cars and the supplement record id of 33415 and include all fields.

http://<path>/supplements/cars/records/33415

Return records filtered by ID and multiple field names: The following URI will retrieve a supplement record for the supplement with a key of cars, a supplement record id of 33415 and include fields for brand and model.

http://<path>/supplements/cars/records/33415&fields=brand,model

PUT /supplements/{supplement}/records/{id}

Parameters

Both existing and additional fields can be included in the JSON based on your data. This includes the indexed fields previously defined for the supplement and any fields you add as additional fields or fields declared on the fly.

Example JSON requests

The following will update the model field with the value of Grand Cherokee.

{
  "model": "Grand Cherokee"
}

The following will do the same as above, but will also add a new non-indexed field labeled annualMilesDriven.

{
  "model": "Grand Cherokee",
  "annualMilesDriven": 10000
}

Example request URIs

The following URI in conjunction with the JSON will perform the PUT to the supplement cars with the supplement record id value of 3324.

http://<path>/supplements/cars/records/3324

DELETE /supplements/{supplement}/records/{id}

Example request URIs

The following URI will delete a supplement record from the supplement with a key of cars and the supplement record id of 33415.

http://<path>/supplements/cars/records/33415

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Supplements API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it is likely recorded within the Global API Error Responses page.