Skip to main content

 

 

Coupa Success Portal

API Return Formats

Overview

Coupa's API returns a lot of data by default (for example: full objects for associated objects). The API return payloads can be very large and therefore slow. This can be a problem for customers that do not need the extraneous data not to mention the unnecessary consumption of resources. 

To make things easier, Coupa has a return format  return_object=shallow that returns a limited JSON or XML response instead of the entire schema, and all associations, for an object. The concept of optionally specifying a return_object is not new, only the concept of the "shallow" format. If no return_object is specified then the full return value is returned.

How It Works

The optional query parameter return_object now supports the following 3 values:

  • none  : Nothing is returned. This is only supported for PUT and POST (not queries, like GET, where it doesn't make sense).
  • limited  : Only ID's are returned. This is supported for all commands.
  • shallow: This parameter returns all attributes/fields of the object being called and only the IDs and natural keys of the one-deep associations.

The parameter return_object=shallow is supported for the following:

  • POST commands
  • PUT commands
  • GET commands

Return Object

You can use the return_object param to control the response body format on any basic create, update, or query calls.

On create and update return_object values supported are: none, limited, and shallow.

On query calls values supported are: limited and shallow.

Example: limited response on query

Query:  https://example.coupahost.com/api/expense_reports?return_object=limited
Response Code:  200
Response Body:
{“id”:1}

Example: none response on create

POST:  https://example.coupahost.com/api/ex...rn_object=none
Request Body:
{
 "id":2,
 "currency":{
   "code":"USD"
 },
 "expense-lines":[
   {
     "description":"Airfare to Reno",
     "merchant":"American Airlines",
     "reason":"",
     "amount":"255.0",
     "expense-date":"2010-02-05T00:00:00-08:00",
     "start-date":"2010-02-05T00:00:00-08:00",
     "expense-category":{
       "name":"Airfare",
     }
   },
 ],
}
Response Code:  200
Response Body:

Example: shallow response on create

Query:  https://example.coupahost.com/api/ex...object=shallow
Response Code:  200
Response Body:
{
 "id":158,
 "created-at":"2010-09-22T20:42:57-07:00",
 "updated-at":"2014-04-24T14:56:49-07:00",
 "title":"",
 "status":"pending_approval",
 "submitted-at":"2014-04-24T14:56:49-07:00",
 "auditor-note":null,
 "reject-reason":null,
 "paid":false,
 "total":"567.07",
 "audit-score":26,
 "exported":false,
 "last-exported-at":null,
 "external-src-ref":null,
 "external-src-name":null,
 "currency":{
   "id":1,
   "code":"USD"
 },
 "expensed-by":{
   "id":20,
   "login":"user_login",
   "email":"user_login@coupa.com"
 },
 "created-by":{
   "id":20,
   "login":"user_login",
   "email":"user_login@coupa.com"
 },
 "updated-by":{
   "id":20,
   "login":"user_login",
   "email":"user_login@coupa.com"
 },
 "expense-lines":[
   {
     "id":546,
     "external-src-ref":null
   },
   {
     "id":547,
     "external-src-ref":null
   },
   {
     "id":548,
     "external-src-ref":null
   },
   {
     "id":549,
     "external-src-ref":null
   }
 ],
 "comments":[ ]
}
  • Was this article helpful?