# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Salesforce Marketing Cloud REST Contacts API
  version: 1.0.0
extends: openapi/salesforce-marketing-cloud-contacts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/contacts/v1/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contact
      effect: write
      questions:
      - How do I add a new subscriber to Marketing Cloud's contact model?
      - Can I set a new contact's email address at the same time I create it?
      instructions:
      - text: Create a new contact with key {contactKey}.
        slots:
          contactKey: requestBody.contactKey
      - text: Create contact {contactKey} with the attribute values {attributes}.
        slots:
          contactKey: requestBody.contactKey
          attributes: requestBody.attributeSets
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/v1/contacts/actions/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search contacts by criteria
      effect: read
      questions:
      - How do I find a contact when I only know their email address?
      - Can I look up contacts by attribute values and choose which attributes come back?
      instructions:
      - text: Search my contacts using the conditions {conditions}.
        slots:
          conditions: requestBody.conditionSet
      - text: Find contacts matching {conditions} and return {attributes}.
        slots:
          conditions: requestBody.conditionSet
          attributes: requestBody.returnAttributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/v1/contacts/{contactKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a contact by contact key
      effect: read
      questions:
      - What attribute values are stored for a specific contact key?
      - Which attribute sets come back when I look up one contact by its key?
      instructions:
      - text: Get contact {contactKey}.
        slots:
          contactKey: path.contactKey
      - text: Show all stored attributes for the contact with key {contactKey}.
        slots:
          contactKey: path.contactKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/v1/contacts/{contactKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact and its data
      effect: destructive
      questions:
      - How do I remove a person and their data from Marketing Cloud entirely?
      - Does deleting a contact happen right away or run in the background?
      instructions:
      - text: Delete contact {contactKey}.
        slots:
          contactKey: path.contactKey
      - text: Start removing all data for the contact with key {contactKey}.
        slots:
          contactKey: path.contactKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/v1/contacts/{contactKey}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a contact's attributes
      effect: write
      questions:
      - How do I change an existing contact's email address without touching their other data?
      - Can I update just one attribute set on a contact who already exists?
      instructions:
      - text: Update existing contact {contactKey} with the attribute values {attributes}.
        slots:
          contactKey: path.contactKey
          attributes: requestBody.attributeSets
      - text: Change the attributes {attributes} on contact {contactKey} and leave the rest alone.
        slots:
          attributes: requestBody.attributeSets
          contactKey: path.contactKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/v1/attributeSets'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact attribute sets
      effect: read
      questions:
      - What attribute sets define the structure of contact data in my account?
      - Which custom attribute sets exist alongside Email Addresses and MobileConnect Demographics?
      instructions:
      - text: List all attribute sets defined in my account.
      - text: Show me the contact data model's attribute sets.
      method: generated
      generated: '2026-09-26'