Authentication
All data is stored as a business object or Resource, and each resource has a Resource URL, just like a webpage, where each resource is in the form /api/{resource_name}.
Make sure to access the url using https://
instead of http://
when using the Coupa API. Each Coupa customer has their own url, of the form {instance_name}.coupahost.com
. For example: https://companyname.coupahost.com/api/users
.
Coupa recommends authenticating API requests using OpenID Connect.
Historically, prior to support for OpenID Connect, API requests were authenticated by a unique API key, generated in Coupa. This method is still supported, but is going to be fully deprecated in R35. All API requests using this authentication method must pass an X-COUPA-API-KEY
” header, an API key, and the ACCEPT
header with value set to application/xml
for XML responses, or application/json
for JSON responses. A key can be created from the API Keys section of the Setup tab by an admin user. The key is a 40 character long case-sensitive alphanumeric code and is associated with an API user who is the equivalent of an admin user on Coupa. Any changes to resources via the API will be attributed to the API user.
API Key security can be configured for example, setting expiration dates, revoking a key, and configuring what objects and methods a key has access to.
API Keys Deprecation
R32 - OAuth2.0 is the only available option for new customers
R34 - new API keys can no longer be issued to existing customers
R35 - API keys will no longer be supported
More Details
Always validate the presence of elements in the XML/JSON before fetching the value as Coupa payload structure can change in the future to not display certain fields which have no or null values.
What methods are supported by the API?
GET (Read Data) - A HTTP GET Request will query Coupa and return information in JSON or XML format. A request at the resource root will list the first 50 objects starting from ID 1. Use these arguments to fine tune the query.
PUT (Update Data) - A HTTP PUT Request to /api/{resource}/{id}
will attempt update a resource. Only one resource can be updated per request and the payload should be a JSON or XML document with the elements to be updated. Not all fields are available through the API and any referenced data must already exist or the value will not be changed.
POST (Create Data) - A HTTP POST Request to the resource root with a JSON or XML payload will attempt to create a new resource. If successful, the resource is returned with the new id, which is generated by Coupa.
Deleting data is not supported for any resource via the API. Users can inactivate a subset of resources using a PUT request.
When should I use the API?
The Coupa API allows you to create, update, and query individual entries, and will mostly be used to manage objects within Coupa. With standard RESTful actions and definitive inputs and outputs, it makes it the easy day-to-day option for non-bulk actions. These methods can be accessed at any time, and built in are tools to allow you to simply check if a call will go through successfully, or to minimize the responses output. This is primarily used to make simple individual updates, or to query data.
XML vs JSON
Coupa supports both XML and JSON. Below is some basic information about each:
Extensible Markup Language (XML) is a set of rules for encoding documents in machine-readable form. XML’s design goals emphasize simplicity, generality, and usability over the Internet.
JavaScript Object Notation (JSON) is a lightweight text-based open standard designed for human-readable data interchange. It is derived from the JavaScript programming language for representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, it is language-independent, with parsers available for most programming languages.
JSON is less verbose than XML, because XML necessitates opening and closing tags (or in some cases less verbose self-closing tags), and JSON uses name/value pairs, concisely delineated by “{“ and “}” for objects, “[“ and “]” for arrays, “,” to separate pairs, and “:” to separate name from value.
Differences between XML and JSON in Coupa
Sample Requests/Responses - XML vs JSON
Regardless of which method you choose, the Coupa API requires that you set both your content-type and content-accept headers to the same type. Don't mix and match.
Using GraphQL
GraphQL is an open specificification for an API query language (thus the “QL” reference) that will allow you to make your integrations more responsive than ever by providing you with the ability to request the data you need and nothing more. GraphQL can also reduce the number of calls and associated round trips you are making by fetching all of the resources you need in a single or few number of calls.
See Introducing GraphQL for more info.
When should I use SFTP flat files?
Flat files allow you to load many records through a single transaction. Once an integration is set up, it will automatically run based on the parameters set. Integration runs and errors are managed within the app and provide insight on the number of entires added, error details, and who was automatically contacted about the error. This is primarily used to make mass updates or additions about key components of the product, like users or suppliers.
Additional info
wiki.tree(page.path)
Coupa supports a number of operators to enable you to query with precision.
Use Coupa's shallow API format to reduce the amount of data you get during a query.
Improved API key security with API key expiration and administrator specified permissions for APIs.
All new custom-fields are added to a custom-field namespace to avoid name conflicts and to make customer-added fields more easily identifiable.
Learn about the types of arguments that Coupa supports in conjunction with operators.
See how you can use queries to quickly identify and pull the data you require.
Additional info on how to use the Coupa API.
- Table Of Contents
- Build on the Coupa Platform
-
The Coupa Core API
- Get Started with the API
- OAuth 2.0 and OIDC
- Orchestration Documents
-
Resources
-
Reference Data Resources
- Accounts API (/accounts)
- Account Types API (/account_types)
- Account Validation Rules API (/account_validation_rules)
- Address API (/addresses)
- Announcements API (/announcements)
- Budget Lines API (/budget lines)
- Business Entities API (/business_entities)
- Content Groups API (/business_groups)
- Currencies API (/currencies)
- Data File Sources API (/data_file_sources)
- Departments API (/departments)
- Exchange Rates API (/exchange_rates)
- Financial Counterparties API (/financial_counterparties)
- Items API (/items)
- Legal Documents API (/legal_documents)
- Lookup Values API (/lookup_values)
- Matching Allocations API (/matching_allocations)
- Payment Terms API (/payment_terms)
- Projects API (/projects)
- Rate Card API
- Remit-To Addresses API (/suppliers/addresses)
- Shipping Terms API (/shipping_terms)
-
Suppliers API (/suppliers)
- Customer Support Contact API
- Diversity Association API
- Diversity Category and Subcategory APIs
- Diversity Certification Agency API
- Proxy Supplier API
- Punchout Site API
- Suppliers API Example Calls
- Supplier Items API (/supplier_items)
- Supplier Items Example Calls
- Supplier Remit To API
- Supplier Sites API (/supplier_sites)
- Supplier User API
- Supplier Information API (/supplier_information)
- Supplier Information Sites API (/supplier_information_sites)
- Supplier Information Tax Registrations API (/supplier_information_tax_registrations)
- Task API (/tasks)
- Tax Registrations API (/tax_registrations)
- Users API (/users)
-
Shared Resources
- Account Category API
- Account Group API
- Alternate API
- Amount Component API
- Asset Tags API
- Attachments API
- Attachment File API
- Bulk Price API
- Comments API
- Cycle Count Line Lot API
- Esign Provider Account API
- ExtraLineAttributes::OrderLineAttribute API
- Form API
- Group Buying Membership API
- Payments API
- Budget Period API
- Purposes API
- RA CLMA Contract API
- RA Risk Request API
- RA Risk Request Relationship API
- RA Risk Request Score API
- Return Request Line API
- Schedule Line API
- Supplier Order Header Change API
- Tagging API
- Tag API
- Unit of Measure API
-
Transactional Resources
- Approvals API (/approvals)
- Advance Ship Notices API (/asn)
- Charges API (/charges)
- Commodities API (/commodities)
-
Contracts API (/contracts)
- Contract API Example Calls
- Contract Classification API
- Contract Clause API
- Contract Clause Reference API
- Contract Detail API
- Contract Dispute API
- Contract Party API
- Contract Party Contact API
- Contract Template API (/contracts/templates)
- Contract Terms API
- Contract Types API
- Country Subdivision API
- Intellectual Property and Data API
- Reason Insights API
- Reason Insights Events API
- Payments API (/coupa_pay/payments )
- Coupa Pay Statements API (/coupa_pay/statements)
- Custom Object API (/custom_objects/id)
- Cycle Count Lines API (/cycle_count_lines)
- Data File Sources API (/data_file_sources)
- Default Receiving Locations API (/default_receiving_locations)
- Default Receiving Location API (/default receiving location)
- Easy Form Responses API (/easy_form_responses)
-
Expenses API (/expense_reports)
- Audit Status API
- Expense API Example Calls
- Expense Artifact API
- Expense Attendee API
- Expense Attendee Type API
- Expense Cash Advance API
- Expense Category API
- Expense Category Translation API
- Expense Lines API
- Expense Line Allocation API
- Expense Line Attendee API
- Expense Line Cash Advance API
- Expense Line Imported Data API
- Expense Line Mileage API
- Expense Line Mileage Allocation API
- Expense Line Per Diem API
- Expense Line Tax API
- Expense Line Virtual Card API
- Expense Preapproval API
- Expense Preapproval Line API
- Expense Reports API
- Expense Report Preapproval API
- Expense Trip API
- Expense Trip Segment API
- Expense Violation API
- Expense Virtual Card API
- Itemized Expense Line API
- Legal Entity API
- Integrations API (/integrations)
- Invoices API (/invoices)
- Object Translation API (/uoms/uom_id/translations)
- Order Confirmations API (/order_header_confirmations)
- Order List API (/order_pads)
- Payables API (/payables/)
- Pick Lists/Fulfillment Reservations API (/pick lists)
- Purchase Orders API (/purchase_orders)
-
Receipts API
- Adjustment Code API
- Inventory Adjustments API (/inventory_adjustments)
- Inventory Consumptions API (/inventory_consumptions)
- Inventory Transaction Lot API
- Inventory Transfers API (/inventory_transfers)
- Receiving Transactions API (/receiving_transactions)
- Receipts API Example Calls
- Return to Supplier Transactions API (/return_to_supplier_transactions)
- Return Requests API (/return_requests)
- Receipt Requests API (/receipt_requests)
- Requisitions API (/requisitions)
- Sourcing API (/quote_requests)
- Supplier Risk Aware Feed API (/supplier_risk_aware_feed)
-
Reference Data Resources
-
Coupa Core Flat Files (CSV)
- Getting Started
-
Flat File (CSV) Export
-
Standard CSV Exports
- Account Type Export
- Advance Ship Notices Export
- Commodity Export
- Contracts Export
- Coupa Pay Charges Export
- Coupa Pay Payments Export
- Data File Source Export
- Delegations Export
- Easy Form Widget Response Export
- Exchange Rate Export
- Expense Preapproval Export
- Expense Reports Export
- Integration Error Export
- Integration History Record Export
- Inventory Balance Export
- Inventory Transactions (Receipts) Export
- Invoices Export
- Item Export
- Lookup Values Export
- Object Translation Export
- Order Header Confirmation Export
- Order Header Change Export
- Order Line Confirmation Export
- Order Line Change Allocation Export
- Order Line Change Export
- Payables :: Allocation
- Payables :: Expense
- Payables :: Expense Preapproval Export
- Payables Invoice Export
- Procurement Milestone Export
- Project Export
- Project Link Export
- Purchase Orders Export
- Remit to Addresses Export
- Requisitions Export
- Schedule Line Export
- Sourcing Export
- Sourcing Quote Request Export
- Sourcing Quote Response Export
- Coupa Pay Statements Export
- Supplier Diversity Report Direct Spends Export
- Supplier Diversity Report Indirect Spends Export
- Supplier Diversity Report Summaries Export
- Supplier Information Export
- Supplier Information Site
- Supplier Site
- Tax Code Export
- Tax Code Rule Export
- Tax Registration Export
- TCS Tax Line Export
- User Group Export
- Work Confirmation/Header (Service/Time Sheet Header) Export
- Work Confirmation/Line (Service/Time Sheet Line) Export
-
Standard CSV Exports
-
Flat File (CSV) Import
- Account Import
- Account Type (CoA) Import
- Account Validation Rules Import
- Approval Chain Import
- Advance Ship Notice Import
- Budget Line Import
- Budget Line Adjustment Import
- Business Entity Import
- Commodity Import
- Commodity Translation Import
- Addresses Import
- Content Group Import
- Contract Import
- Departments Import
- Enterprise Import
- Exchange Rate Import
- Expense Mileage Data Import
- Expense Action Dynamic Category Limit Import
- Expense Category Import
- Expense Category Tax Rates Import
- Expense Category Translation Import
- Expense Import Category Map Import
- Expense Import Transaction Type Filter Map Import
- Expense Import User Map Import
- Expense Payment Import
- External Orders Import
- External Payments
- Forms (Easy Forms) Import
- Integration Contacts Import
- Integration Import
- Inventory Balance Import
- Inventory Balance Lot Import
- Invoices Import
- Invoice Payment Import
- Item Import
- Legal Entity Import
- Legal Payment Receipt Loader
- Lookup Values Import
- Object Instance Import
- Object Translation Import
- Order Confirmation Import
- Payment Import
- Payables :: External :: Payable Import
- Payment Term Import
- Project Import
- Purchase Order Change Import
- Quote Request Line Import
- Inventory Transactions (Receipts) Import
- Remit-to Addresses Import
- Requisitions Import
- Shippable Tracker Import
- Suppliers Import
- Supplier Risk Aware Feed Import
- Supplier Site Import
- Tax Code Import
- Tax Code Rule Import
- Tax Rate Import
- Tax Reference Import
- Tax Registration Import
- Treasury Cash Flow File Import
- Users Import
- User Group Import
- Warehouse Import
- Warehouse Location Import
- Service/Time Sheets Import
- Payables :: Allocation
- The CCW API
- CCW Flat Files (CSV)
- The CSO API
-
Treasury Integrations
- View Treasury API Documentation
-
Treasury CSV Format Descriptions
- Account Statement Import - CSV Format
- TTGL Bookings Export CSV Format
- Cash Flow Data Import CSV Formats
- Cash Flow Export - CSV Format
- CSV Table Export File Format
- Holidays Import CSV Format
- IC Balances - FX Rates Import - CSV Format
- IC Netting - FX Rates Import - CSV Format
- IC Netting - Payments Export - CSV Format
- IC Recon - Invoice Export - CSV Format
- IC Recon Server Import CSV Formats
- LMPLANNING - Liquidity Planning Data Import
- TTContract Leasing Payment Plan Import
- System - FX and Interest Rate Scenarios Import
- System - Market Data Import
- TTContract Interest and Repayment Plan Import
- Risk Assess Quick Integration
- Coupa Core User Authentication (SSO)
- Coupa Core Application IP Addresses
- Core API and CSV Download Formats