Cordial Contacts API

openapi: 3.2.0
info:
  title: Cordial Contacts API
  termsOfService: https://cordial.zendesk.com
  version: '1.0'
  description: 'Operations tagged contacts 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: contacts
paths:
  /v1/contacts/{primary_key}/downloadprofile:
    post:
      security:
      - basicAuth: []
      summary: Export Contact Profile
      operationId: buildcontactprofile
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: jobId
        '404':
          description: Record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCPB'
        description: Export contact profile
        required: true
  /v1/contacts:
    post:
      security:
      - basicAuth: []
      summary: Add a new contact to the system
      operationId: addContact
      tags:
      - contacts
      responses:
        '201':
          description: record created
        '405':
          description: Invalid input
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactC'
        description: Contact object that needs to be added to the system
        required: true
    get:
      security:
      - basicAuth: []
      summary: Get contacts
      operationId: getContacts
      tags:
      - contacts
      parameters:
      - name: email
        description: Email for search
        required: false
        in: query
        schema:
          type: string
      - name: audience-key
        description: Audience name for filtering contacts
        required: false
        in: query
        schema:
          type: string
      - name: page
        description: Page number
        required: false
        in: query
        schema:
          type: string
      - name: per_page
        description: Number of records returned
        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
      - name: return_count
        description: Return count of records
        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/ContactC'
        '404':
          description: Record not found
  /v1/contacts/{primary_key}:
    put:
      security:
      - basicAuth: []
      summary: Update an existing contact
      operationId: updateContacts
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '404':
          description: Record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactC'
        description: Contact object that needs to be updated in the system
        required: true
    get:
      security:
      - basicAuth: []
      summary: Get a single contact
      operationId: getsinglecontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactC'
        '404':
          description: Record not found
    delete:
      security:
      - basicAuth: []
      summary: Delete a single contact
      operationId: deletesinglecontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '404':
          description: Record not found
  /v1/contacts/{primary_key}/unsubscribe/{channel}:
    put:
      security:
      - basicAuth: []
      summary: Unsubscribe contact by primary Key with channel
      operationId: unsubscribecontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      - name: channel
        description: Specified channel
        required: true
        in: path
        schema:
          type: string
      - name: mcID
        description: mcID provided for attribution purposes
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '404':
          description: Record not found
  /v1/contacts/{primary_key}/cart:
    post:
      security:
      - basicAuth: []
      summary: Add cart object to contact
      operationId: savecartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '404':
          description: Record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartC'
        description: Cart object that needs to be updated in the system
        required: true
    put:
      security:
      - basicAuth: []
      summary: Update cart
      operationId: updatecartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '404':
          description: Record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartC'
        description: Cart object that needs to be updated in the system
        required: true
    delete:
      security:
      - basicAuth: []
      summary: Remove cart object from contact
      operationId: clearcartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '404':
          description: Record not found
  /v1/contacts/{primary_key}/cartitems:
    post:
      security:
      - basicAuth: []
      summary: Add product to cart
      operationId: addproducttocartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartitemsC'
        '404':
          description: Record not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartitemsC'
        description: Cartitem object that needs to be updated in the system
        required: true
  /v1/contacts/{primary_key}/cartitems/{productID}:
    delete:
      security:
      - basicAuth: []
      summary: Remove product from cart
      operationId: removeproducttocartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      - name: productID
        description: Product ID
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '404':
          description: Record not found
  /v1/contacts/{primary_key}/cartitems/{productID}/{qty}:
    delete:
      security:
      - basicAuth: []
      summary: Remove product from cart by Qty
      operationId: removeproducttocartqtycontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Primary key
        required: true
        in: path
        schema:
          type: string
      - name: productID
        description: Product ID
        required: true
        in: path
        schema:
          type: string
      - name: qty
        description: Quantity
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
        '404':
          description: Record not found
  /v2/contacts:
    post:
      security:
      - basicAuth: []
      summary: Add a contact
      description: Creates a new contact record using the appropriate JSON body. The contact object can optionally include attribute values and list associations. Note that contact attribute keys and list names must be created in advance using the Cordial UI or the <b>/accountcontactattributes</b> and <b>/accountlists</b> API endpoints.
      operationId: addContact
      tags:
      - contacts
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactCreated'
        '422':
          description: Creation contact errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCPost'
        description: Contact object that needs to be added.
        required: true
    get:
      security:
      - basicAuth: []
      summary: Get contacts
      description: Retrieves contact records from the Cordial database. It is possible to filter the response using query string parameters including a unique contact identifier to retrieve information for a single contact, saved audience rule to limit the response to contacts in an audience, and by contact attribute key to get contact records with a specified attribute value.
      operationId: getContacts
      tags:
      - contacts
      parameters:
      - name: email
        description: Filter records for a specific contact using the email address value.
        required: false
        in: query
        schema:
          type: string
      - name: audience-key
        description: Filter records for contacts in an audience using a saved audience rule key.
        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/ContactC_2'
        '404':
          $ref: '#/components/responses/RecordNotFound'
  /v2/contacts/{primary_key}:
    put:
      security:
      - basicAuth: []
      summary: Update a contact
      description: Updates a contact record using the appropriate JSON body.
      operationId: updateContacts
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: 'Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key: secondary_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'
        '422':
          description: Update contact errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCPut'
        description: Contact object that needs to be updated.
        required: true
    get:
      security:
      - basicAuth: []
      summary: Get a single contact
      description: Retrieves a single contact record and the associated contact attribute values.
      operationId: getsinglecontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_key_value>`.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactC_2'
        '404':
          $ref: '#/components/responses/RecordNotFound'
    delete:
      security:
      - basicAuth: []
      summary: Delete a single contact
      description: Deletes a contact record and the associated account attribute values.
      operationId: deletesinglecontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_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/contacts/{primary_key}/unsubscribe/{channel}:
    put:
      security:
      - basicAuth: []
      summary: Unsubscribe a contact
      description: Unsubscribes a contact from the specified channel. Contacts can be associated with multiple channels (email, SMS, push, etc.), each channel having a subscribe status of either subscribed, unsubscribed, or none. Promotional messages will not be sent to <b>unsubscribed</b> contacts.
      operationId: unsubscribecontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_key_value>`.
        required: true
        in: path
        schema:
          type: string
      - name: channel
        description: Unique channel key (e.g. email, sms, push or a custom-named channel key).
        required: true
        in: path
        schema:
          type: string
      - name: mcID
        description: Unique message contact ID (mcID) typically used for tracking revenue attribution.
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessOperation'
        '404':
          $ref: '#/components/responses/RecordNotFound'
        '422':
          $ref: '#/components/responses/ContactUnsubscribeError'
  /v2/contacts/merge:
    post:
      security:
      - basicAuth: []
      summary: Merges two contacts
      description: Merges one contact (source) into another (destination) in the Cordial database using the appropriate JSON body.
      operationId: mergecontacts
      tags:
      - contacts
      responses:
        '201':
          description: On successful operation returns a jobId and a message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeContactsSuccess'
        '403':
          description: When an account does not have an ability to merge contacts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeContactsFeatureError'
        '422':
          description: When the request is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeContactsError'
        '500':
          description: When an unexpected internal error occurs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergeContactsServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MergeContacts'
        description: An object that contains necessary parameters
        required: true
  /v2/contacts/split:
    post:
      security:
      - basicAuth: []
      summary: Splits a contact
      description: Splits part of the existing contact into a new contact. Requires a contacts split feature to be enabled.
      operationId: splitContact
      tags:
      - contacts
      responses:
        '202':
          description: On successful operation returns accepted message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitContactSuccess'
        '403':
          description: When the contacts split feature is not available for an account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitContactNotAvailable'
        '404':
          description: When the contact cannot be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitContactNotFoundError'
        '422':
          description: When the request is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitContactRequestError'
        '500':
          description: Something went wrong on the application side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitContactApplicationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SplitContact'
        description: An object that contains necessary parameters
        required: true
  /v2/contacts/{primary_key}/cart:
    post:
      security:
      - basicAuth: []
      summary: Add contact cart object
      description: Adds a cart object to the contact record.
      operationId: savecartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_key_value>`.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessOperation'
        '422':
          $ref: '#/components/responses/ContactCartError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartC_2'
        description: Cart object that needs to be added.
        required: true
    put:
      security:
      - basicAuth: []
      summary: Update contact cart object
      description: Updates the cart object for the contact record.
      operationId: updatecartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_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'
        '422':
          $ref: '#/components/responses/ContactCartError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartC_2'
        description: Cart object that needs to be updated.
        required: true
    delete:
      security:
      - basicAuth: []
      summary: Remove contact cart object
      description: Removes the cart object from the contact record.
      operationId: clearcartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_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'
        '422':
          $ref: '#/components/responses/ContactCartError'
  /v2/contacts/{primary_key}/cartitems:
    post:
      security:
      - basicAuth: []
      summary: Add product to cart
      description: Adds a product to the contact's cart.
      operationId: addproducttocartcontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_key_value>`.
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartitemsC_2'
        '422':
          $ref: '#/components/responses/ContactCartError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartitemsC_2'
        description: Cart item object that needs to be added.
        required: true
  /v2/contacts/{primary_key}/cartitems/{productID}/{qty}/{sku}:
    delete:
      security:
      - basicAuth: []
      summary: Remove product from cart in quantities by product ID and, optionally, SKU
      description: Removes the specified quantity of a product from the contact's cart.
      operationId: removeproducttocartqtycontact
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_key_value>`.
        required: true
        in: path
        schema:
          type: string
      - name: productID
        description: Product id value.
        required: true
        in: path
        schema:
          type: string
      - name: qty
        description: Quantity of product to be removed.
        required: true
        in: path
        schema:
          type: string
      - name: sku
        description: Product SKU 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'
        '422':
          $ref: '#/components/responses/ContactCartError'
  /v2/contacts/{primary_key}/downloadprofile:
    post:
      security:
      - basicAuth: []
      summary: Download contact profile
      description: Creates an export job to download and store a JSON file of a contact's profile including channel association, contact attributes, and event data. Destination parameters are only required if FTP/SFTP is used as the destination. If parameters are not supplied or set as "AWS", the exported file can be downloaded via the Jobs page from the Cordial UI.
      operationId: buildcontactprofile
      tags:
      - contacts
      parameters:
      - name: primary_key
        description: Contact identifier to look up and reference the contact record. Possible identifier variations include `<cID_value>`, or `<primary_key_value>` or `<secondary_key:secondary_key_value>`.
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: jobId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactDownloadProfileSuccess'
        '404':
          $ref: '#/components/responses/RecordNotFound'
        '422':
          $ref: '#/components/responses/ContactDownloadProfileError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCPB_2'
        description: JSON body information to create the export job.
        required: true
components:
  schemas:
    ContactCPost:
      title: Contact
      type: object
      required:
      - channels
      properties:
        channels:
          $ref: '#/components/schemas/ChannelC'
        attribute_key:
          type: string
          description: 'Adds a value for string, date (ISO 8601 format), number, array, or geo ("geo_attribute_key.city": "San Diego") contact attribute types.'
        list_name:
          type: boolean
          description: 'Adds or removes the contact from a list. Possible values: true, false'
        suppressTriggers:
          type: boolean
          description: If `true`, will suppress triggering messages set to fire based on updates to attribute values in the import file. Defaults to `true`.
        identifyBy:
          type: array
          items:
            type: string
          description: 'Array where 1 or more valid secondary keys are supplied in descending priority order. Updates existing contacts when applicable. '
          example:
          - email
          - channels.sms.address
          - custID
    MergeContactsSuccess:
      title: Successful operation
      type: object
      required:
      - jobID
      - message
      properties:
        jobID:
          type: string
        message:
          type: string
    ChannelC:
      title: Channel
      type: object
      required:
      - email
      properties:
        email:
          $ref: '#/components/schemas/EmailC'
    CartC:
      title: Cart
      type: object
      required:
      - cartitems
      properties:
        mcID:
          type: string
        customerID:
          type: string
        linkID:
          type: string
        cartID:
          type: string
        url:
          type: string
        expiration:
          type: string
          format: date
        cartitems:
          type: array
          items:
            $ref: '#/components/schemas/CartitemsC'
        totalAmount:
          type: integer
        tax:
          type: integer
    MergeContactsServerError:
      title: Operation failed due to unexpected server error
      type: object
      required:
      - error
      - errorKey
      - message
      properties:
        error:
          type: boolean
        errorKey:
          type: string
        message:
          type: string
    CartitemsC_2:
      title: Cartitems
      type: object
      required:
      - productID
      - sku
      - category
      - name
      properties:
        productID:
          type: string
          description: Unique product identifier (e.g. 1234abcd).
        description:
          type: string
          description: Product description (e.g. Ultra soft casual t-shirt).
        sku:
          type: string
          description: The Stock Keeping Unit value for a particular item (e.g. RF-WP33286-21).
        category:
          type: string
          description: Item category.
        name:
          type: string
          description: The name of the person or company placing the order.
        qty:
          type: integer
          description: The number of items purchased. Defaults to `1` if not specified.
        itemPrice:
          type: number
          description: Item price.
          format: double
        url:
          type: string
          description: Link to the product page (e.g. https://mydomain.com/myproduct).
        attr:
          type: object
          description: Key/value pairs describing product attributes (e.g. "size":"large", "color":"red"). Attribute values <b>cannot</b> be searched using the Kaleidoscope or within Smarty for personalization.
        images:
          type: array
          items:
            type: string
            description: A comma-separated array of image file locations. Use an empty array `[]` as default if no values exist (e.g. "http://example.com/image1.jpg", "http://example.com/image2.jpg").
        properties:
          type: object
          description: 'Can be used in place of the `attr` key (e.g. "brands":["Marmot", "Quicksilver"], "return_date": "2018-07-01 00:00:00"). Values added <b>can</b> be searched using the Kaleidoscope and within Smarty for personalization.'
    DestinationObject:
      title: Destination
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: 'Defines the destination type. Possible values: AWS (should be used if the file is to be downloaded via the Cordial UI), FTP, SFTP, S3, GCS, AZUREBLOB.'
        aws_access_key_id:
          type: string
          description: Defines the public AWS access key ID. Required if destination is S3 and IAM role is not configured.
        aws_secret_access_key:
          type: string
          description: Defines the secr

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