Search Approval Policies

POST /base/approval-policies/search

Group: Base › Approval Policies · Operation ID: searchApprovalPolicies

Returns the approval policies that match the given filters, each in full with its rule lines, approvers, exclusion lines and notification settings.

Returns each match in full, the same record GET base/approval-policies/:id returns. Use this endpoint rather than the collection when you match on a legal entity: entityId and entityName are accepted only in the request body, and the collection returns entityName but will not filter or sort on it. Every filter is optional and they are combined with AND. Omitting all of them matches every policy. An entityId that matches no entity returns an empty page, not an error.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchApprovalPoliciesInput.

Field Type Required Description
filters object no The filters to apply. A policy must match every filter you send. Omit to return all approval policies.
filters.businessObject string no Limits results to policies governing this business object, for example 'VendorBill'. A code that matches no registered business object returns an empty page.
filters.status string no Limits results to policies in this lifecycle status. Accepted values: 'active', 'inActive'. Any other value returns an empty page.
filters.entityId string no Limits results to policies scoped to this legal entity, given as the entity id. Accepted only in the request body. An id that matches no entity returns an empty page, not an error. This does not include the all-entities policies. Combine with isAllEntities to widen. See id on GET base/entities.
filters.entityName string no Limits results to policies whose legal entity name contains this text. The match is case-sensitive. Accepted only in the request body. Use entityId when you already have the id.
filters.isAllEntities boolean no Limits results to policies that cover every legal entity when true, or only single-entity policies when false.
filters.policyHeaderNumber string no Limits results to the policy with this policy number. The match is exact.
filters.startDate object no Limits results by the policy's startDate. Both bounds are inclusive. Use format YYYY-MM-DD, and omit either side for an open-ended range.
filters.startDate.start string no
filters.startDate.end string no
filters.endDate object no Limits results by the policy's endDate. Both bounds are inclusive. Use format YYYY-MM-DD, and omit either side for an open-ended range.
filters.endDate.start string no
filters.endDate.end string no
page object no Cursor pagination. Omit the whole object for the first page at the default size.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit for the first page.
page.size number no The number of policies per page. Defaults to 50. A value above 200 is treated as 200, not rejected.

Example:

{
  "filters": {
    "businessObject": "VendorBill",
    "status": "active"
  },
  "page": {
    "size": 25
  }
}

Response

200 Success

Under data (searchApprovalPoliciesOutput):

Field Type Required Description
items array of object yes The approval policies that match, oldest first. An empty array when nothing matches.
items[].id string yes The unique identifier for the approval policy.
items[].policyHeaderNumber string no The policy number, assigned when the policy is created and stable across edits.
items[].entityId string no The legal entity the policy applies to. Absent when isAllEntities is true. See id on GET base/entities.
items[].entityName string no The name of the legal entity the policy applies to. Absent when isAllEntities is true.
items[].isAllEntities boolean no Whether the policy applies to every legal entity rather than the one named by entityId.
items[].businessObject string yes The code of the business object the policy governs, for example 'VendorBill', 'ExpenseReport' or 'PurchaseOrder'.
items[].status string yes The lifecycle status of the policy. Possible values: 'active', 'inActive'. Only active policies are matched against new documents.
items[].startDate string no The first date the policy is eligible for matching. Format YYYY-MM-DD. Absent when there is no lower bound.
items[].endDate string no The last date the policy is eligible for matching. Format YYYY-MM-DD. Absent when there is no upper bound.
items[].submitterCannotApprove boolean no Whether the document submitter is stopped from approving their own document.
items[].approverCommentEnabled boolean no Whether approvers are prompted for an optional comment at approve time.
items[].lastModifiedDate string (date-time) yes The date and time the approval policy last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].notification object no The notification channels used when approvers and submitters are told about this policy's documents. Absent when they have never been configured for this policy.
items[].notification.emailNotification boolean no
items[].notification.nativeNotification boolean no
items[].notification.slackNotification boolean no
items[].lines array of object yes The policy's rule lines, ordered by step. A document picks up the approvers of every line it matches.
items[].lines[].id string yes
items[].lines[].policyLineNumber string no
items[].lines[].criteria string yes The document field the rule tests, for example 'Vendor' or 'Total Amount'. The literal COMPOSITE marks a line whose value is a JSON AND or OR expression over several criteria.
items[].lines[].operator string yes
items[].lines[].value array of string yes The values the criteria is compared against, each as a string. For a COMPOSITE line this is a single-element array holding the JSON expression.
items[].lines[].valueType string no
items[].lines[].step number yes The approval order, starting at 1. Lines that share a step are evaluated and approved together.
items[].lines[].requireAction string no
items[].lines[].approvers array of object yes The approvers assigned to this line. A line always has at least one.
items[].lines[].approvers[].id string yes
items[].lines[].approvers[].approverId number yes The approver. For approverType 'employee' or 'supremeApprover' it is the employee, and for 'manager' it is the manager-hierarchy record. It is an integer, not a UUID. There is no endpoint for it.
items[].lines[].approvers[].approverType string yes
items[].lines[].approvers[].approverName string no The resolved display name of the approver. Absent when the referenced employee or manager no longer exists.
items[].exclusionLines array of object yes The exclusion lines. A document matching any of them is exempted from the policy entirely.
items[].exclusionLines[].id string yes
items[].exclusionLines[].criteria string yes
items[].exclusionLines[].operator string yes
items[].exclusionLines[].value array of string yes
items[].exclusionLines[].valueType string no
pagination object yes The pagination cursor for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes True when more matches remain beyond this page.

Statuses