# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Conga Contact API
  version: 1.0.0
extends: openapi/conga-contact-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: 16
- target: $.paths['/api/data/v1/Contact'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact records
      effect: read
      questions:
      - Where can I see all contacts stored in Conga?
      - Can I sort and page through contact records by a field?
      instructions:
      - text: List my contact records.
      - text: Show contacts matching {criteria}, sorted by {field}.
        slots:
          criteria: query.criteria
          field: query.sortField
      - text: Get page {page} of contacts, {size} per page.
        slots:
          page: query.pageNumber
          size: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contact
      effect: write
      questions:
      - How do I add a single new contact with name and email?
      - Will creating a contact fail if the record already exists?
      instructions:
      - text: Create a contact named {first} {last} with email {email}.
        slots:
          first: requestBody.FirstName
          last: requestBody.LastName
          email: requestBody.Email
      - text: Add contact {last} to account {account}.
        slots:
          last: requestBody.LastName
          account: requestBody.Account
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/bulk'].put
  update:
    x-apievangelist-phrasing:
      intent: Update many contacts at once
      effect: write
      questions:
      - Can I update a batch of existing contacts in one request?
      - Is optimistic locking supported when bulk-updating contacts?
      instructions:
      - text: Bulk-update these existing contact records.
      - text: Update many contacts matched by field {field}.
        slots:
          field: query.UpdateByField
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many contacts at once
      effect: write
      questions:
      - Is it possible to insert a list of new contacts in a single call?
      - Can I bulk-create contacts and get the records back in the response?
      instructions:
      - text: Insert this batch of new contacts.
      - text: 'Bulk-create contacts and include payload in response: {include}.'
        slots:
          include: query.IncludeRecordPayloadInResponse
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/bulk'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete many contacts at once
      effect: destructive
      questions:
      - Can a batch of contact records be removed together?
      - Can I bulk-delete contacts by a field other than ID?
      instructions:
      - text: Bulk-delete the listed contact records.
      - text: Delete many contacts matched by field {field}.
        slots:
          field: query.DeleteByField
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/bulk'].patch
  update:
    x-apievangelist-phrasing:
      intent: Upsert many contacts
      effect: write
      questions:
      - Can I insert new contacts and update existing ones in the same call?
      - How do I upsert contacts in bulk?
      instructions:
      - text: Upsert this list of contacts.
      - text: Upsert contacts, matching existing ones on {field}.
        slots:
          field: query.UpdateByField
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/by-externalId/{externalId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact by external ID
      effect: read
      questions:
      - Which contact matches the ID from my other system?
      - Can I look up a Conga contact by its external identifier?
      instructions:
      - text: Get the contact with external ID {ext}.
        slots:
          ext: path.externalId
      - text: Look up contact by external identifier {ext}.
        slots:
          ext: path.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/by-externalId/{externalId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact by external ID
      effect: write
      questions:
      - How do I update a contact when I only know its external ID?
      - Can I change a contact's email using its external identifier?
      instructions:
      - text: Update the contact with external ID {ext}.
        slots:
          ext: path.externalId
      - text: Set email {email} on contact with external ID {ext}.
        slots:
          email: requestBody.Email
          ext: path.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/by-externalId/{externalId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact by external ID
      effect: destructive
      questions:
      - How do I delete a contact using its external identifier?
      - Can I remove a contact matched by external ID rather than record ID?
      instructions:
      - text: Delete the contact with external ID {ext}.
        slots:
          ext: path.externalId
      - text: Remove contact by external identifier {ext}.
        slots:
          ext: path.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Query contact records
      effect: read
      questions:
      - How do I search contacts with criteria and choose which fields come back?
      - Can a contact query return the total record count?
      instructions:
      - text: Query contacts matching {criteria}.
        slots:
          criteria: requestBody.Criteria
      - text: Search contacts and return only fields {fields}.
        slots:
          fields: requestBody.Select
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/recordtypes'].get
  update:
    x-apievangelist-phrasing:
      intent: List contact record types
      effect: read
      questions:
      - Which record types are defined for contacts?
      - What kinds of contact record types can I choose from?
      instructions:
      - text: List the contact record types.
      - text: Show every record type available for contacts.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Get contact count and storage size
      effect: read
      questions:
      - How many contact records do we have and how much disk do they use?
      - Can I see the storage footprint of the contact object?
      instructions:
      - text: Get the contact record count and size on disk.
      - text: Summarize how many contacts are stored.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact by record ID
      effect: read
      questions:
      - How do I fetch one contact using its Conga record ID?
      - What details are stored on a particular contact?
      instructions:
      - text: Get contact {id}.
        slots:
          id: path.id
      - text: Show the details of contact record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact by record ID
      effect: write
      questions:
      - How do I edit a single contact using its record ID?
      - Can I update a contact's title and phone number?
      instructions:
      - text: Update contact {id}.
        slots:
          id: path.id
      - text: Change the title of contact {id} to {title}.
        slots:
          id: path.id
          title: requestBody.Title
      - text: Set phone {phone} on contact record {id}.
        slots:
          phone: requestBody.Phone
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/data/v1/Contact/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact by record ID
      effect: destructive
      questions:
      - How do I delete one contact by its record ID?
      - Can I choose a delete behaviour when removing a contact?
      instructions:
      - text: Delete contact {id}.
        slots:
          id: path.id
      - text: Remove contact record {id} with behaviour {behaviour}.
        slots:
          id: path.id
          behaviour: query.deleteBehaviour
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/contacts/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find contacts by name for authoring
      effect: read
      questions:
      - Which contacts match a name when I'm authoring a document?
      - Can I search contacts by name from the authoring add-in?
      instructions:
      - text: Find contacts named {name}.
        slots:
          name: path.name
      - text: Look up authoring contacts matching {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-10-01'