Approvals API (/approvals)

Use the approvals API to create, update, or query the approval of a document. This includes specific endpoints to take action (reject/hold/approve) as well as requisition details like requestor, line items, and shipping details.

The URL to access the approvals API is:

https://<instance>/api/approvals/<approval id>

See Integration Best Practices for more info. To learn more about implementing remote approvals, see Remote Approvals via API.

Actions


Verb	Path	Action	Description
PUT	`/api/approvals/:id/approve`	approve	Perform Approve action on an approval
PUT	`/api/approvals/:id/hold`	hold	Perform Hold action on an approval
GET	`/api/approvals`	index	Query approvals
PUT	`/api/approvals/:id/reject`	reject	Perform Reject action on an approval
GET	`/api/approvals/:id`	show	Show approval
PUT	`/api/approvals/:id`	update	Update approval

Elements

These are the elements available for the Approvals API


Field Name	Field Description	Out	Type
approvable-id	The document ID that was approved	yes	integer
approvable-type	The document type that was approved (requisition, purchase order, etc)	yes	string(255)
approval-chain-id	ID of the approval chain this approval is located in	yes	integer
approval-date	The date the approval occurred	yes	datetime
approved-by	The user name that made the approval	yes	User
approver	approver	yes	User, Approval Group
approver-id	The user ID that made the approval	yes	integer
approver-type	The role of the approver	yes	string(255)
created-at	Automatically created by Coupa in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ	yes	datetime
created-by	User who created	yes	User
delegate	delegate	yes	User, Approval Group
delegate-id	The delegate ID that made the approval (if applicable)	yes	integer
delegates	Delegates	yes	Delegate Approval
holdable	Hold the approval or not	yes	boolean
id	Coupa unique identifier	yes	integer
note	Reason for approval or reject	yes	text
position	The position in the approval chain this approval occurred	yes	integer
reasons	Reasons	yes	Approval Reason
status	The status of the approval (approved, escalated, rejected, etc)	yes	string(50)
type	How the approval occured (override approval, approval chain approval, etc)	yes	string(255)
updated-at	Automatically created by Coupa in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ	yes	datetime
updated-by	User who updated	yes	User

Example

In this example, we queried for a single approval with an ID of 12622. We did a GET to the URL:

https://<instance url>/api/approvals/12622

Approvals GET Response

<?xml version="1.0" encoding="UTF-8"?>
<approval>
	 <id type="integer">12622</id>
	 <created-at type="datetime">2012-02-15T14:56:22-08:00</created-at>
	 <updated-at type="datetime">2012-04-23T11:49:25-07:00</updated-at>
	 <position type="integer">1</position>
	 <approval-chain-id nil="true" />
	 <status>approved</status>
	 <approval-date type="datetime">2012-02-15T14:56:59-08:00</approval-date>
	 <note />
	 <type>ManagementHierarchyApproval</type>
	 <approvable-type>RequisitionHeader</approvable-type>
	 <approvable-id type="integer">2696</approvable-id>
	 <approver>
			<id type="integer">3</id>
			<login>vpierre</login>
			<email>upgrade+vp@coupa.com</email>
			<employee-number />
			<firstname>Victor (CFO)</firstname>
			<lastname>Pierre</lastname>
			<salesforce-id nil="true" />
	 </approver>
	 <created-by>
			<id type="integer">9</id>
			<login>bjenkins</login>
			<email>upgrade+bj@coupa.com</email>
			<employee-number />
			<firstname>Bob (VP Procurement)</firstname>
			<lastname>Jenkins</lastname>
			<salesforce-id nil="true" />
	 </created-by>
<updated-by>
			<id type="integer">17</id>
			<login>coupa_metrics_gatherer</login>
			<email>do_not_reply_metrics@coupa.com</email>
			<employee-number nil="true" />
			<firstname>Coupa</firstname>
			<lastname>Metrics</lastname>
			<salesforce-id nil="true" />
	 </updated-by>
</approval>

Approving or Rejecting

The following describes how you can use the Coupa API to perform actions on Approvals.

Approving

/api/approvals/{id}/approve

Rejecting

/api/approvals/{id}/reject

Adding Reason

In both cases, an approval must be Pending (and not already approved or rejected) for the action to be valid. It is also possible to provide a "Reason" for the rejection through the XML request directly. For example, to reject an approval by id of 12612 and provide a reason of "Rejected by Integration", you would use the following request:

PUT https://{instance url}/api/approvals/12612/reject?reason=Rejected%20by%20Integration

Successful requests will return HTTP 200 Response. The body of the response will include the created requisition. Unsuccessful requests will return

HTTP 400 Bad Request

. The body of the response will include validation errors formatted as XML.

Coupa Documentation