API Return Formats
Note: Coupa now offers more advanced API Filters that let
you define a specific output. We suggest using these filters instead of the shallow format,
which will be deprecated in a future release.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 IDs 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
The fields query operator allows you to pass the fields you want in the
response body. The format of the fields value is JSON. Please refer to the
example below:
?fields=["id","invoice_number",{"invoice_lines":["id","line_num"]}]
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":[ ]
}