# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for Drata Personnel API version: 1.0.0 extends: openapi/drata-personnel-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: 11 - target: $.paths['/personnel'].get update: x-apievangelist-phrasing: intent: List personnel records effect: read questions: - Which employees on our personnel roster are out of compliance right now? - Can I page through the full personnel list filtered by employment status? instructions: - text: List all personnel records with employment status {employmentStatus}. slots: employmentStatus: query.employmentStatus[] - text: Page through the personnel roster where overall compliance status is {complianceStatus}. slots: complianceStatus: query.complianceStatus[] method: generated generated: '2026-09-26' - target: $.paths['/personnel-search'].get update: x-apievangelist-phrasing: intent: Search personnel across all workspaces effect: read questions: - How do I find a person by name or email across every workspace I can access? - Which people in any workspace are missing MFA or security training? - Can a search across all workspaces return facet counts by compliance status? instructions: - text: Search every workspace for personnel matching {q}. slots: q: query.q - text: Find personnel in all workspaces whose disk encryption status is {diskEncryptionStatus}. slots: diskEncryptionStatus: query.diskEncryptionStatus[] - text: Across all workspaces, find people whose last name starts with {lastName}. slots: lastName: query.lastName method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/personnel-search'].get update: x-apievangelist-phrasing: intent: Search personnel within one workspace effect: read questions: - Can I search the people in a single workspace by first name prefix? - Which people in one specific workspace haven't completed HIPAA training? instructions: - text: Search workspace {workspaceId} for personnel matching {q}. slots: workspaceId: path.workspaceId q: query.q - text: In workspace {workspaceId}, find people whose background check status is {bgCheckStatus}. slots: workspaceId: path.workspaceId bgCheckStatus: query.bgCheckStatus[] method: generated generated: '2026-09-26' - target: $.paths['/personnel/{personnelId}'].get update: x-apievangelist-phrasing: intent: Get one person's personnel record effect: read questions: - How do I pull up a single employee's personnel record using their email? - What does Drata hold on file for one specific person? instructions: - text: Get the personnel record for {personnelId}. slots: personnelId: path.personnelId - text: Show personnel {personnelId} with {expand} expanded. slots: personnelId: path.personnelId expand: query.expand[] method: generated generated: '2026-09-26' - target: $.paths['/personnel/{personnelId}'].put update: x-apievangelist-phrasing: intent: Update a person's employment details effect: write questions: - How do I record the separation date for someone who left the company? - Will editing a person's start date by hand stop HRIS sync from overwriting it? - Can I note why a personnel record is marked as not a real person? instructions: - text: Set the separation date of personnel {personnelId} to {separatedAt}. slots: personnelId: path.personnelId separatedAt: requestBody.separatedAt - text: Change the employment status of {personnelId} to {employmentStatus}. slots: personnelId: path.personnelId employmentStatus: requestBody.employmentStatus - text: Update the start date for personnel {personnelId} to {startedAt}. slots: personnelId: path.personnelId startedAt: requestBody.startedAt method: generated generated: '2026-09-26' - target: $.paths['/personnel/actions'].post update: x-apievangelist-phrasing: intent: Reset personnel IdP/HRIS sync effect: write questions: - How can I restore automatic identity provider updates after editing people manually? - Is it possible to reset HRIS sync for every person at once? instructions: - text: Run the {action} action on personnel {personnelIds}. slots: action: requestBody.action personnelIds: requestBody.personnelIds - text: Reset IdP and HRIS sync for all personnel. method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/scoped-personnel-groups'].get update: x-apievangelist-phrasing: intent: List groups in a workspace's personnel scope effect: read questions: - Which personnel groups are currently in scope for a workspace? - What teams decide who counts as personnel in a given workspace? instructions: - text: List the personnel groups scoped to workspace {workspaceId}. slots: workspaceId: path.workspaceId - text: Show the scoped groups for workspace {workspaceId}, {size} per page. slots: workspaceId: path.workspaceId size: query.size method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/scoped-personnel-groups'].put update: x-apievangelist-phrasing: intent: Replace a workspace's scoped personnel groups effect: write questions: - Can I set the exact list of groups in a workspace's personnel scope in one call? - What happens to scoped groups I leave out when I overwrite the whole scope? instructions: - text: Replace the personnel scope of workspace {workspaceId} with groups {groupIds}. slots: workspaceId: path.workspaceId groupIds: requestBody.groupIds - text: Make {groupIds} the only groups in scope for workspace {workspaceId}. slots: workspaceId: path.workspaceId groupIds: requestBody.groupIds method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/scoped-personnel-groups'].post update: x-apievangelist-phrasing: intent: Add a group to a workspace's personnel scope effect: write questions: - How do I add one more team to a workspace's personnel scope? - What error comes back if the group I'm adding to the scope is already assigned? instructions: - text: Add group {groupId} to the personnel scope of workspace {workspaceId}. slots: workspaceId: path.workspaceId groupId: requestBody.groupId - text: Bring personnel group {groupId} into scope for workspace {workspaceId}. slots: workspaceId: path.workspaceId groupId: requestBody.groupId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/scoped-personnel-groups/{groupId}'].delete update: x-apievangelist-phrasing: intent: Remove a group from a workspace's personnel scope effect: destructive questions: - Can I take a single department out of a workspace's scope without resending the full list? - Which call drops just one group from a workspace's personnel scope? instructions: - text: Remove group {groupId} from workspace {workspaceId}'s personnel scope. slots: workspaceId: path.workspaceId groupId: path.groupId - text: Take personnel group {groupId} out of scope for workspace {workspaceId}. slots: workspaceId: path.workspaceId groupId: path.groupId method: generated generated: '2026-09-26' - target: $.paths['/workspaces/{workspaceId}/scoped-personnel-counts'].get update: x-apievangelist-phrasing: intent: Count personnel in a workspace's scope effect: read questions: - How many people are reachable through a workspace's scoped groups? - Can I compare a workspace's scoped headcount with the total IdP-connected personnel? instructions: - text: Count the scoped personnel for workspace {workspaceId}. slots: workspaceId: path.workspaceId - text: Get scoped versus IdP-connected personnel totals for workspace {workspaceId}. slots: workspaceId: path.workspaceId method: generated generated: '2026-09-26'