How can we help?

Supplements API

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.

Collection Association
contacts Supplements data can be associated back to a contact if the contactId is stored in a record.

Methods, parameters, and examples

POST/supplements

Method URI Path
POST /supplements
  • Creates a new supplement in the Cordial database using the appropriate JSON body.
  • Fields that will serve as search indexes need to be placed in the indexed array of fields. Additional non-indexed fields can be added in the JSON records, or by declaring the field as a column in an import file.
  • Posting more than one time for the same supplement key will generate an error.
  • *Required

    Parameter Type Description Example
    Supplement
    *key string Unique supplement identifier. cars
    Indexes (array) - Individual supplement record index values cannot exceed 1024 bytes.
    *field string The name of the field. Required to be unique within the context of this supplement only. model
    *type string Defines the field's data type. Options include: string, number, date, geo, or array. string
    Supplement
    name string The name of the supplement Cars
    contactObject boolean Enables the use of this supplement as a contact attribute for audience segmentation. Possible values: true or false. true
  • 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"
        }
      ]
    }
  • The following URI in conjunction with the JSON will perform the POST.

    http://<path>/supplements

GET/supplements

Method URI Path
GET /supplements
  • Retrieves all supplements from the Cordial database.
  • When retrieving a large amount of supplements in the response, it is possible to apply the per_page and page query string parameters to limit the count returned and page position.
  • 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}

Method URI Path
GET /supplements/{key}
  • Retrieves a supplement from the Cordial database.
  • The supplement is defined by the supplement's unique key value.
  • For example, /supplements/cars would return the response data for the supplement with the key of cars.
  • The following URI will retrieve the supplement with the key of cars, and include all fields.

    http://<path>/supplements/cars
    

PUT/supplements/{key}

Method URI Path
PUT /supplements
Updates a supplement in the Cordial database using the appropriate JSON body.

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.

  • Same requirements and schema as the POST method above.

  • 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"
    }
    ]
    }
  • The following URI in conjunction with the JSON will perform the POST.

    http://<path>/supplements/cars

DELETE/supplements/{key}

Method URI Path
DELETE /supplements/{key}
  • Deletes a supplement from within the Cordial database.
  • The supplement is defined by the supplement's unique key value.
  • For example, /supplements/cars would delete the supplement with the key value of cars.
  • The following URI will delete the supplement with the key value of cars.

    http://<path>/supplements/cars

POST/supplements/{supplement}/imports

Method URI Path
POST /supplements/{supplement}/imports
  • Creates a supplement data import job using the JSON body information.
  • Permissible import file types: CSV and JSONL.
  • The import file must contain an id field that uniquely identifies each record in a supplement. By default, existing supplements records are overwritten and new supplements are added.
  • Column headers can include one or more indexed fields along with any other optional non-indexed fields of your choosing.
  • If needed, an optional email confirmation can be set to trigger upon completion. This is helpful for larger imports.
  • *Required

    Parameter Type Description Example
    *transport string Transport options include HTTP, FTP, SFTP, s3, or Snowflake. Note that HTTP also incorporates HTTPS. http
    *url string URL or location of the import file. http://files.example.com/123
    server string Defines FTP or SFTP when using a file transport protocol (FTP) transport. ftp
    username string An account username for gaining access to the file location. file-access-acct
    password string The account password for the above user name. Msm1th$99!
    port string if transport = FTP or SFTP, and not using default 44
    path string Options are FTP, SFTP and s3 only ftp
    aws_access_key_id string if transport = s3, public  AWS id asdf9g8asg89gd
    aws_secret_access_key string if transport = s3, secret AWS key dudhKDDHE476383kdsdhdkasK
    aws_bucket string if transport = s3, AWS bucket name some-bucket
    aws_region string if transport = s3, AWS region us-west-2
    job
    confirmEmail string Email address to send confirmation status message. msmith@example.com
    strategy string Options are insertOnly and updateOnly. If a strategy is not provided, by default records will be inserted and updated. updateOnly
    *hasHeader boolean Required if columns is not included. Denotes the first row column headers are present, default is false. true
    *columns array Required, if hasHeader is not explicitly set to true. Array of column headers, ordered by column positionally left to right. ["model", "year", "milage"]
    nullMarker string Defines the value to use for ignoring or skipping attribute updates.
    Upon import, if an attribute contains the nullMarker value (i.e. skip), then the attribute will be skipped or ignored.
    skip
    delimiter string Defines the data separation delimiter.

    , - comma

    : - colon

    \t - tab

    importName string Import job name that will be displayed alongside the job ID in the Jobs Widget. May only contain letters, numbers, and dashes. Does not accept whitespaces.

    ContactImport-7-31

    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.

  • 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
    }
  • 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

