What can we help you find? Products Platform Integration Playbooks and Resources Integration Knowledge Articles API: Using the new API query parameter "fields", Alternative to "return object"

API: Using the new API query parameter "fields", Alternative to "return object"

Revised: 19 November 2021

Introduction

For better performance when using APIs, we recommend customers using API filters or return_object in the queries but API filters are only available for specific object types, and in future releases, we will be deprecating the return_object. As part of this, the alternative way to create dynamic API filters as needed can be specified as an API query parameter with the fields we need.

The newly added fields within the APIs will only appear in API responses when accompanied by a specific field mentioned in API response filter or the 'fields' query parameter.

Integration Objects

These objects work with the query parameter: fields

Approvals API

https://<customer>.coupahost.com/api/approvals?fields=["id","created-at"]&limit=1

https://<customer>.coupahost.com/api/approvals?approvable-type=EasyFormResponse&status[in]=pending_approval,approved&updated-at[gt_or_eq]=2021-11-01T00:00:00&fields=["id","approvable-type","approvable-id"]

Charges API

https://<customer>.coupahost.com/api/charges?fields=["id”,”external-ref-id"]&limit=1

Example for nested fields:

https://<customer>.coupahost.com/api/charges?fields=["id","external-ref-id",{"currency":["code"]}]&limit=1

Contracts API:

Example: https://<customer>.coupahost.com/api/contracts?status=published&fields=["id","status"]&limit=1

Example for nested fields:

https://<customer>.coupahost.com/api/charges??limit=1&fields=["id","external-ref-id",{"supplier":["id","name"]}]

CoupaPay Payments API

https://<customer>.coupahost.com/api/coupa_pay/payments?status=published&fields=["id","status"]&limit=1

Example for nested fields:

fields=["id","payment-batch-id","status","exchange_rate","updated_at",{"pay_from_account":["id",{"currency":["code"]}]},{"pay_to_currency":["code"]},{"payee":["number"]},{"digital_check":["check_number"]},{"payment_details":["id","updated_at","source_transaction_id","source_transaction_reference","discount_total","payment_total",{"payable_allocations":["id","updated_at","payable_to_amount","source_transaction_to_reference","source_transaction_to_id"]},{"currency":["code"]}]}]

Custom Objects API

https://<customer>.coupahost.com/api/custom_objects/<ID>/object_instances?updated_at[gt_or_eq]=2021-11-10&fields=["id","created_at","updated_at","custom_object_name","custom_object_code","form_response_id","owner_id","due_date","start_date","duration","percentage","linkable_type","linkable_id",{"created_by": ["id"]},{"updated_by": ["id"]},{"custom_fields": {}}]

Easy Form Responses API

https://<customer>.coupahost.com/api/easy_form_responses/<ID>?fields=["id","created_at","updated_at","easy_form_id","name","status","submitted_at",{"subject": ["id","supplier_id","custom_object_name","custom_object_code"]},{"easy_form_widget_responses": ["id","easy_form_id","easy_form_widget_id","easy_form_response_id","answer","type","field_name","widget_label"]},{"requested_by": ["id"]},{"created_by": ["id"]},{"updated_by": ["id"]}]

Expense Reports API

https://<customer>.coupahost.com/api/expense_reports?status=approved_for_payment&fields=["id","title"]&limit=1

Example for nested fields:

https://<customer>.coupahost.com/api/users?status=active&fields=["id",{"expense_lines":["id","amount"]}]&limit=1

Invoices API

https://<customer>.coupahost.com/api/invoices?status=approved&fields=["id","status"]&limit=1

Example for Nested fields:

/invoices/:id?fields=["id", "invoice-number", { "currency": [ "code" ] },{"account_type":["id", "name"]}]

Items API

https://<customer>.coupahost.com/api/items?fields=["id","created-at"]&limit=1

Purchase Orders API

https://<customer>.coupahost.com/api/purchase_orders?status=issued&fields=["id","status"]&limit=1

Example for Nested fields:

