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
- POST/supplements
- GET/supplements
- GET/supplements/{key}
- PUT/supplements/{key}
- DELETE/supplements/{key}
- POST/supplements/{supplement}/imports
- POST/supplements/{supplement}/records
- GET/supplements/{supplement}/records
- PUT/v2/supplements/{supplement}/clear
- GET/supplements/{supplement}/records/{id}
- PUT/supplements/{supplement}/records/{id}
- DELETE/supplements/{supplement}/records/{id}
- Error responses
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 |
|
-
*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 ofmodel
,year
, andmileage
. 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 |
|
-
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} |
|
-
The following URI will retrieve the supplement with the
key
ofcars
, 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} |
|
-
The following URI will delete the supplement with the
key
value ofcars
.http://<path>/supplements/cars
POST/supplements/{supplement}/imports
Method | URI Path |
---|---|
POST | /supplements/{supplement}/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 |
|
-
*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
ofcars
. 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 |
|
-
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
ofcars
, 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
ofcars
, 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
ofcars
, and where the value formodel
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
ofcars
, where the value formodel
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
ofcars
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
ofcars
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
ofcars
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 |
|
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
ofcars
.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, |
-
Return records filtered by ID: The following URI will retrieve a supplement record for the supplement with a
key
ofcars
and the supplement recordid
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
ofcars
, a supplement recordid
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} |
|
-
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 recordid
value of3324
.http://<path>/supplements/cars/records/3324
DELETE/supplements/{supplement}/records/{id}
Method | URI Path |
---|---|
DELETE | /supplements/{supplement}/records/{id} |
|
-
The following URI will delete a supplement record from the supplement with a
key
ofcars
and the supplement recordid
of33415
.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.