Method URI Path
POST /supplements/{supplement}/records
  • Creates a new data record in the specified supplement in the Cordial database using the appropriate JSON body.
  • The record must include values for each of the indexed fields along with any other optional non-indexed fields of your choosing. The values provided for the indexed fields cannot be empty strings. Posting more than one time for the same record id value within a supplement will update the existing record.
  • *Required

    Parameter Type Description Example
    *id string Unique record ID for each supplement in a collection. Cannot be a 24 character hex string. 1234212

    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.

  • 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"
    }
  • 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

Method URI Path
GET /supplements/{supplement}/records
  • Retrieves all records for a specific supplement from the Cordial database.
  • The supplement is defined by the supplement key value.
  • For example, /supplements/cars/records would return the response data for the supplement with the key value of cars.
  • 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

Method URI Path
PUT /supplements/{supplement}/clear
  • Updates a supplement by clearing all previously added field values. Supplement name, key, and indexes will remain in the Cordial database and the supplement can be updated again with new values for the fields.
  • The supplement is defined by the supplement key value.
  • For example, /supplements/cars/clear would clear the field values in the supplement with a key of cars.

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

  • 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}

Method URI Path
GET /supplements/{supplement}/records/{id}
Retrieves a record for a specific supplement from the Cordial database.

The record is defined by the supplement key value and the record id value.

For example, /supplements/cars/records/33415 would return the response data for the record with the id value 33415 from within the supplement cars.

  • 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}

Method URI Path
PUT /supplements/{supplement}/records/{id}
  • Updates an existing record in the specified supplement in the Cordial database using the appropriate JSON body.
  • The record is defined by the supplement key value and the record id value.
  • For example, /supplements/cars/records/33415 would update the record with the id value 33415 from within the supplement cars. It is possible to update any number of field values.
  • 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.

  • 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
    }
  • 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}

Method URI Path
DELETE /supplements/{supplement}/records/{id}
  • Deletes a record and its data for a specific supplement from the Cordial database.
  • The record resource is defined by the supplement's unique key value and the record's unique id value.
  • For example, /supplements/cars/records/33415 would remove the record with the id value 33415 from within the supplement cars.
  • 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.

errorKey Message Modifications
SUPPLEMENTS_SERVICE_ERROR API endpoint not available No Supplement repository was able to be instantiated.
SUPPLEMENTS_KEY_ALREADY_EXIST Key already exists The key must be unique.
SUPPLEMENTS_FIELD_RESERVED Field(s) :reserved is reserved for supplement records Reserved words may not be used.
SUPPLEMENTS_PRIMARY_KEY_ADDED_LIKE_INDEX primaryKey should not be added as an index The primaryKey should not be added as an index.
SUPPLEMENTS_FIELD_TYPE_CHANGED Field type can't be changed. The Supplement field type cannot be changed.
SUPPLEMENTS_WITH_KEY_NOT_EXIST Supplement with key :key does not exist The provided key did not return a Supplement.
SUPPLEMENTS_REMOVING_SUPPLEMENT_ERROR Internal error has occurred at attempt to delete a supplement :key An error has occurred while attempting to delete the Supplement.
SUPPLEMENTS_ID_CANT_BE_UPDATED ID cannot be updated The Supplement's ID cannot be updated.
SUPPLEMENTS_EMPTY_POST Empty post The empty post is invalid.
SUPPLEMENTS_ERROR_ON_REMOVING_SUPPLEMENT Error occurred on removing supplement records. Unable to remove the Supplement record.
SUPPLEMENTS_KEY_NOT_EXIST_IN_SUPPLEMENT Warning, the index name :key does not exist for the supplement :supplement. Please check to make sure to create this index or check the spelling of the index name. Please check to make sure to create this index or check the spelling of the index name.
VALIDATION_ERROR Error occurred on validation supplement record. Ensure the Supplement's fields are entered correctly.
SUPPLEMENTS_MAPPING_UPDATE_FAILED Update mapping for supplements index failed. Update mapping for the Supplement's index failed.

Comments

0 comments

Please sign in to leave a comment.