API Evangelist conversational phrasing for AppConnect V3 Contacts API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for AppConnect V3 Contacts API
  version: 1.0.0
extends: openapi/constant-contact-contacts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/contacts/{contact_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one contact
      effect: read
      questions:
      - What information do I have about a specific contact?
      - Can I include a contact's lists, tags and custom fields in one response?
      instructions:
      - text: Show contact {contact_id}.
        slots:
          contact_id: path.contact_id
      - text: Get contact {contact_id} including {include}.
        slots:
          contact_id: path.contact_id
          include: query.include
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts/{contact_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing contact
      effect: write
      questions:
      - Can I change a contact's name or email by their contact ID?
      - Is it possible to restore a deleted contact?
      instructions:
      - text: Update contact {contact_id} with first name {first_name} and last name {last_name}, source {update_source}.
        slots:
          contact_id: path.contact_id
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          update_source: requestBody.update_source
      - text: Change the job title of contact {contact_id} to {job_title}, source {update_source}.
        slots:
          contact_id: path.contact_id
          job_title: requestBody.job_title
          update_source: requestBody.update_source
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts/{contact_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single contact
      effect: destructive
      questions:
      - What happens to a contact after I delete them — can they come back?
      - Do deleted contacts still count toward my active contacts?
      instructions:
      - text: Delete contact {contact_id}.
        slots:
          contact_id: path.contact_id
      - text: Remove contact {contact_id} from my account.
        slots:
          contact_id: path.contact_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: Search and list contacts
      effect: read
      questions:
      - Which contacts have unsubscribed since last month?
      - Can I find a contact by email address?
      - Is there a way to list everyone with a certain tag or in a segment?
      instructions:
      - text: Find the contact with email {email}.
        slots:
          email: query.email
      - text: List contacts in lists {lists}.
        slots:
          lists: query.lists
      - text: List contacts updated after {updated_after}.
        slots:
          updated_after: query.updated_after
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new contact
      effect: write
      questions:
      - How do I add a single new contact?
      - What's the minimum information needed to create a contact?
      instructions:
      - text: Create a contact with email {email_address} and first name {first_name}.
        slots:
          email_address: requestBody.email_address
          first_name: requestBody.first_name
      - text: Add a new contact {first_name} {last_name} from {company_name}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          company_name: requestBody.company_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts/sign_up_form'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a contact from a sign-up
      effect: write
      questions:
      - Can I add someone if they're new, or update them if they already exist, in one call?
      - Is there an upsert for sign-up forms that also puts the person on a list?
      instructions:
      - text: Sign up {email_address} to lists {list_memberships}, creating or updating them.
        slots:
          email_address: requestBody.email_address
          list_memberships: requestBody.list_memberships
      - text: Upsert {first_name} at {email_address} onto lists {list_memberships}.
        slots:
          first_name: requestBody.first_name
          email_address: requestBody.email_address
          list_memberships: requestBody.list_memberships
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts/contact_id_xrefs'].get
  update:
    x-apievangelist-phrasing:
      intent: Map old V2 contact IDs to V3 contact IDs
      effect: read
      questions:
      - I stored contact IDs from the V2 API — how do I get the new V3 IDs?
      - Can I migrate legacy contact identifiers in bulk?
      instructions:
      - text: Translate V2 contact IDs {sequence_ids} to V3.
        slots:
          sequence_ids: query.sequence_ids
      - text: Get V3 contact IDs for legacy contacts {sequence_ids}.
        slots:
          sequence_ids: query.sequence_ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts/sms_engagement_history/{contact_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact's SMS consent history
      effect: read
      questions:
      - When did a contact give or withdraw SMS consent?
      - Can I see a contact's SMS advertising frequency details?
      instructions:
      - text: Show SMS engagement history for contact {contact_id}.
        slots:
          contact_id: path.contact_id
      - text: Get the SMS consent record of contact {contact_id}.
        slots:
          contact_id: path.contact_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts/counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count contacts by consent state
      effect: read
      questions:
      - How many contacts do I have, and how many are subscribed versus unsubscribed?
      - Can I see how many new subscribers joined in the last 30 days?
      instructions:
      - text: Count my contacts by consent state.
      - text: Get contact consent counts including {include}.
        slots:
          include: query.include
      method: generated
      generated: '2026-10-01'
- target: $.paths['/contacts/resubscribe/{contact_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Send a resubscribe confirmation to a contact
      effect: write
      questions:
      - Can I get an unsubscribed contact back on my lists?
      - Is it possible to send someone a resubscribe confirmation email?
      instructions:
      - text: Send a resubscribe email to contact {contact_id} for lists {list_ids}.
        slots:
          contact_id: path.contact_id
          list_ids: requestBody.list_ids
      - text: Ask contact {contact_id} to confirm resubscribing to {list_ids}.
        slots:
          contact_id: path.contact_id
          list_ids: requestBody.list_ids
      method: generated
      generated: '2026-10-01'