# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Nylas Contacts API
  version: 1.0.0
extends: openapi/nylas-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['/v3/grants/{grant_id}/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List or filter a user's contacts
      effect: read
      questions:
      - Which contacts in someone's address book have a given email address?
      - Can I list only the contacts in one contact group?
      - How can I find a contact by phone number?
      instructions:
      - text: List contacts for grant {grant}.
        slots:
          grant: path.grant_id
      - text: Find contacts on {grant} with email {email}.
        slots:
          grant: path.grant_id
          email: query.email
      - text: Show contacts in group {group} for {grant}.
        slots:
          group: query.group
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a contact to an address book
      effect: write
      questions:
      - How do I add a new person to a user's address book?
      - Can I save a job title and company when creating a contact?
      instructions:
      - text: Add a contact named {given_name} {surname} for grant {grant}.
        slots:
          given_name: requestBody.given_name
          surname: requestBody.surname
          grant: path.grant_id
      - text: Create contact {given_name} at {company_name} on {grant}.
        slots:
          given_name: requestBody.given_name
          company_name: requestBody.company_name
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/contacts/{contact_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one contact
      effect: read
      questions:
      - What details do we have for a specific contact?
      - Can I get a contact's profile picture as image data?
      instructions:
      - text: Show contact {contact} for grant {grant}.
        slots:
          contact: path.contact_id
          grant: path.grant_id
      - text: Get contact {contact} on {grant} including the profile picture.
        slots:
          contact: path.contact_id
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/contacts/{contact_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact's details
      effect: write
      questions:
      - Can I change an existing contact's job title or notes?
      - What happens to nested fields when I update a contact?
      instructions:
      - text: Update the job title of contact {contact} on {grant} to {job_title}.
        slots:
          contact: path.contact_id
          grant: path.grant_id
          job_title: requestBody.job_title
      - text: Change contact {contact}'s given name to {given_name} for grant {grant}.
        slots:
          contact: path.contact_id
          given_name: requestBody.given_name
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/contacts/{contact_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact
      effect: destructive
      questions:
      - How do I remove someone from a user's address book?
      - Can I delete a single contact by ID?
      instructions:
      - text: Delete contact {contact} from grant {grant}.
        slots:
          contact: path.contact_id
          grant: path.grant_id
      - text: Remove contact {contact} from the address book on {grant}.
        slots:
          contact: path.contact_id
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/contacts/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact groups
      effect: read
      questions:
      - What contact groups does this account have?
      - Are contact groups available for every email provider?
      instructions:
      - text: List contact groups for grant {grant}.
        slots:
          grant: path.grant_id
      - text: Show all contact groups on {grant}.
        slots:
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'