https://<customer>.coupahost.com/api/purchase_orders?limit=1&fields=[ "id", "created_at", "updated_at", "order_header_id", "po_number", "status", "version", { "custom_fields": {} }, { "ship_to_address": [ "id", "created_at", "updated_at", "name", "location_code", "street1", "street2", "city", "state", "postal_code", "attention", "active", { "country": [ "code" ] }, { "custom_fields": {} } ] }, { "ship_to_user": [ "id", "login" ] }, { "supplier": [ "id", "name", "display_name", "number", { "primary_address": [ "id", "name", "location_code", "street1", "street2", "city", "state", "postal_code", "attention", "active", { "country": [ "code" ] } ] } ] }, { "payment_term": [ "id", "code" ] }, { "currency": [ "code" ] }, { "shipping_term": [ "id", "code" ] }, { "order_line_changes": [ "id", "created_at", "updated_at", "line_num", "description", "order_header_change_id", "order_line_id", "price", "quantity", "total", { "account": [ "id", "name", "code", "segment_1", "segment_2", "segment_3", "segment_4" ] }, { "custom_fields": {} }, { "currency": [ "code" ] }, { "commodity": [ "name", { "custom_fields": {} } ] }, { "uom": [ "code" ] } ] }, { "current_approval": [ "id", "created_at", "updated_at", "position", "approval_chain_id", "status", "approval_date", "note", "type", "approvable_type", "approvable_id", "delegate_id", { "approver": [ "id" ] }, { "approved_by": [ "id", "login", "employee_number" ] } ] }, { "approvals": [ "id", "created_at", "updated_at", "position", "approval_chain_id", "status", "approval_date", "note", "type", "approvable_type", "approvable_id", "delegate_id", { "approved_by": [ "id", "login", "employee_number" ] } ] }]

Purchase Order Changes API

https://<customer>.coupahost.com/api/purchase_order_changes?fields=["id","created-at"]&limit=1

Example for Nested fields:

Requisitions API

https://<customer>.coupahost.com/api/requisitions?status=ordered&fields=["id","status"]&limit=1

Example for Nested fields:

https://<customer>.coupahost.com/api/requisitions?limit=1&fields=[ "id", "submitted_at", "us_estimated_tax", { "currency": [ "code" ] }, { "ship_to_address": [ "id", "name", "location_code", "street1", "street2", "city", "state", "postal_code", "attention", "active", "vat_number", { "country": [ "code" ] }, { "custom_fields": {} } ] }, { "requisition_lines": [ "id", "description", "line_num", "need_by_date", "order_line_id", "quantity", "source_part_num", "unspsc_code", "status", "supp_aux_part_num", "total", "line_type", "supplier_site_id", "unit_price", { "account": [ "name", "code", "segment_1", "segment_2", "segment_3", "segment_4", { "account_type": [ "name" ] } ] }, { "uom": [ "code" ] }, { "shipping_term": [ "code" ] }, { "supplier": [ "id", "name", "display_name", "number", { "primary_address": [ "id", "name", "location_code", "street1", "street2", "city", "state", "postal_code", "attention", "active", { "country": [ "code" ] } ] } ] }, { "commodity": [ "name" ] }, { "custom_fields": {} } ] }, { "current_approval": [ "id", "created_at", "updated_at", "position", "approval_chain_id", "status", "approval_date", "note", "type", "approvable_type", "approvable_id", "delegate_id", "holdable" ] }, { "custom_fields": {} }]

Suppliers API

Example: https://<customer>.coupahost.com/api/suppliers?status=active&fields=["id","name"]&limit=1

Example for nested fields:

https://<customer>.coupahost.com/api/users?status=active&fields=["id",{"primary_contact":["name-given"]}]&limit=1

Supplier Items API

https://<customer>.coupahost.com/api/supplier_items?fields=["id","created-at"]&limit=1

Supplier Risk Aware Feed API

https://<customer>.coupahost.com/api/supplier_risk_aware_feed?fields=["id","number-field-01"]&limit=1

Example for nested fields:

https://<customer>.coupahost.com/api/users?status=active&fields=["id",{"supplier":["id","name"]}]&limit=1

Tasks API

https://<customer>.coupahost.com/api/tasks?&updated_at[gt_or_eq]=2021-07-01&linkable-type=Project&owner-id[blank]=false&linkable[status][not_eq]=draft&fields=["id","created_at","updated_at","title","description","status","owner_id","due_date","start_date","duration","percentage","linkable_type","linkable_id",{ "owner": [ "id"]},{ "resolved_by": [ "id"]},{ "linkable": [ "id","created_at","updated_at","name","active","open","description","mention_name","start_date","external_reference_number","end_date","commodity_id","status",{"template_group": ["id","name",{"custom_fields": {}}]},{"category": ["id","name",{"custom_fields": {}}]},{"department": ["id","name",{"custom_fields": {}}]},{"users": ["id","email",{"custom_fields": {}}]},{"commodity": ["id","name",{"custom_fields": {}}]},{"custom_fields": {}}]},{ "created_by": [ "id"]},{ "updated_by": [ "id"]}]

Users API

Example: https://<customer>.coupahost.com/api/users?status=active&fields=["id","email"]&limit=1

Example for nested fields:

https://<customer>.coupahost.com/api/users?status=active&fields=["id","external-ref-id",{"roles":["name"]}]&limit=1

API Filter Reference Doc

Success Portal Article: https://success.coupa.com/Integrate/Integration_Knowledge_Articles/API_Response_Filters#As_an_operator