# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Unify Data API
  version: 1.0.0
extends: openapi/unify-data-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: 31
- target: $.paths['/data/v1/events/query-jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List analytics event export jobs
      effect: read
      questions:
      - Which analytics event export jobs have I started recently?
      - Can I see only the event export jobs that are still in progress?
      instructions:
      - text: List my analytics event export jobs.
      - text: Show event export jobs with status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/events/query-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a bulk export of analytics events
      effect: write
      questions:
      - How do I export all my website page, track and identify events from Unify in bulk?
      - Can I export only analytics events newer than a certain timestamp for an incremental sync?
      - Do exported website events include the revealed company and person for each visit?
      instructions:
      - text: Start an export job for all analytics events.
      - text: Start an analytics event export filtered by {filter}.
        slots:
          filter: requestBody.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/events/query-jobs/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of an event export job
      effect: read
      questions:
      - Has my analytics event export job finished yet?
      - When does an event export job expire after I create it?
      instructions:
      - text: Check whether event export job {job_id} is finished.
        slots:
          job_id: path.job_id
      - text: Poll the status of analytics event export {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/events/query-jobs/{job_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a running event export job
      effect: destructive
      questions:
      - Can I stop an analytics event export that is still running?
      - Which event export jobs are allowed to be canceled?
      instructions:
      - text: Cancel analytics event export job {job_id}.
        slots:
          job_id: path.job_id
      - text: Stop the in-progress event export {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/events/query-jobs/{job_id}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: Download results of an event export job
      effect: read
      questions:
      - How do I page through the rows of a finished analytics event export?
      - Can I stream exported website events as newline-delimited JSON?
      - What is the largest page size for downloading event export results?
      instructions:
      - text: Fetch the exported events from job {job_id}.
        slots:
          job_id: path.job_id
      - text: Get page {page} of event export {job_id} with {page_size} rows per page.
        slots:
          page: query.page
          job_id: path.job_id
          page_size: query.page_size
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects'].get
  update:
    x-apievangelist-phrasing:
      intent: List the objects in a workspace
      effect: read
      questions:
      - What standard and custom objects exist in my Unify workspace?
      - Which kinds of records, like company, person or opportunity, can my workspace store?
      instructions:
      - text: List every object defined in my workspace.
      - text: Show me all standard and custom object types.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom object
      effect: write
      questions:
      - How do I add a custom object to store a new kind of record?
      - Can I change a custom object's API name after I create it?
      instructions:
      - text: Create a custom object {api_name} called {display_name} described as {description}, provided by {provider}.
        slots:
          api_name: requestBody.api_name
          display_name: requestBody.display_name
          description: requestBody.description
          provider: requestBody.provider
      - text: Add a new custom object type named {display_name} with API name {api_name}, provider {provider} and description {description}.
        slots:
          display_name: requestBody.display_name
          api_name: requestBody.api_name
          provider: requestBody.provider
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an object definition
      effect: read
      questions:
      - What does the definition of one of my workspace objects look like?
      - Can I look up a single object type by its API name?
      instructions:
      - text: Show the definition of object {object_name}.
        slots:
          object_name: path.object_name
      - text: Get the {object_name} object's display name and description.
        slots:
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an object
      effect: destructive
      questions:
      - How do I remove a custom object type I no longer need?
      - Can an entire object be deleted by its API name?
      instructions:
      - text: Delete the object {object_name}.
        slots:
          object_name: path.object_name
      - text: Remove the custom object type {object_name} from my workspace.
        slots:
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe an object
      effect: write
      questions:
      - Can I rename an object's display name without changing its API name?
      - How do I update the description shown for an object in the UI?
      instructions:
      - text: Rename object {object_name} to {display_name} with description {description}.
        slots:
          object_name: path.object_name
          display_name: requestBody.display_name
          description: requestBody.description
      - text: Update the {object_name} object's description to {description} and display name to {display_name}.
        slots:
          object_name: path.object_name
          description: requestBody.description
          display_name: requestBody.display_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List the attributes on an object
      effect: read
      questions:
      - Which fields are defined on my company object?
      - What attributes can records of a given object hold values for?
      instructions:
      - text: List all attributes on the {object_name} object.
        slots:
          object_name: path.object_name
      - text: Show me the fields defined for {object_name}.
        slots:
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an attribute to an object
      effect: write
      questions:
      - How do I add a new field to an object, like a select or a reference to another object?
      - Can I change an attribute's value type after creating it?
      - Can a new attribute be marked unique so I can upsert records by it?
      instructions:
      - text: Add a new attribute to the {object_name} object.
        slots:
          object_name: path.object_name
      - text: Create a reference field on {object_name} that links to another object's records.
        slots:
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes/{attribute_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one attribute on an object
      effect: read
      questions:
      - How can I see the type and settings of a single field on an object?
      - Is a particular attribute on my object unique or required?
      instructions:
      - text: Show attribute {attribute_name} on object {object_name}.
        slots:
          attribute_name: path.attribute_name
          object_name: path.object_name
      - text: Get the definition of the {attribute_name} field of {object_name}.
        slots:
          attribute_name: path.attribute_name
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes/{attribute_name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an attribute from an object
      effect: destructive
      questions:
      - How do I remove a field I no longer use from an object?
      - Can I delete an attribute by its API name?
      instructions:
      - text: Delete attribute {attribute_name} from object {object_name}.
        slots:
          attribute_name: path.attribute_name
          object_name: path.object_name
      - text: Remove the {attribute_name} field from {object_name}.
        slots:
          attribute_name: path.attribute_name
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes/{attribute_name}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an attribute's display name or description
      effect: write
      questions:
      - Can I rename a field's display name on an object after it exists?
      - Is it possible to downgrade a reference attribute from many to one?
      instructions:
      - text: Update the display name and description of attribute {attribute_name} on {object_name}.
        slots:
          attribute_name: path.attribute_name
          object_name: path.object_name
      - text: Edit the {attribute_name} field settings on object {object_name}.
        slots:
          attribute_name: path.attribute_name
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes/{attribute_name}/options'].get
  update:
    x-apievangelist-phrasing:
      intent: List the options of a select attribute
      effect: read
      questions:
      - What values can I pick from in a select or multi-select field?
      - Which predefined options exist on a dropdown attribute?
      instructions:
      - text: List the options of select field {attribute_name} on {object_name}.
        slots:
          attribute_name: path.attribute_name
          object_name: path.object_name
      - text: Show the allowed values for the {attribute_name} dropdown on object {object_name}.
        slots:
          attribute_name: path.attribute_name
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes/{attribute_name}/options'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an option to a select attribute
      effect: write
      questions:
      - How do I add a new choice to a select or multi-select field?
      - Can I give a dropdown option a separate API name and display name?
      instructions:
      - text: Add option {display_name} with API name {api_name} to the {attribute_name} field on {object_name}.
        slots:
          display_name: requestBody.display_name
          api_name: requestBody.api_name
          attribute_name: path.attribute_name
          object_name: path.object_name
      - text: Create a new choice {api_name} labeled {display_name} on select attribute {attribute_name} of {object_name}.
        slots:
          api_name: requestBody.api_name
          display_name: requestBody.display_name
          attribute_name: path.attribute_name
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes/{attribute_name}/options/{option_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one option of a select attribute
      effect: read
      questions:
      - How can I look up a single dropdown option by its API name?
      - What is the display label of a specific select option?
      instructions:
      - text: Show option {option_name} of field {attribute_name} on {object_name}.
        slots:
          option_name: path.option_name
          attribute_name: path.attribute_name
          object_name: path.object_name
      - text: Get the {option_name} choice from select attribute {attribute_name} of object {object_name}.
        slots:
          option_name: path.option_name
          attribute_name: path.attribute_name
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes/{attribute_name}/options/{option_name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an option from a select attribute
      effect: destructive
      questions:
      - How do I remove a choice from a select or multi-select field?
      - Can I delete one dropdown value without deleting the whole attribute?
      instructions:
      - text: Delete option {option_name} from field {attribute_name} on {object_name}.
        slots:
          option_name: path.option_name
          attribute_name: path.attribute_name
          object_name: path.object_name
      - text: Remove the {option_name} choice from the {attribute_name} dropdown of {object_name}.
        slots:
          option_name: path.option_name
          attribute_name: path.attribute_name
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/attributes/{attribute_name}/options/{option_name}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename an option of a select attribute
      effect: write
      questions:
      - Can I relabel a dropdown option without changing its API name?
      - How do I change the display name of a select field choice?
      instructions:
      - text: Rename option {option_name} on field {attribute_name} of {object_name} to {display_name}.
        slots:
          option_name: path.option_name
          attribute_name: path.attribute_name
          object_name: path.object_name
          display_name: requestBody.display_name
      - text: Change the label of the {option_name} choice in {object_name}.{attribute_name} to {display_name}.
        slots:
          option_name: path.option_name
          object_name: path.object_name
          attribute_name: path.attribute_name
          display_name: requestBody.display_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/query-jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List record export jobs for an object
      effect: read
      questions:
      - Which record export jobs have I run against my company object?
      - Can I filter an object's record export jobs by status?
      instructions:
      - text: List record export jobs for object {object_name}.
        slots:
          object_name: path.object_name
      - text: Show {object_name} record export jobs with status {status}.
        slots:
          object_name: path.object_name
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/query-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a bulk export of an object's records
      effect: write
      questions:
      - How do I bulk export all person records with only the fields I choose?
      - Can a record export filter on attribute values and sort by last updated for incremental syncs?
      - Can I expand a reference field into nested records when exporting an object?
      instructions:
      - text: Start an export of {object_name} records using query {query}.
        slots:
          object_name: path.object_name
          query: requestBody.query
      - text: Kick off a bulk record export job on {object_name} selecting and filtering with {query}.
        slots:
          object_name: path.object_name
          query: requestBody.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/query-jobs/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a record export job
      effect: read
      questions:
      - Is my company record export job done yet?
      - How long do object record export jobs stay available?
      instructions:
      - text: Check the status of {object_name} record export job {job_id}.
        slots:
          object_name: path.object_name
          job_id: path.job_id
      - text: Poll record export {job_id} on object {object_name} until it finishes.
        slots:
          job_id: path.job_id
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/query-jobs/{job_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a running record export job
      effect: destructive
      questions:
      - Can I stop a record export on an object that is taking too long?
      - What happens if I try to cancel a record export that already finished?
      instructions:
      - text: Cancel record export job {job_id} on {object_name}.
        slots:
          job_id: path.job_id
          object_name: path.object_name
      - text: Stop the in-progress {object_name} record export {job_id}.
        slots:
          object_name: path.object_name
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/query-jobs/{job_id}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: Download results of a record export job
      effect: read
      questions:
      - How do I page through the records a finished object export returned?
      - Why are some attributes missing from rows in my record export results?
      - Can I download exported records as NDJSON with up to 10,000 rows per page?
      instructions:
      - text: Fetch the exported {object_name} records from job {job_id}.
        slots:
          object_name: path.object_name
          job_id: path.job_id
      - text: Get page {page} of record export {job_id} on {object_name} with {page_size} rows.
        slots:
          page: query.page
          job_id: path.job_id
          object_name: path.object_name
          page_size: query.page_size
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/records'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a record of an object
      effect: write
      questions:
      - How do I add a brand-new company or person record?
      - What happens if I create a record whose unique field duplicates an existing one?
      instructions:
      - text: Create a new {object_name} record with values {data}.
        slots:
          object_name: path.object_name
          data: requestBody.data
      - text: Insert a {object_name} record with {data} using validation mode {validation_mode}.
        slots:
          object_name: path.object_name
          data: requestBody.data
          validation_mode: query.validation_mode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/records/find-unique'].post
  update:
    x-apievangelist-phrasing:
      intent: Find one record by a unique attribute
      effect: read
      questions:
      - How can I look up a person record by their email instead of its ID?
      - What comes back when no record matches the unique value I search for?
      instructions:
      - text: Find the {object_name} record matching {match}.
        slots:
          object_name: path.object_name
          match: requestBody.match
      - text: Look up the single {object_name} whose unique field values are {match}.
        slots:
          object_name: path.object_name
          match: requestBody.match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/records/upsert'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a record by a unique match
      effect: write
      questions:
      - How do I sync a company into Unify without knowing whether it already exists?
      - Can I only fill in fields that are empty when the record already exists?
      - Is there a way to set different values on create versus on update in one call?
      instructions:
      - text: Upsert a {object_name} record matched on {match}.
        slots:
          object_name: path.object_name
          match: requestBody.match
      - text: Upsert {object_name} matching {match}, setting {create_or_update} whether it is new or existing.
        slots:
          object_name: path.object_name
          match: requestBody.match
          create_or_update: requestBody.create_or_update
      - text: Upsert {object_name} by {match} and only fill {update_if_empty} where those fields are blank.
        slots:
          object_name: path.object_name
          match: requestBody.match
          update_if_empty: requestBody.update_if_empty
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/records/{record_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a record by its ID
      effect: read
      questions:
      - How do I fetch a single record when I already have its ID?
      - Can I read all attribute values of one specific record?
      instructions:
      - text: Get {object_name} record {record_id}.
        slots:
          object_name: path.object_name
          record_id: path.record_id
      - text: Show me the details of record {record_id} in {object_name}.
        slots:
          record_id: path.record_id
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/records/{record_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a record by its ID
      effect: destructive
      questions:
      - How do I permanently remove one company or person record?
      - Can I delete a record if I know its ID?
      instructions:
      - text: Delete {object_name} record {record_id}.
        slots:
          object_name: path.object_name
          record_id: path.record_id
      - text: Remove record {record_id} from the {object_name} object.
        slots:
          record_id: path.record_id
          object_name: path.object_name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data/v1/objects/{object_name}/records/{record_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update fields on a record by its ID
      effect: write
      questions:
      - How do I change a few fields on an existing record without touching the others?
      - Does updating a record by ID clear the attributes I leave out?
      instructions:
      - text: Update {object_name} record {record_id} with {data}.
        slots:
          object_name: path.object_name
          record_id: path.record_id
          data: requestBody.data
      - text: Set {data} on record {record_id} of {object_name} using validation mode {validation_mode}.
        slots:
          data: requestBody.data
          record_id: path.record_id
          object_name: path.object_name
          validation_mode: query.validation_mode
      method: generated
      generated: '2026-10-01'