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. |
Parameters
*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 |
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
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 |
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}
Method | URI Path |
---|---|
GET | /supplements/{key} |
Retrieves a supplement from the Cordial database.
The supplement is defined by the supplement's unique For example, /supplements/cars would return the response data for the supplement with the |
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}
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.
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}
Method | URI Path |
---|---|
DELETE | /supplements/{key} |
Deletes a supplement from within the Cordial database.
The supplement is defined by the supplement's unique For example, /supplements/cars would delete the supplement with the |
Example request URIs
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 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. |
Parameters
*Required
Parameter | Type | Description | Example |
---|---|---|---|
*transport | string | Transport options include HTTP, FTP, SFTP or s3. 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.
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
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 |
Parameters
*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.
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
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 For example, /supplements/cars/records would return the response data for the supplement with the |
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
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.
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}
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 For example, /supplements/cars/records/33415 would return the response data for the record with the |
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}
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 For example, /supplements/cars/records/33415 would update the record with the |
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}
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 For example, /supplements/cars/records/33415 would remove the record with the |
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.
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.