Cordial Supplements API

openapi: 3.2.0
info:
  title: Cordial Supplements API
  termsOfService: https://cordial.zendesk.com
  version: '1.0'
  description: 'Operations tagged supplements across 2 of this provider''s published API definitions: cordial-v1-openapi-original.json, cordial-v2-openapi-original.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cordial.io/
tags:
- name: supplements
paths:
  /v1/supplements/{key}:
    get:
      security:
      - basicAuth: []
      summary: Get a single supplement
      tags:
      - supplements
      operationId: getsupplement
      parameters:
      - name: key
        description: Key for attribute
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Fields (can be many, separate by comma)
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementShowSup'
        '422':
          description: record not found
    put:
      security:
      - basicAuth: []
      summary: Update a single supplement
      tags:
      - supplements
      operationId: updatesupplement
      parameters:
      - name: key
        description: Key for attribute
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementUpdateSup'
        '422':
          description: record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementUpdateSup'
        description: Supplement object that needs to be updated to the system
        required: true
    delete:
      security:
      - basicAuth: []
      summary: Delete supplement
      tags:
      - supplements
      operationId: deletesupplements
      parameters:
      - name: key
        description: Supplement key
        required: true
        in: path
        schema:
          type: string
      responses:
        '400':
          description: unable to validate segment participation
  /v1/supplements:
    post:
      security:
      - basicAuth: []
      summary: Add a new supplement
      tags:
      - supplements
      operationId: addsupplement
      responses:
        '200':
          description: successful operation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementSup'
        description: Supplement object that needs to be added to the system
        required: true
    get:
      security:
      - basicAuth: []
      summary: Get supplements
      tags:
      - supplements
      operationId: getsupplements
      parameters:
      - name: page
        description: Number of page
        required: false
        in: query
        schema:
          type: string
      - name: per_page
        description: Count supplements on page
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplementUpdateSup'
        '422':
          description: record not found
  /v1/supplements/{supplement}/clear:
    put:
      security:
      - basicAuth: []
      summary: Clear a single supplement
      tags:
      - supplements
      operationId: clearsupplement
      parameters:
      - name: supplement
        description: Supplement Key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '422':
          description: record not found
  /v1/supplements/{supplement}/records:
    get:
      security:
      - basicAuth: []
      summary: Get records from a supplement
      tags:
      - supplements
      operationId: getsupplementrecords
      parameters:
      - name: supplement
        description: Supplement Key
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Fields (can be many, separate by comma)
        required: false
        in: query
        schema:
          type: string
      - name: page
        description: Number of page
        required: false
        in: query
        schema:
          type: string
      - name: per_page
        description: Count supplements on page
        required: false
        in: query
        schema:
          type: string
      - name: sort_by
        description: Sort field
        required: false
        in: query
        schema:
          type: string
      - name: sort_dir
        description: Sort direction
        required: false
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecordSup'
        '422':
          description: record not found
    post:
      security:
      - basicAuth: []
      summary: Add records to a supplement
      tags:
      - supplements
      operationId: addsupplementrecord
      parameters:
      - name: supplement
        description: Supplement Key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '422':
          description: record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordSup'
        description: Record object that needs to be added to the system
        required: true
  /v1/supplements/{supplement}/records/{id}:
    get:
      security:
      - basicAuth: []
      summary: Get a single supplement record
      tags:
      - supplements
      operationId: getsupplementrecord
      parameters:
      - name: supplement
        description: Supplement Key
        required: true
        in: path
        schema:
          type: string
      - name: id
        description: Record ID
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordSup'
        '422':
          description: record not found
    put:
      security:
      - basicAuth: []
      summary: Update a single supplement record
      tags:
      - supplements
      operationId: updatesupplementrecord
      parameters:
      - name: supplement
        description: Supplement Key
        required: true
        in: path
        schema:
          type: string
      - name: id
        description: Record ID
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '422':
          description: record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordSup'
        description: Record object that needs to be updated in the system
        required: true
    delete:
      security:
      - basicAuth: []
      summary: Delete a single supplement record
      tags:
      - supplements
      operationId: deletesupplementrecord
      parameters:
      - name: supplement
        description: Supplement Key
        required: true
        in: path
        schema:
          type: string
      - name: id
        description: Record ID
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '422':
          description: record not found
  /v1/supplements/{supplement}/imports:
    post:
      security:
      - basicAuth: []
      summary: Add a new job
      tags:
      - supplements
      operationId: importsupplementrecords
      parameters:
      - name: supplement
        description: Supplement Key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '422':
          description: record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobSup'
        description: Job object that needs to be added to the system
        required: true
  /v2/supplements/{key}:
    get:
      security:
      - basicAuth: []
      summary: Get a single supplement
      description: Retrieves the specified supplement from the Cordial database. The supplement is defined by its unique `key` value. For example, /supplements/cars would return the response data for the supplement with the key of <b>cars</b>.
      tags:
      - supplements
      operationId: getsupplement
      parameters:
      - name: key
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Fields to include (can be many, comma-separated).
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementResponse'
        '404':
          $ref: '#/components/responses/RecordNotFound'
    put:
      security:
      - basicAuth: []
      summary: Update a single supplement
      description: Updates a supplement in the Cordial database using the appropriate JSON body. The supplement is defined by its unique `key` value. For example, /supplements/cars would update the supplement with the key of <b>cars</b>.
      tags:
      - supplements
      operationId: updatesupplement
      parameters:
      - name: key
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessOperation'
        '422':
          description: record not found
          $ref: '#/components/responses/SupplementUpdateError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementUpdateSup_2'
        description: Supplement object that needs to be updated.
        required: true
    delete:
      security:
      - basicAuth: []
      summary: Delete supplement
      description: Deletes a supplement collection from the Cordial database. The supplement is defined by its unique `key` value. For example, /supplements/cars would delete the supplement with the key value of <b>cars</b>.
      tags:
      - supplements
      operationId: deletesupplements
      parameters:
      - name: key
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessOperation'
        '422':
          description: Error on removing supplement
          $ref: '#/components/responses/SupplementRemove'
  /v2/supplements:
    post:
      security:
      - basicAuth: []
      summary: Add a supplement
      description: 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. These non-indexed fields are available for message content, but not available for searching or filtering via Smarty. Posting more than once for the same supplement key will generate an error.
      tags:
      - supplements
      operationId: addsupplement
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessOperation'
        '422':
          $ref: '#/components/responses/SupplementValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementSup_2'
        description: Supplement object that needs to be added.
        required: true
    get:
      security:
      - basicAuth: []
      summary: Get supplements
      description: Retrieves all supplements from the Cordial database. When retrieving a large number of supplements, it is possible to apply the `per_page` and `page` query string parameters to limit the count returned along with page position.
      tags:
      - supplements
      operationId: getsupplements
      parameters:
      - name: page
        description: Specific page number to be returned.
        required: false
        in: query
        schema:
          type: string
      - name: per_page
        description: Number or records per page.
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SupplementResponse'
        '404':
          $ref: '#/components/responses/RecordNotFound'
  /v2/supplements/{supplement}/clear:
    put:
      security:
      - basicAuth: []
      summary: Clear a single supplement
      description: '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 its unique `key` value. For example, /supplements/cars/clear would clear the field values in the supplement with a key of <b>cars</b>.'
      tags:
      - supplements
      operationId: clearsupplement
      parameters:
      - name: supplement
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessOperation'
        '404':
          $ref: '#/components/responses/RecordNotFound'
  /v2/supplements/{supplement}/records:
    get:
      security:
      - basicAuth: []
      summary: Get records from a supplement
      description: 'Retrieves all records within the specified supplement collection. The supplement is defined by its unique `key` value.


        For example, /supplements/cars/records would return the response data for the supplement with the key value of <b>cars</b>.'
      tags:
      - supplements
      operationId: getsupplementrecords
      parameters:
      - name: supplement
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Fields to include (can be many, comma-separated).
        required: false
        in: query
        schema:
          type: string
      - name: page
        description: Specific page number to be returned.
        required: false
        in: query
        schema:
          type: string
      - name: per_page
        description: Number or records per page.
        required: false
        in: query
        schema:
          type: string
      - name: sort_by
        description: Field by which results should be sorted.
        required: false
        in: query
        schema:
          type: string
      - name: sort_dir
        description: Direction to sort by. Works in conjunction with `sort_by` (e.g. asc, desc).
        required: false
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: return_count
        description: Show the total count of records returned.
        required: false
        in: query
        schema:
          type: boolean
          enum:
          - true
          - false
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecordSupplementResponse'
        '404':
          description: Records not found
          $ref: '#/components/responses/RecordNotFound'
        '422':
          description: Supplement does not exist
          $ref: '#/components/responses/SupplementDoesntExist'
    post:
      security:
      - basicAuth: []
      description: Creates a new data record in the specified supplement collection 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 once for the same record `id` will update the existing data record.
      summary: Add records to a supplement
      tags:
      - supplements
      operationId: addsupplementrecord
      parameters:
      - name: supplement
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementRecordCreationSuccess'
        '422':
          description: Validation error
          $ref: '#/components/responses/SupplementRecordPostResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementRecordPost'
        description: Record object that needs to be added.
        required: true
  /v2/supplements/{supplement}/records/{id}:
    get:
      security:
      - basicAuth: []
      summary: Get a single supplement record
      description: 'Retrieves a record from the specified supplement collection. The supplement is defined by its unique `key` value and the supplement record is defined by its unique `id` value.


        For example, /supplements/cars/records/33415 would return the response data for the record with the id value <b>33415</b> from the <b>cars</b> supplement collection.'
      tags:
      - supplements
      operationId: getsupplementrecord
      parameters:
      - name: supplement
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      - name: id
        description: Unique supplement record id.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordSupplementResponse'
        '404':
          description: Records not found
          $ref: '#/components/responses/RecordNotFound'
        '422':
          description: Supplement does not exist
          $ref: '#/components/responses/SupplementDoesntExist'
    put:
      security:
      - basicAuth: []
      summary: Update a single supplement record
      description: 'Updates an existing data record in the specified supplement collection using the appropriate JSON body. The supplement is defined by its unique `key` value and the supplement record is defined by its unique `id` value.


        For example, /supplements/cars/records/33415 would update the record with the id value <b>33415</b> within the <b>cars</b> supplement collection. It is possible to update any number of field values.'
      tags:
      - supplements
      operationId: updatesupplementrecord
      parameters:
      - name: supplement
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      - name: id
        description: Unique supplement record id.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessOperation'
        '400':
          description: Validation error
          $ref: '#/components/responses/SupplementRecordPutResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementRecordPost'
        description: Supplement object that needs to be updated.
        required: true
    delete:
      security:
      - basicAuth: []
      summary: Delete a single supplement record
      description: 'Deletes a supplement record and its data from the specified supplement collection. The supplement is defined by its unique `key` value and the supplement record is defined by its unique `id` value.


        For example, /supplements/cars/records/33415 would remove the record with the id value <b>33415</b> from the <b>cars</b> supplement collection.'
      tags:
      - supplements
      operationId: deletesupplementrecord
      parameters:
      - name: supplement
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      - name: id
        description: Unique supplement record id.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessOperation'
        '404':
          description: Records not found
          $ref: '#/components/responses/RecordNotFound'
        '422':
          description: Supplement does not exist
          $ref: '#/components/responses/SupplementDoesntExist'
  /v2/supplements/{supplement}/imports:
    post:
      security:
      - basicAuth: []
      description: 'Creates a supplement record import job using the JSON body information. The import file must contain an `id` field that uniquely identifies each supplement data record. By default, importing records with an `id` that already exists will overwrite the existing data record.


        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 sent to the specified email address when the job is done. This is helpful for larger imports that require some time to process.'
      summary: Create a supplement record import job
      tags:
      - supplements
      operationId: importsupplementrecords
      parameters:
      - name: supplement
        description: Supplement key value.
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementImportConfigSuccess'
        '406':
          description: Import configuration error
          $ref: '#/components/responses/SupplementImportConfigError'
        '422':
          description: record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementImportResource'
        description: JSON body information to create the import job.
        required: true
