# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for act.web.api Contacts API
  version: 1.0.0
extends: openapi/act-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: 33
- target: $.paths['/api/companies/{companyId}/associated-contacts/{contactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link one contact to a company
      effect: write
      questions:
      - Can I attach a single existing contact to a company record in Act!?
      - What's the call to add just one person to a company's associated contacts?
      instructions:
      - text: Link contact {contactId} to company {companyId}.
        slots:
          contactId: path.contactId
          companyId: path.companyId
      - text: Add the single contact {contactId} to the contacts of company {companyId}.
        slots:
          contactId: path.contactId
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}/associated-contacts/{contactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink one contact from a company
      effect: destructive
      questions:
      - Can I remove one person from a company without deleting the contact itself?
      - What happens to a contact when I detach it from a single company?
      instructions:
      - text: Unlink contact {contactId} from company {companyId}.
        slots:
          contactId: path.contactId
          companyId: path.companyId
      - text: Remove just contact {contactId} from company {companyId}'s associated contacts.
        slots:
          contactId: path.contactId
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}/associated-contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List the contacts linked to a company
      effect: read
      questions:
      - Who are all the people associated with a particular company?
      - Can I filter a company's contacts with an OData query?
      - Is it possible to choose the phone number format when listing a company's contacts?
      instructions:
      - text: List the contacts associated with company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show everyone linked to company {companyId} with phone numbers in {phoneFormat} format.
        slots:
          companyId: path.companyId
          phoneFormat: query.phoneFormat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}/associated-contacts'].put
  update:
    x-apievangelist-phrasing:
      intent: Link several contacts to a company at once
      effect: write
      questions:
      - Can I attach a whole batch of contacts to a company in one request?
      - What's the bulk way to add many people to a company record?
      instructions:
      - text: Link contacts {contacts} to company {companyId}.
        slots:
          contacts: requestBody.contacts
          companyId: path.companyId
      - text: Bulk-add the list {contacts} as associated contacts of company {companyId}.
        slots:
          contacts: requestBody.contacts
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}/associated-contacts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink several contacts from a company
      effect: destructive
      questions:
      - Can I detach a list of contacts from a company in a single call?
      - Is there a bulk way to clear several people off a company record?
      instructions:
      - text: Unlink contacts {contacts} from company {companyId}.
        slots:
          contacts: requestBody.contacts
          companyId: path.companyId
      - text: Bulk-remove the list {contacts} from company {companyId}'s associated contacts.
        slots:
          contacts: requestBody.contacts
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/groups/{groupId}/associated-contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List the contacts in a group
      effect: read
      questions:
      - Who are the members of a specific Act! group?
      - Can I run an OData filter over the contacts inside one group?
      instructions:
      - text: List the contacts in group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show group {groupId}'s members with phone numbers formatted as {phoneFormat}.
        slots:
          groupId: path.groupId
          phoneFormat: query.phoneFormat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/groups/{groupId}/associated-contacts'].put
  update:
    x-apievangelist-phrasing:
      intent: Add several contacts to a group
      effect: write
      questions:
      - Can I put a batch of contacts into a group in one request?
      - What's the bulk call for assigning many people to a group?
      instructions:
      - text: Add contacts {contacts} to group {groupId}.
        slots:
          contacts: requestBody.contacts
          groupId: path.groupId
      - text: Bulk-assign the list {contacts} as members of group {groupId}.
        slots:
          contacts: requestBody.contacts
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/groups/{groupId}/associated-contacts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove several contacts from a group
      effect: destructive
      questions:
      - Can I take a list of contacts out of a group in one call?
      - Is there a bulk way to drop members from a group without deleting them?
      instructions:
      - text: Remove contacts {contacts} from group {groupId}.
        slots:
          contacts: requestBody.contacts
          groupId: path.groupId
      - text: Bulk-remove the members {contacts} from group {groupId}.
        slots:
          contacts: requestBody.contacts
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/groups/{groupId}/associated-contacts/{contactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add one contact to a group
      effect: write
      questions:
      - Can I add a single person to an existing group?
      - What's the call to make one contact a member of a group?
      instructions:
      - text: Add contact {contactId} to group {groupId}.
        slots:
          contactId: path.contactId
          groupId: path.groupId
      - text: Make contact {contactId} a member of group {groupId}.
        slots:
          contactId: path.contactId
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/groups/{groupId}/associated-contacts/{contactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one contact from a group
      effect: destructive
      questions:
      - Can I take a single person out of a group but keep their contact record?
      - What removes just one member from a group?
      instructions:
      - text: Remove contact {contactId} from group {groupId}.
        slots:
          contactId: path.contactId
          groupId: path.groupId
      - text: Drop the single member {contactId} from group {groupId}.
        slots:
          contactId: path.contactId
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List the contacts on an opportunity
      effect: read
      questions:
      - Which people are attached to a particular sales opportunity?
      - Can I filter an opportunity's contacts with an OData query?
      instructions:
      - text: List the contacts on opportunity {opportunityId}.
        slots:
          opportunityId: path.opportunityId
      - text: Show who is linked to opportunity {opportunityId}, with phones in {phoneFormat} format.
        slots:
          opportunityId: path.opportunityId
          phoneFormat: query.phoneFormat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-contacts'].put
  update:
    x-apievangelist-phrasing:
      intent: Link several contacts to an opportunity
      effect: write
      questions:
      - Can I attach a batch of contacts to a deal in one request?
      - What's the bulk call to add many people to an opportunity?
      instructions:
      - text: Link contacts {contacts} to opportunity {opportunityId}.
        slots:
          contacts: requestBody.contacts
          opportunityId: path.opportunityId
      - text: Bulk-attach the list {contacts} to deal {opportunityId}.
        slots:
          contacts: requestBody.contacts
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-contacts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink several contacts from an opportunity
      effect: destructive
      questions:
      - Can I detach a list of contacts from a deal in one call?
      - Is there a bulk way to clear people off an opportunity?
      instructions:
      - text: Unlink contacts {contacts} from opportunity {opportunityId}.
        slots:
          contacts: requestBody.contacts
          opportunityId: path.opportunityId
      - text: Bulk-remove the list {contacts} from deal {opportunityId}.
        slots:
          contacts: requestBody.contacts
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-contacts/{contactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link one contact to an opportunity
      effect: write
      questions:
      - Can I add a single person to an existing sales opportunity?
      - What's the call to attach one contact to a deal?
      instructions:
      - text: Link contact {contactId} to opportunity {opportunityId}.
        slots:
          contactId: path.contactId
          opportunityId: path.opportunityId
      - text: Attach the single contact {contactId} to deal {opportunityId}.
        slots:
          contactId: path.contactId
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-contacts/{contactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink one contact from an opportunity
      effect: destructive
      questions:
      - Can I take one person off a deal without deleting the contact?
      - What detaches a single contact from an opportunity?
      instructions:
      - text: Unlink contact {contactId} from opportunity {opportunityId}.
        slots:
          contactId: path.contactId
          opportunityId: path.opportunityId
      - text: Remove just contact {contactId} from deal {opportunityId}.
        slots:
          contactId: path.contactId
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact's details
      effect: read
      questions:
      - How do I pull up the full record for one contact by its id?
      - Can I choose how phone numbers are formatted when fetching a contact?
      instructions:
      - text: Get contact {contactId}.
        slots:
          contactId: path.contactId
      - text: Show me the details of contact {contactId} with phones in {phoneFormat} format.
        slots:
          contactId: path.contactId
          phoneFormat: query.phoneFormat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a contact's record
      effect: write
      questions:
      - How do I overwrite an existing contact with a full set of new values?
      - Can I rewrite a contact's whole record, job title and addresses included, in one call?
      instructions:
      - text: Replace contact {contactId} with first name {firstName}, last name {lastName} and email {emailAddress}.
        slots:
          contactId: path.contactId
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          emailAddress: requestBody.emailAddress
      - text: Do a full update of contact {contactId}, setting job title {jobTitle} and company {company}.
        slots:
          contactId: path.contactId
          jobTitle: requestBody.jobTitle
          company: requestBody.company
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact
      effect: destructive
      questions:
      - Can I permanently remove a contact from the database?
      - What happens when I delete a contact record by id?
      instructions:
      - text: Delete contact {contactId}.
        slots:
          contactId: path.contactId
      - text: Permanently remove contact {contactId} from Act!.
        slots:
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change selected fields on a contact
      effect: write
      questions:
      - Can I change only a contact's mobile number without resending everything else?
      - Is there a partial update for a contact that leaves other fields untouched?
      instructions:
      - text: Change just the mobile phone of contact {contactId} to {mobilePhone}.
        slots:
          contactId: path.contactId
          mobilePhone: requestBody.mobilePhone
      - text: Patch contact {contactId} so their email is {emailAddress}, leaving everything else as is.
        slots:
          contactId: path.contactId
          emailAddress: requestBody.emailAddress
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/{entityName}/{id}/associated-contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List contacts linked to a custom entity record
      effect: read
      questions:
      - Which contacts are attached to a record in one of my custom tables?
      - Can I list the people linked to a custom entity item with an OData filter?
      instructions:
      - text: List the contacts linked to record {id} in custom entity {entityName}.
        slots:
          id: path.id
          entityName: path.entityName
      - text: Show who is associated with {entityName} record {id}.
        slots:
          entityName: path.entityName
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/by-ids'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch several contacts by their ids
      effect: read
      questions:
      - Can I fetch a handful of specific contacts in one request by id?
      - What's the way to look up multiple contacts when I already have their ids?
      instructions:
      - text: Fetch the contacts with ids {ids}.
        slots:
          ids: query.ids
      - text: Look up contacts {ids} and format their phone numbers as {phoneFormat}.
        slots:
          ids: query.ids
          phoneFormat: query.phoneFormat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/access'].get
  update:
    x-apievangelist-phrasing:
      intent: See who can access a contact
      effect: read
      questions:
      - Who has access to a particular contact record?
      - Is a contact public, private or limited to certain users?
      instructions:
      - text: Show the access level of contact {contactId}.
        slots:
          contactId: path.contactId
      - text: List who is allowed to see contact {contactId}.
        slots:
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/access'].put
  update:
    x-apievangelist-phrasing:
      intent: Set who can access a contact
      effect: write
      questions:
      - Can I restrict a contact so only certain users can see it?
      - How do I change the access level on a contact record?
      instructions:
      - text: Set contact {contactId} to access level {type}.
        slots:
          contactId: path.contactId
          type: requestBody.type
      - text: Limit access to contact {contactId} to the users {accessors}.
        slots:
          contactId: path.contactId
          accessors: requestBody.accessors
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search all contacts
      effect: read
      questions:
      - Can I search my whole contact database with an OData filter?
      - What's the way to page through every contact I have?
      instructions:
      - text: List all my contacts.
      - text: Show every contact with phone numbers formatted as {phoneFormat}.
        slots:
          phoneFormat: query.phoneFormat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new contact
      effect: write
      questions:
      - How do I add a brand-new person to my contacts?
      - Can I set custom fields when I create a contact?
      instructions:
      - text: Create a contact named {firstName} {lastName} with email {emailAddress}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
          emailAddress: requestBody.emailAddress
      - text: Add a new contact {fullName} who works at {company} as {jobTitle}.
        slots:
          fullName: requestBody.fullName
          company: requestBody.company
          jobTitle: requestBody.jobTitle
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/group-contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List distinct contacts across several groups
      effect: read
      questions:
      - Can I get everyone in several groups at once without duplicates?
      - Which contacts belong to any of a set of groups?
      instructions:
      - text: List the distinct contacts across groups {ids}.
        slots:
          ids: query.ids
      - text: Combine the members of groups {ids} into one de-duplicated contact list.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/nearby'].get
  update:
    x-apievangelist-phrasing:
      intent: Find contacts near a location
      effect: read
      questions:
      - Which of my contacts are within a few kilometers of a given point?
      - Can I search contacts by latitude, longitude and radius?
      instructions:
      - text: Find contacts within {radius} km of {latitude}, {longitude}.
        slots:
          radius: query.radius
          latitude: query.latitude
          longitude: query.longitude
      - text: Show me who is near latitude {latitude} longitude {longitude} inside a {radius} km radius.
        slots:
          latitude: query.latitude
          longitude: query.longitude
          radius: query.radius
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/webinfo'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact web info links
      effect: read
      questions:
      - What web info hyperlinks are configured for contacts?
      - Can I see the web info link groups used on contact records?
      instructions:
      - text: List the contact web info hyperlinks.
      - text: Show all web info link groups for contacts.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/myrecord'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my own contact record
      effect: read
      questions:
      - Can I fetch the contact record that represents the logged-in user?
      - Where do I find my own My Record contact?
      instructions:
      - text: Show my own contact record.
      - text: Get the current user's My Record with phones in {phoneFormat} format.
        slots:
          phoneFormat: query.phoneFormat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/duplicate'].put
  update:
    x-apievangelist-phrasing:
      intent: Duplicate several contacts
      effect: write
      questions:
      - Can I copy a batch of contacts in one go?
      - Is it possible to duplicate many contacts but copy only their primary fields?
      instructions:
      - text: Duplicate contacts {contacts}.
        slots:
          contacts: requestBody.contacts
      - text: 'Make copies of contacts {contacts}, primary fields only: {primaryFields}.'
        slots:
          contacts: requestBody.contacts
          primaryFields: query.primaryFields
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/duplicate'].put
  update:
    x-apievangelist-phrasing:
      intent: Duplicate one contact
      effect: write
      questions:
      - Can I clone a single contact record?
      - When copying one contact, can I limit it to the primary fields?
      instructions:
      - text: Duplicate contact {contactId}.
        slots:
          contactId: path.contactId
      - text: 'Clone contact {contactId}, copying primary fields only: {primaryFields}.'
        slots:
          contactId: path.contactId
          primaryFields: query.primaryFields
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/hotlead-subscription'].put
  update:
    x-apievangelist-phrasing:
      intent: Turn hot lead alerts on or off for a contact
      effect: write
      questions:
      - Can I subscribe to hot lead notifications for a specific contact?
      - How do I stop hot lead alerts for one contact?
      instructions:
      - text: Subscribe me to hot leads for contact {contactId}.
        slots:
          contactId: path.contactId
      - text: Set the hot lead subscription on contact {contactId} to {active}.
        slots:
          contactId: path.contactId
          active: query.active
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/webinfo/{id}/HyperLink/{linkId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact web info hyperlink
      effect: write
      questions:
      - Can I change the URL a web info link points to?
      - What's the way to rename a hyperlink inside a web info group?
      instructions:
      - text: Point web info link {linkId} in group {id} at {href}.
        slots:
          linkId: path.linkId
          id: path.id
          href: requestBody.href
      - text: Rename hyperlink {linkId} in web info group {id} to {name}.
        slots:
          linkId: path.linkId
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'