# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Klaviyo Profiles API
  version: 1.0.0
extends: openapi/klaviyo-profiles-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: 36
- target: $.paths['/api/profiles'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter profiles in the account
      effect: read
      questions:
      - How do I pull every contact profile out of my Klaviyo account?
      - Can I sort profiles by when they were created or last updated?
      - Is there a way to find a profile by email address without knowing its ID?
      instructions:
      - text: List all profiles in my account, newest first.
      - text: Find profiles matching the filter {filter}.
        slots:
          filter: query.filter
      - text: List profiles sorted by {sort}, {page_size} per page.
        slots:
          sort: query.sort
          page_size: query.page[size]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new profile
      effect: write
      questions:
      - What's the way to add a brand-new contact profile that doesn't exist yet?
      - Is there a payload size limit when creating a single profile?
      instructions:
      - text: 'Create a new profile with these details: {profile}.'
        slots:
          profile: requestBody.data
      - text: Add a brand-new contact profile for {profile} and return its subscriptions.
        slots:
          profile: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one profile by ID
      effect: read
      questions:
      - How can I look up everything stored on a single profile by its ID?
      - Can I see a profile's predictive analytics along with its attributes?
      instructions:
      - text: Get profile {profile_id}.
        slots:
          profile_id: path.id
      - text: Show profile {profile_id} including predictive analytics and subscriptions.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing profile's attributes
      effect: write
      questions:
      - How do I change the attributes on a profile I already have the ID for?
      - Does sending null for a field on a profile update clear it out?
      instructions:
      - text: Update profile {profile_id} with {changes}.
        slots:
          profile_id: path.id
          changes: requestBody.data
      - text: Clear the fields listed in {changes} on profile {profile_id} by setting them to null.
        slots:
          profile_id: path.id
          changes: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-bulk-import-jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List bulk profile import jobs
      effect: read
      questions:
      - Where can I see all the bulk profile import jobs I've submitted?
      - Can I filter my bulk import jobs by status?
      instructions:
      - text: List all my bulk profile import jobs.
      - text: Show bulk profile import jobs matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-bulk-import-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk import up to 10,000 profiles
      effect: write
      questions:
      - How many profiles can I import in a single bulk import request?
      - What's the fastest way to create or update thousands of profiles at once?
      instructions:
      - text: 'Start a bulk import job for these profiles: {profiles}.'
        slots:
          profiles: requestBody.data
      - text: Bulk import {profiles} and add them to a list.
        slots:
          profiles: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-bulk-import-jobs/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a bulk profile import job
      effect: read
      questions:
      - How do I check whether my bulk profile import job has finished?
      - Can I see the progress of one specific import job?
      instructions:
      - text: Get the status of bulk profile import job {job_id}.
        slots:
          job_id: path.job_id
      - text: Check how import job {job_id} is progressing.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-suppression-bulk-create-jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List bulk profile suppression jobs
      effect: read
      questions:
      - Which bulk email suppression jobs have I run and what state are they in?
      - Can I filter suppression jobs by list or segment?
      instructions:
      - text: List the status of all my bulk suppression jobs.
      - text: Show bulk suppression jobs matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-suppression-bulk-create-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Suppress profiles from email marketing
      effect: write
      questions:
      - How do I stop email marketing to a batch of email addresses regardless of consent?
      - Can I suppress every current member of a list or segment in one go?
      instructions:
      - text: 'Suppress these email addresses from marketing email: {emails}.'
        slots:
          emails: requestBody.data
      - text: Suppress all current members of {list_or_segment} from email marketing.
        slots:
          list_or_segment: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-suppression-bulk-create-jobs/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a bulk suppression job
      effect: read
      questions:
      - Did my bulk suppression request finish processing?
      - What's the current state of a single suppression job?
      instructions:
      - text: Get bulk suppression job {job_id}.
        slots:
          job_id: path.job_id
      - text: Check whether suppression job {job_id} has completed.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-suppression-bulk-delete-jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List bulk profile unsuppression jobs
      effect: read
      questions:
      - Where do I see all the jobs I ran to lift email suppressions?
      - Can I sort unsuppression jobs by creation date?
      instructions:
      - text: List all my bulk unsuppression jobs.
      - text: Show unsuppression jobs matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-suppression-bulk-delete-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Lift manual email suppressions in bulk
      effect: write
      questions:
      - How can I remove manual suppressions so people can get marketing email again?
      - Will unsuppressing also restore profiles that unsubscribed or had invalid emails?
      instructions:
      - text: 'Unsuppress these email addresses: {emails}.'
        slots:
          emails: requestBody.data
      - text: Remove user suppressions from every member of {list_or_segment}.
        slots:
          list_or_segment: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-suppression-bulk-delete-jobs/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a bulk unsuppression job
      effect: read
      questions:
      - Has my request to lift suppressions finished?
      - What does a single unsuppression job report about its progress?
      instructions:
      - text: Get bulk unsuppression job {job_id}.
        slots:
          job_id: path.job_id
      - text: Check the status of unsuppress job {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/push-tokens'].get
  update:
    x-apievangelist-phrasing:
      intent: List push tokens in the account
      effect: read
      questions:
      - How do I see all the mobile push tokens registered for my company?
      - Can I filter push tokens by platform or profile?
      instructions:
      - text: List every push token in my account.
      - text: Show push tokens matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/push-tokens'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a push token
      effect: write
      questions:
      - Can I migrate existing mobile push tokens from another system into Klaviyo?
      - What's the server-side way to register a device push token for a profile?
      instructions:
      - text: Register push token {push_token} for its profile.
        slots:
          push_token: requestBody.data
      - text: Create or update the push token record {push_token}.
        slots:
          push_token: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/push-tokens/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one push token by ID
      effect: read
      questions:
      - How do I look up a single push token by its ID?
      - What details are stored on a specific push token?
      instructions:
      - text: Get push token {token_id}.
        slots:
          token_id: path.id
      - text: Show the details of push token {token_id}.
        slots:
          token_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/push-tokens/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a push token
      effect: destructive
      questions:
      - How do I remove a device's push token so it stops getting notifications?
      - Can I delete a stale push token by its ID?
      instructions:
      - text: Delete push token {token_id}.
        slots:
          token_id: path.id
      - text: Remove the stale push token {token_id} from my account.
        slots:
          token_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-import'].post
  update:
    x-apievangelist-phrasing:
      intent: Upsert a profile by its attributes
      effect: write
      questions:
      - Is there a single call that creates a profile if it's new or updates it if it exists?
      - How can I tell whether an upsert created a new profile or updated an old one?
      instructions:
      - text: Create or update the profile for {profile}.
        slots:
          profile: requestBody.data
      - text: Upsert a profile using the email and properties in {profile}.
        slots:
          profile: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge a duplicate profile into another
      effect: destructive
      questions:
      - How do I combine two duplicate profiles for the same person?
      - Which profile survives when I merge a source profile into a destination?
      instructions:
      - text: Merge the duplicate profiles described in {merge_request} into the destination profile.
        slots:
          merge_request: requestBody.data
      - text: 'Queue a merge of source and destination profiles: {merge_request}.'
        slots:
          merge_request: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-subscription-bulk-create-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe profiles to marketing channels
      effect: write
      questions:
      - How do I opt people in to email, SMS, WhatsApp or push marketing in bulk?
      - Will subscribers get a confirmation message if the list uses double opt-in?
      instructions:
      - text: 'Subscribe these profiles to marketing: {subscriptions}.'
        slots:
          subscriptions: requestBody.data
      - text: Opt the contacts in {subscriptions} in to SMS and email on a list.
        slots:
          subscriptions: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-subscription-bulk-delete-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Unsubscribe profiles from marketing channels
      effect: destructive
      questions:
      - How can I unsubscribe a batch of people from email or SMS marketing?
      - What happens to profiles that aren't on the list I pass when unsubscribing?
      instructions:
      - text: 'Unsubscribe these profiles from marketing: {unsubscriptions}.'
        slots:
          unsubscriptions: requestBody.data
      - text: Opt out the contacts in {unsubscriptions} from SMS and email.
        slots:
          unsubscriptions: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}/push-tokens'].get
  update:
    x-apievangelist-phrasing:
      intent: List a profile's push tokens
      effect: read
      questions:
      - Which devices does a given profile have push tokens registered on?
      - Can I get the full push token records for one profile?
      instructions:
      - text: List the push tokens belonging to profile {profile_id}.
        slots:
          profile_id: path.id
      - text: Show full push token details for profile {profile_id}.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}/relationships/push-tokens'].get
  update:
    x-apievangelist-phrasing:
      intent: Get push token IDs for a profile
      effect: read
      questions:
      - Can I get just the IDs of a profile's push tokens without the full records?
      - What's the lightweight way to see which token IDs are linked to a profile?
      instructions:
      - text: Get only the push token IDs linked to profile {profile_id}.
        slots:
          profile_id: path.id
      - text: Return the token ID relationships for profile {profile_id}.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List the lists a profile belongs to
      effect: read
      questions:
      - Which email lists is a particular person a member of?
      - Can I see full list details for every list a profile has joined?
      instructions:
      - text: Show the lists profile {profile_id} is a member of.
        slots:
          profile_id: path.id
      - text: Get full list records for profile {profile_id}'s memberships.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}/relationships/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: Get list IDs a profile belongs to
      effect: read
      questions:
      - Can I fetch only the list IDs a profile is on, not the whole list objects?
      - What's the quick way to check list membership IDs for a contact?
      instructions:
      - text: Get just the list IDs for profile {profile_id}.
        slots:
          profile_id: path.id
      - text: Return list membership relationships for profile {profile_id}.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the segments a profile is in
      effect: read
      questions:
      - Which segments does this customer currently fall into?
      - Can I see the full segment definitions a profile qualifies for?
      instructions:
      - text: Show the segments profile {profile_id} belongs to.
        slots:
          profile_id: path.id
      - text: Get full segment records for profile {profile_id}'s memberships.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}/relationships/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: Get segment IDs a profile is in
      effect: read
      questions:
      - Can I retrieve only the segment IDs for a profile?
      - Is there a lightweight check for which segment IDs a contact matches?
      instructions:
      - text: Get just the segment IDs for profile {profile_id}.
        slots:
          profile_id: path.id
      - text: Return segment membership relationships for profile {profile_id}.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}/conversation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a profile's conversation
      effect: read
      questions:
      - How do I pull up the messaging conversation tied to a customer's profile?
      - Can I read the full conversation record for one profile?
      instructions:
      - text: Get the conversation for profile {profile_id}.
        slots:
          profile_id: path.id
      - text: Show the full conversation record attached to profile {profile_id}.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profiles/{id}/relationships/conversation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a profile's conversation ID
      effect: read
      questions:
      - Can I get only the conversation ID linked to a profile?
      - What's the conversation relationship ID for a given contact?
      instructions:
      - text: Get just the conversation ID for profile {profile_id}.
        slots:
          profile_id: path.id
      - text: Return the conversation relationship of profile {profile_id}.
        slots:
          profile_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-bulk-import-jobs/{id}/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the list a bulk import job targets
      effect: read
      questions:
      - Which list were the profiles in my bulk import job added to?
      - Can I see the full list record attached to an import job?
      instructions:
      - text: Get the list that bulk import job {job_id} adds profiles to.
        slots:
          job_id: path.id
      - text: Show list details for import job {job_id}.
        slots:
          job_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-bulk-import-jobs/{id}/relationships/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: Get list IDs for a bulk import job
      effect: read
      questions:
      - Can I get only the list ID a bulk import job is tied to?
      - What list relationship does an import job carry?
      instructions:
      - text: Get just the list IDs for bulk import job {job_id}.
        slots:
          job_id: path.id
      - text: Return the list relationship of import job {job_id}.
        slots:
          job_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-bulk-import-jobs/{id}/profiles'].get
  update:
    x-apievangelist-phrasing:
      intent: List profiles from a bulk import job
      effect: read
      questions:
      - Which profiles were created or updated by a particular bulk import?
      - Can I page through the full profile records an import job touched?
      instructions:
      - text: List the profiles imported by bulk import job {job_id}.
        slots:
          job_id: path.id
      - text: Show {page_size} imported profiles at a time from job {job_id}.
        slots:
          job_id: path.id
          page_size: query.page[size]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-bulk-import-jobs/{id}/relationships/profiles'].get
  update:
    x-apievangelist-phrasing:
      intent: Get profile IDs from a bulk import job
      effect: read
      questions:
      - Can I get just the profile IDs that a bulk import job processed?
      - What's the lightweight way to see which profile IDs an import touched?
      instructions:
      - text: Get only the profile IDs from bulk import job {job_id}.
        slots:
          job_id: path.id
      - text: Return profile relationships for import job {job_id}.
        slots:
          job_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/profile-bulk-import-jobs/{id}/import-errors'].get
  update:
    x-apievangelist-phrasing:
      intent: Get errors from a bulk import job
      effect: read
      questions:
      - Why did some profiles fail to import in my bulk job?
      - Where do I find the import errors for a bulk profile upload?
      instructions:
      - text: Show the import errors for bulk import job {job_id}.
        slots:
          job_id: path.id
      - text: List which rows failed in import job {job_id}.
        slots:
          job_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/push-tokens/{id}/profile'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the profile that owns a push token
      effect: read
      questions:
      - Who is the customer behind a given push token?
      - Can I get the full profile record for a device token?
      instructions:
      - text: Get the profile that owns push token {token_id}.
        slots:
          token_id: path.id
      - text: Show the full customer profile for device token {token_id}.
        slots:
          token_id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/push-tokens/{id}/relationships/profile'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the profile ID for a push token
      effect: read
      questions:
      - Can I fetch only the profile ID linked to a push token?
      - What profile relationship does a device token point to?
      instructions:
      - text: Get just the profile ID for push token {token_id}.
        slots:
          token_id: path.id
      - text: Return the profile relationship of token {token_id}.
        slots:
          token_id: path.id
      method: generated
      generated: '2026-09-26'