components:
  schemas:
    SupplementSup:
      title: Supplement
      type: object
      required:
      - key
      - indexes
      properties:
        key:
          description: Unique identifier for the Supplement
          type: string
        name:
          type: string
        indexes:
          type: array
          items:
            $ref: '#/components/schemas/IndexesSup'
    IndexesSup_2:
      title: Indexes
      type: object
      required:
      - field
      - type
      properties:
        field:
          type: string
          description: The name of the field. Required to be unique within the context of this supplement only.
          example: model
        type:
          type: string
          description: 'Defines the field data type. Possible values: string, number, date, geo, array.'
          example: string
    SupplementResponse:
      title: Supplement
      type: object
      required:
      - key
      properties:
        key:
          description: Unique identifier for the supplement.
          type: string
          example: cars
        name:
          type: string
          description: The name of the supplement.
          example: Cars
        indexes:
          type: array
          description: Individual supplement record index values cannot exceed 1024 bytes.
          example:
          - field: model
            type: string
          items:
            $ref: '#/components/schemas/IndexesSup_2'
        createdAt:
          type: string
          format: date-time
        lastDataUpdate:
          type: string
          format: date-time
        contactObject:
          type: boolean
          description: 'Using a supplement as a contact attribute allows you to store a complex data object for each contact. Note: each record must contain ''email'' or ''cID'''
          example: true
        autogenerateIDs:
          type: boolean
          default: false
          description: Generates a 24-character random hash for inserted supplement records where the ID is not supplied.
    SupplementUpdateSup_2:
      title: SupplementUpdate
      type: object
      required:
      - name
      - indexes
      properties:
        name:
          type: string
          description: Supplement name.
          example: Cars
        indexes:
          type: array
          description: 'Fields that will serve as search indexes (e.g. [{"field": "model","type": "string"}]). Individual supplement record index values cannot exceed 1024 bytes.'
          example:
          - field: model
            type: string
          items:
            $ref: '#/components/schemas/IndexesSup_2'
        contactObject:
          type: boolean
          description: 'Enables the use of this supplement as a contact attribute for audience segmentation. Possible values: true, false.'
          example: true
        autogenerateIDs:
          type: boolean
          default: false
          description: Generates a 24-character random hash for inserted supplement records where the ID is not supplied.
    SupplementRecordPostResponse:
      title: ''
      required:
      - error
      - errorKey
      properties:
        error:
          type: boolean
          example: true
        errorKey:
          type: string
          example: GENERIC_ERROR_KEY
        message:
          type: object
          $ref: '#/components/schemas/validationSupplementErrors'
          description: 'String or object. Possible errors: [''Must include email or secondaryKey email,cID,push'', ''The supplement \''supplementKey\'' does not exist'', ''Field type can''t be changed'', ''empty post'', ''record not found'', ''id is required'', ''Error occurred on validation supplement record.'']'
    SupplementValidationError:
      title: Validation error
      required:
      - messages
      - errorKey
      - error
      properties:
        error:
          type: boolean
          example: true
        errorKey:
          type: string
          example: GENERIC_ERROR_KEY
        messages:
          type: object
          $ref: '#/components/schemas/validationSupplementErrors'
        message:
          type: string
          description: 'Errors. Possible errors: [''Field type can''t be changed.'']'
    SupplementDoesntExist:
      title: ''
      required:
      - error
      - errorKey
      properties:
        error:
          type: boolean
          example: true
        errorKey:
          type: string
          example: GENERIC_ERROR_KEY
        message:
          type: string
          example: The supplement 'supplementKey' does not exist.
          description: Returned if supplement doesn't exist.
    SupplementShowSup:
      title: Supplement
      type: object
      required:
      - key
      properties:
        key:
          description: Unique identifier for the Supplement
          type: string
        name:
          type: string
        indexes:
          type: array
          items:
            $ref: '#/components/schemas/IndexesSup'
        createdAt:
          type: string
          format: date
        lastDataUpdate:
          type: string
          format: date
    RecordSupplementResponse:
      title: Record
      type: object
      required:
      - id
      properties:
        id:
          type: string
          example: '1234212'
          description: Unique record ID for each supplement in a collection. Cannot be a 24-character hex string.
        attributes:
          schema:
            properties:
              cID:
                type: string
                example: 5f27b8c3965afd5165265393
                description: Contact ID that connects to current supplement record.
              ct:
                type: string
                format: date-time
                description: Date created.
              lm:
                type: string
                format: date-time
                description: Last modified date.
              created:
                type: string
                format: date-time
                description: Date created.
            example:
              id: '3324'
              make: Jeep
              model: Liberty
              year: '2007'
              lm: 2020-09-22T09:00:29+0000
              ct: 2020-09-22T09:00:29+0000
              created: 2020-09-22T09:00:29+0000
              cID: 5f27b8c3965afd5165265393
            description: Response data for the record.
          type: object
    validationSupplementPutErrors:
      required:
      - validationErrors
      properties:
        validationErrors:
          type: object
          description: 'Object with validation error explanation for each field from payload. Possible errors: [''id is required'', ''<field> is required'',''The <field> must be a number.'']'
    SupplementUpdateError:
      title: ''
      required:
      - error
      - errorKey
      properties:
        error:
          type: boolean
          example: true
        errorKey:
          type: string
          example: GENERIC_ERROR_KEY
        messages:
          type: object
          $ref: '#/components/schemas/validationSupplementErrors'
          description: This field is present in case we receive validation errors on supplement updates. String or object.
        message:
          type: string
          example: '''supplementKey'' provided but no record found'
          description: Present if 'supplement' doesn't exist.
    SupplementImportConfigError:
      title: Import configuration error
      required:
      - error
      - message
      - errorKey
      properties:
        error:
          type: boolean
          example: true
        errorKey:
          type: string
          example: GENERIC_ERROR_KEY
        message:
          type: string
          example: The source.transport field is required.
          description: 'Field is present if import configuration is wr

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cordial/refs/heads/main/openapi/cordial-supplements-api-openapi.yml