# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Conga Sign Approval API
  version: 1.0.0
extends: openapi/conga-approval-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: 12
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals'].put
  update:
    x-apievangelist-phrasing:
      intent: Update all approvals on a document
      effect: write
      questions:
      - Can I update every signature approval on a document in one request?
      - Is there a way to replace the whole set of approvals on a package document?
      instructions:
      - text: Update all of the approvals on document {documentId} in package {packageId}.
        slots:
          documentId: path.documentId
          packageId: path.packageId
      - text: Rewrite the full approval list for document {documentId} of package {packageId}.
        slots:
          documentId: path.documentId
          packageId: path.packageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a signature approval to a document
      effect: write
      questions:
      - How do I add a new signature block for a role on a Conga Sign document?
      - Can a new approval be marked optional or require captured signatures?
      - Does creating an approval support text anchor extraction?
      instructions:
      - text: Create an approval for role {role} on document {documentId} in package {packageId}.
        slots:
          role: requestBody.role
          documentId: path.documentId
          packageId: path.packageId
      - text: Add an optional approval named {name} to document {documentId} of package {packageId}.
        slots:
          name: requestBody.name
          documentId: path.documentId
          packageId: path.packageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one approval on a document
      effect: read
      questions:
      - What fields and role are set on a specific approval in a document?
      - Has a particular signature approval been signed yet?
      instructions:
      - text: Get approval {approvalId} on document {documentId} in package {packageId}.
        slots:
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
      - text: Show the details of approval {approvalId} in package {packageId}, document {documentId}.
        slots:
          approvalId: path.approvalId
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a specific approval on a document
      effect: write
      questions:
      - Can I change the role or make one existing approval optional?
      - How do I disable a single signature approval on a document?
      instructions:
      - text: Assign approval {approvalId} on document {documentId} of package {packageId} to role {role}.
        slots:
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
          role: requestBody.role
      - text: Update just approval {approvalId} in package {packageId}, document {documentId}.
        slots:
          approvalId: path.approvalId
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an approval from a document
      effect: destructive
      questions:
      - Can I remove a signature approval from a document before sending it?
      - What happens to a document when I delete one of its approvals?
      instructions:
      - text: Delete approval {approvalId} from document {documentId} in package {packageId}.
        slots:
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
      - text: Remove signature approval {approvalId} from package {packageId}, document {documentId}.
        slots:
          approvalId: path.approvalId
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a field to an approval with a generated name
      effect: write
      questions:
      - How do I place a new signature or input field on an existing approval?
      - Can I add a field to an approval and let the system name it?
      instructions:
      - text: Add a {type} field on page {page} to approval {approvalId} of document {documentId} in package {packageId}.
        slots:
          type: requestBody.type
          page: requestBody.page
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
      - text: Create an auto-named field at left {left}, top {top} on approval {approvalId}, document {documentId}, package {packageId}.
        slots:
          left: requestBody.left
          top: requestBody.top
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields/{fieldId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a field on an approval
      effect: read
      questions:
      - Where is a given field positioned on an approval and what type is it?
      - Can I read the current value of a field attached to an approval?
      instructions:
      - text: Get field {fieldId} on approval {approvalId} in document {documentId} of package {packageId}.
        slots:
          fieldId: path.fieldId
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
      - text: Show field {fieldId} from approval {approvalId}, package {packageId}, document {documentId}.
        slots:
          fieldId: path.fieldId
          approvalId: path.approvalId
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields/{fieldId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing field on an approval
      effect: write
      questions:
      - How do I move or resize a field that's already on an approval?
      - Will the field ID in my JSON body be used when updating an approval field?
      instructions:
      - text: Move field {fieldId} on approval {approvalId} to page {page} in document {documentId} of package {packageId}.
        slots:
          fieldId: path.fieldId
          approvalId: path.approvalId
          page: requestBody.page
          documentId: path.documentId
          packageId: path.packageId
      - text: Set existing field {fieldId} on approval {approvalId} to value {value} (package {packageId}, document {documentId}).
        slots:
          fieldId: path.fieldId
          approvalId: path.approvalId
          value: requestBody.value
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields/{fieldId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a field to an approval with a chosen field ID
      effect: write
      questions:
      - Can I create an approval field using a field ID I pick myself?
      - Why might creating an approval field by ID behave like an update?
      instructions:
      - text: Create field with ID {fieldId} on approval {approvalId} of document {documentId} in package {packageId}.
        slots:
          fieldId: path.fieldId
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
      - text: Add a {type} field using my own ID {fieldId} to approval {approvalId}, package {packageId}, document {documentId}.
        slots:
          type: requestBody.type
          fieldId: path.fieldId
          approvalId: path.approvalId
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields/{fieldId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a field from an approval
      effect: destructive
      questions:
      - Can I remove a single field from an approval without deleting the approval?
      - What's the way to drop an unwanted field from a signature approval?
      instructions:
      - text: Delete field {fieldId} from approval {approvalId} on document {documentId} of package {packageId}.
        slots:
          fieldId: path.fieldId
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
      - text: Remove field {fieldId} off approval {approvalId} in package {packageId}, document {documentId}.
        slots:
          fieldId: path.fieldId
          approvalId: path.approvalId
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields/{fieldId}/conditionalFields'].put
  update:
    x-apievangelist-phrasing:
      intent: Set show/hide conditions on an approval field
      effect: write
      questions:
      - How do I make a field appear only when another field is checked?
      - Can approval fields be enabled or disabled based on conditions?
      instructions:
      - text: Apply conditions {conditions} to field {fieldId} on approval {approvalId}, document {documentId}, package {packageId}.
        slots:
          conditions: requestBody.conditions
          fieldId: path.fieldId
          approvalId: path.approvalId
          documentId: path.documentId
          packageId: path.packageId
      - text: Update the conditional logic on field {fieldId} of approval {approvalId} in package {packageId}, document {documentId}.
        slots:
          fieldId: path.fieldId
          approvalId: path.approvalId
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/cs-packages/{packageId}/documents/{documentId}/signers/{signerId}/approvals'].get
  update:
    x-apievangelist-phrasing:
      intent: List approvals a signer can sign on a document
      effect: read
      questions:
      - Which approvals on a document is a particular signer eligible to sign?
      - What signature blocks are waiting for a given signer?
      instructions:
      - text: List signable approvals for signer {signerId} on document {documentId} in package {packageId}.
        slots:
          signerId: path.signerId
          documentId: path.documentId
          packageId: path.packageId
      - text: Show what signer {signerId} still needs to sign in package {packageId}, document {documentId}.
        slots:
          signerId: path.signerId
          packageId: path.packageId
          documentId: path.documentId
      method: generated
      generated: '2026-10-01'