REST API

August 21, 2024

2024.1

This software and related documentation are provided under a license agreement containing restrictions

on use and disclosure and are protected by intellectual property laws. Except as expressly permitted

in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast,

modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any

means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for

interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-

free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it

on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,

any programs embedded, installed or activated on delivered hardware, and modifications of such

programs) and Oracle computer documentation or other Oracle data delivered to or accessed by

U.S. Government end users are "commercial computer software" or "commercial computer software

documentation" pursuant to the applicable Federal Acquisition Regulation and agency-specific

supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure,

modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any

operating system, integrated software, any programs embedded, installed or activated on delivered

hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other

Oracle data, is subject to the rights and limitations specified in the license contained in the applicable

contract. The terms governing the U.S. Government's use of Oracle cloud services are defined by the

applicable contract for such services. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management

applications. It is not developed or intended for use in any inherently dangerous applications, including

applications that may create a risk of personal injury. If you use this software or hardware in dangerous

applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other

measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages

caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks

of their respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks

are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,

Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a

registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content,

products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and

expressly disclaim all warranties of any kind with respect to third-party content, products, and services

unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and

its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use

of third-party content, products, or services, except as set forth in an applicable agreement between you

and Oracle.

If this document is in public or private pre-General Availability status:

This documentation is in pre-General Availability status and is intended for demonstration and preliminary

use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation

and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to

this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of

this documentation.

If this document is in private pre-General Availability status:

The information contained in this document is for informational sharing purposes only and should be

considered in your capacity as a customer advisory board member or pursuant to your pre-General

Availability trial agreement only. It is not a commitment to deliver any material, code, or functionality, and

should not be relied upon in making purchasing decisions. The development, release, timing, and pricing

of any features or functionality described in this document may change and remains at the sole discretion

of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the

exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms

and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle

PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has

been executed by you and Oracle and with which you agree to comply. This document and information

contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle

without prior written consent of Oracle. This document is not part of your license agreement nor can it be

incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website

at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle

Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://

www.oracle.com/pls/topic/lookup?ctx=acc&id=trsif you are hearing impaired.

Sample Code

Oracle may provide sample code in SuiteAnswers, the Help Center, User Guides, or elsewhere through

help links. All such sample code is provided "as is” and “as available”, for use only with an authorized

NetSuite Service account, and is made available as a SuiteCloud Technology subject to the SuiteCloud

Oracle may modify or remove sample code at any time without notice.

No Excessive Use of the Service

As the Service is a multi-tenant service offering on shared databases, Customer may not use the Service

in excess of limits or thresholds that Oracle considers commercially reasonable for the Service. If Oracle

reasonably concludes that a Customer’s use is excessive and/or will cause immediate or ongoing

performance issues for one or more of Oracle’s other customers, Oracle may slow down or throttle

Customer’s excess use until such time that Customer’s use stays within reasonable limits. If Customer’s

particular usage pattern requires a higher limit or threshold, then the Customer should procure a

subscription to the Service that accommodates a higher limit and/or threshold that more effectively aligns

with the Customer’s actual usage pattern.

Table of Contents

REST API Overview .................................................................................................................. 1

Getting Started with the REST API .............................................................................................. 4

Supported Resources, Methods and API Features ......................................................................... 7

REST API Known Limitations ...................................................................................................... 9

Authentication ....................................................................................................................... 12

OAuth 2.0 Authorization ......................................................................................................... 14

Managing API Integration Applications ................................................................................. 14

Auditing and Managing OAuth 2.0 Authorizations ................................................................... 22

OAuth 2.0 for Integration Applications Developers .................................................................. 24

Authorizing Applications to Access OpenAir on Your Behalf ...................................................... 33

Request Format ..................................................................................................................... 36

Response Format .................................................................................................................. 40

Returned Data ...................................................................................................................... 41

Attribute Naming Convention, Data Types and Formats ............................................................... 42

Custom Fields ....................................................................................................................... 43

Active Filter Set ..................................................................................................................... 44

Filtering ............................................................................................................................... 45

Pagination ............................................................................................................................ 48

Sorting ................................................................................................................................. 50

Referenced Objects and Expansion .......................................................................................... 53

Errors .................................................................................................................................. 58

API Limits ............................................................................................................................. 62

RateLimit .......................................................................................................................... 63

Web Services Logs ................................................................................................................. 65

Generated API Documentation JSON ........................................................................................ 66

Testing the REST API Using Postman ........................................................................................ 70

REST API Endpoint Reference .................................................................................................. 79

Attachments ..................................................................................................................... 79

Contacts ........................................................................................................................... 81

Insert a Contact ............................................................................................................ 83

Get the List of Contacts .................................................................................................. 85

Get a Contact ............................................................................................................... 87

Update a Contact .......................................................................................................... 88

Delete a Contact ........................................................................................................... 90

Discover Available Methods and Fetch the Endpoint Reference for Contacts ............................ 91

Expense Reports ............................................................................................................... 92

Insert an Expense Report ............................................................................................... 94

Insert an Overlapping Expense Report .............................................................................. 97

Get the List of Expense Reports ....................................................................................... 99

Get an Expense Report ................................................................................................. 101

Update an Expense Report ............................................................................................ 104

Delete an Expense Report ............................................................................................. 106

Get the List of Receipts in an Expense Report .................................................................. 107

Get a Receipt associated with an Expense Report ............................................................. 110

Add an Attachment to an Expense Report ....................................................................... 113

Get the List of Attachments Associated with an Expense Report .......................................... 115

Get an Attachment Associated with an Expense Report ...................................................... 117

Get an Attachment File Associated with an Expense Report ................................................ 119

Get the Thumbnail for an Attachment Associated with an Expense Report ............................. 120

Replace an Attachment to an Expense Report .................................................................. 121

Delete an Attachment Associated with an Expense Report .................................................. 123

Delete Attachments Associated with an Expense Report ..................................................... 125

Discover Available Methods and Fetch the Endpoint Reference for Expense Reports ................ 126

Job Codes ....................................................................................................................... 127

Insert a Job Code ......................................................................................................... 128

Get the List of Job Codes .............................................................................................. 130

Get a Job Code ............................................................................................................ 132

Update a Job Code ...................................................................................................... 133

Delete a Job Code ........................................................................................................ 135

Discover Available Methods and Fetch the Endpoint Reference for Job Codes ......................... 136

Projects .......................................................................................................................... 137

Insert a Project ........................................................................................................... 146

Insert Multiple Projects ................................................................................................. 148

Create a Project from Template ..................................................................................... 150

Get the List of Projects ................................................................................................. 154

Get a Project ............................................................................................................... 156

Update a Project ......................................................................................................... 158

Update Multiple Projects ............................................................................................... 160

Delete a Project ........................................................................................................... 163

Delete Multiple Projects ................................................................................................ 164

Add an Attachment to a Project ..................................................................................... 165

Get the List of Attachments Associated with a Project ........................................................ 167

Get an Attachment Associated with a Project ................................................................... 170

Get an Attachment File Associated with a Project .............................................................. 172

Get the Thumbnail for an Attachment Associated with a Project .......................................... 173

Replace an Attachment to a Project ................................................................................ 174

Delete an Attachment Associated with a Project ................................................................ 176

Delete Attachments Associated with a Project .................................................................. 178

Discover Available Methods and Fetch the Endpoint Reference for Projects ........................... 179

Project Milestones ........................................................................................................... 180

Get the List of Project Milestones ................................................................................... 183

Get a Project Milestone ................................................................................................ 185

Project Phases ................................................................................................................. 188

Get the List of Project Phases ........................................................................................ 191

Get a Project Phase ..................................................................................................... 193

Project Tasks ................................................................................................................... 195

Insert a Project Task .................................................................................................... 199

Get the List of Project Tasks .......................................................................................... 201

Get a Project Task ....................................................................................................... 204

Add an Attachment to a Project Task .............................................................................. 206

Get the List of Attachments Associated with a Project Task ................................................. 208

Get an Attachment Associated with a Project Task ............................................................. 211

Get an Attachment File Associated with a Project Task ....................................................... 213

Get the Thumbnail for an Attachment Associated with a Project Task .................................... 214

Replace an Attachment to a Project Task ......................................................................... 215

Delete an Attachment Associated with a Project Task ......................................................... 217

Delete Attachments Associated with a Project Task ............................................................ 219

Receipts ......................................................................................................................... 220

Insert a Receipt ........................................................................................................... 223

Get the List of Receipts ................................................................................................ 225

Get a Receipt .............................................................................................................. 228

Update a Receipt ......................................................................................................... 230

Delete a Receipt .......................................................................................................... 232

Add an Attachment to a Receipt ..................................................................................... 233

Get the List of Attachments Associated with a Receipt ....................................................... 236

Get an Attachment Associated with a Receipt ................................................................... 238

Get an Attachment File Associated with a Receipt ............................................................. 240

Get the Thumbnail for an Attachment Associated with a Receipt .......................................... 241

Replace an Attachment to a Receipt ............................................................................... 242

Delete an Attachment Associated with a Receipt ............................................................... 244

Delete Attachments Associated with a Receipt .................................................................. 246

Discover Available Methods and Fetch the Endpoint Reference for Receipts ........................... 247

Time Entries .................................................................................................................... 248

Insert a Time Entry ...................................................................................................... 250

Get the List of Time Entries ........................................................................................... 252

Get a Time Entry ......................................................................................................... 255

Delete a Time Entry ..................................................................................................... 257

Discover Available Methods and Fetch the Endpoint Reference for Time Entries ...................... 258

Release History .................................................................................................................... 260

REST API Overview 1

REST API Overview

OpenAir REST API provides an interface for integration applications to exchange information with

OpenAir.

The REST API:

■

Is organized around REST.

■

Uses predictable resource-oriented URLs.

■

Accepts JSON-encoded request bodies.

■

Returns JSON-encoded responses.

■

Uses standard HTTP response codes, authentication and verbs.

The REST API lets you:

■

Use CRUD (create, read, update, delete) operations on OpenAir records.

■

Retrieve a list of records from a collections and use pagination.

■

Filter OpenAir record collections.

The REST API is a service layer that is built on top of the business layer in OpenAir. This ensures that

business rules configured for your OpenAir account are applied when an integration application interacts

with your OpenAir data through OpenAir REST API. Business rules include OpenAir account configuration

settings and access control mechanisms, as well as any user scripts deployed on your OpenAir account.

This guide provides a reference for using the REST API. This section provides a high level overview. Review

Getting Started with the REST API for guidance about setting up and using the API. Other sections in this

guide address specific conceptual topics, including Supported Resources, Methods and API Features,

OAuth 2.0 Authorization and Authentication, Request Format, Response Format, Active Filter Set, Errors,

API Limits, Web Services Logs and API features including Filtering, Pagination, Sorting and Referenced

Objects and Expansion. The final section gives reference information about supported endpoints,

methods, and resources — REST API Endpoint Reference.

You can also access the generated REST API reference documentation in OpenAPI 3.0 JSON format and

use it alongside this guide. For more information, see Generated API Documentation JSON.

REST API

Key Concepts 2

Important: The REST API was introduced in the October 10, 2020 OpenAir release. It is an

initial version with limited functionality.

Some optional features and application settings may not be fully supported.

The current scope of the REST API is limited to selected OpenAir modules and entities. It

supports the following resources: Expense reports (including attachments), Receipts (including

attachments), Projects, Job codes, Contacts. See Supported Resources, Methods and API Features.

As with any other API or platform features, it is crucial that you test integration applications

leveraging the REST API extensively on a Sandbox account. Make sure your integration

applications run smoothly without error on a non-production account before you implement it on

your production account.

Key Concepts

OpenAir REST API is an application programming interface (API) - a set of functions and procedures that

let application developers access OpenAir functionality and data within their application. The information

is exchanged across the internet in a consistent format.

Note: The REST API follows the same security best practice as OpenAir. All data is encrypted in

transport using the industry standard transport layer security (TLS) protocol.

REST

Representational State Transfer (REST) refers to the architectural style used to create web services that

let developers access OpenAir resources at pre-defined URLs using the HTTP protocol and perform CRUD

operations (Create, Retrieve, Update, Delete) on these resources.

Resource

A resource represents OpenAir data that can be uniquely identified. Each resource has its own unique

URL. When accessing the URL, information and content can be returned as a JSON-encoded string, in the

case of record information, or as download file, in the case of file attachments.

In OpenAir, the most important resource is a record. Resources can be grouped into collections that each

contain only one type of resources - for example, a collection of expense report records. A resource can

also contain a sub-collection — for example, an expense report contains a sub-collection of receipts, with

each receipt being a sub-resource. Collections are themselves resources as well.

REST API Benefits

The main benefits of REST web services include the following:

■

Business Layer API — In contrast with the XML API and SOAP API, which interface with the data layer

in OpenAir, the REST API interfaces with the business layer. The business logic is already applied —

REST API

REST API Limitations 3

you do not need to replicate the business logic in your integration applications. This makes integration

applications simpler and faster as it reduces the volume of data that needs to be exchanged and

processed. It also ensures that behavior is consistent with the OpenAir web application and across

integrated applications and that you can take advantage of new features in OpenAir when they

become available or when they are enabled for your account.

■

OAuth 2.0 — The REST API supports OAuth 2.0 exclusively for authentication and authorization, which

is a more robust and reliable way to access data.

■

JSON-encoded request bodies and responses — JSON (JavaScript Object Notation) is a lightweight

data-interchange format which is self-describing and human-readable.

■

Easier deployment — REST has a more flexible and lightweight architecture than SOAP, which

requires heavy programming and deployment environment (C#, Java).

REST API Limitations

Consider the following information when working with the REST API.

■

The REST API was introduced in the October 10, 2020 OpenAir release. It is an initial version with

limited functionality. Some OpenAir features and application settings may not be fully supported. See

REST API Known Limitations.

■

The current scope of the REST API is limited to selected OpenAir resources. See Supported Resources,

Methods and API Features.

■

As with any other API or platform features, it is crucial that you test integration applications leveraging

the REST API extensively on a Sandbox account. Make sure your integration applications run smoothly

without error on a non-production account before you implement it on your production account.

REST API

Getting Started with the REST API 4

Getting Started with the REST API

You can use the following steps to set up and get familiar with the REST API before using it in your

integration applications:

■

Step 1 — Prerequisites and Setup

■

Step 2 — Read the Relevant Documentation

■

Step 3 — Register an API Integration Application

■

Step 4 — Test and Familiarize Yourself With the REST API on a Sandbox Account

Step 1 — Prerequisites and Setup

The following features must be enabled for your OpenAir account to use the REST API.

Feature How to enable / Usage

API Access Contact your OpenAir account manager.

REST API Contact OpenAir Customer Support.

REST API definition

(OpenAPI 3.0 / JSON)

Account administrators and employees with the Export data role permission can access the

REST API reference documentation in OpenAPI 3.0 JSON format.

To access the generated API reference documentation, including resource and method

references specific to your account, go to Administration > Global Settings > Account >

Integration: Import/Export and click REST API documentation under Account data. For more

information, see Generated API Documentation JSON.

Step 2 — Read the Relevant Documentation

This guide provides a reference for using the REST API. The guide is organized around the following

conceptual topics for ease of reference:

■

Supported Resources, Methods and API Features — Get a quick overview of what you can do using the

API.

■

REST API Known Limitations — Review the list of features that are only partially supported or not

currently supported.

■

Authentication — Ensure each API request must have the relevant authorization.

■

OAuth 2.0 Authorization — Register client applications so they can use the OAuth 2.0 authorization

code flow to access your OpenAir account.

■

Request Format — Review how to form your API requests.

■

Response Format — Get an overview of the information returned in the API responses.

■

Returned Data — Review what to expect in the data returned and how to include only what you need

in the response data.

■

Attribute Naming Convention, Data Types and Formats — Review the naming convention for resource

attributes (fields), and the data types and formats used.

■

Custom Fields — Review special considerations concerning custom fields defined for your OpenAir

account.

■

Active Filter Set — Specify the filter set to be applied to your requests.

REST API

Step 3 — Register an API Integration Application 5

■

Filtering — Build query expressions to retrieve the resources matching your search criteria.

■

Pagination — Control the volume of data returned in the response and how to navigate multiple

pages of data.

■

Sorting — Sort a returned list of objects in ascending or descending order.

■

Referenced Objects and Expansion — Expand object referenced by ID in the main response payload.

■

Errors — Review possible API errors to handle errors programmatically in your client applications.

■

API Limits — Review the API limits set for your OpenAir account.

■

Web Services Logs — Access log reports to audit API requests for your account, and troubleshoot your

integrations.

■

Generated API Documentation JSON — Access a generated reference document in OpenAPI 3.0 JSON

format. The generated documentation includes account specific information such as custom fields.

This guide also include descriptions for each endpoints and methods for reference — See REST API

Endpoint Reference. For account specific reference documentation, use Generated API Documentation

JSON.

The business logic configured for your account may impact API requests and responses. Make sure you

consult the relevant documentation, for information about OpenAir business rules. For example:

■

For a description of account global and application settings and access control mechanisms, see

Administrator Guide and Security.

■

For a description of optional features that may impact behavior, see Optional Features.

■

For a description of user scripting, see User Scripting.

■

For reference documentation about the OpenAir database, see Database and the OpenAir Data

Dictionary.

Note: Unless you are viewing this help topic in the OpenAir Help Center, links to the data

dictionary use the generic OpenAir domain for production accounts (app.openair.com). In

some instances, you may need to replace the generic domain name with your account-specific

domain name in the link URLs.

□

To view the OpenAir Data Dictionary, use the following URL:

https://<account-domain>/database/single_user.html, where <account-domain> is the

account-specific domain for your account.

□

To view the details of a specific table, append a hash symbol # followed by the table name to

the end of the data dictionary URL.

For example, use https://<account-domain>/database/single_user.html#project to view

the details of the Project table.

For more information about your account-specific domain name, see the help topic Your

OpenAir Account URLs.

Step 3 — Register an API Integration Application

The REST API supports OAuth 2.0 exclusively for authentication and authorization. An account

administrator must register an application in OpenAir and enable it before you can use the REST API.

REST API

Step 4 — Test and Familiarize Yourself With the REST API on a Sandbox Account 6

To register an application, go to Application > Global settings > API integration Applications and click

Add new app. Note the client ID, client secret and redirect URI for the application. You will need this

information to get the user’s permission and to obtain an access token. For more information, see OAuth

2.0 Authorization.

Step 4 — Test and Familiarize Yourself With the

REST API on a Sandbox Account

Important: The REST API was introduced in the October 10, 2020 OpenAir release. It is an

initial version with a limited scope and functionality. Some OpenAir business logic may not be fully

supported. Review the list of features that are only partially supported or not currently supported

— see REST API Known Limitations. As with any other API or platform features, it is crucial that you

test integration applications leveraging the REST API extensively on a Sandbox account. Make sure

your integration applications run smoothly without error on a non-production account before you

implement it on your production account.

You can use a GUI REST client to test and familiarize yourself with the REST API. A GUI REST client lets you:

■

Execute HTTP requests from a user-friendly interface instead of using a command-line utility such as

cURL.

■

Save your requests and other important information and reuse them again later.

■

Get a new access token using the built-in GUI REST client functionality.

■

Enter request information more easily and in the right format ( headers, query parameters).

■

See the response in a prettified JSON view or a raw format.

This guide includes some guidelines working with the Postman desktop application to test the REST API.

See Testing the REST API Using Postman.

REST API

Supported Resources, Methods and API Features 7

Supported Resources, Methods and API

Features

The current scope of the REST API is limited to selected OpenAir modules and entities.

The following table summarizes the methods available for supported resources. For more information

about the endpoints and methods, see REST API Endpoint Reference.

Resources

POST GET PUT DELETE OPTIONS

Attachments

(Use the endpoints and

methods specific to the

object the attachments are

associated with)

—

Contacts

Expense reports

Job codes

Projects

Project milestones —

(objects with Task

classification set

to “Milestone” only)

— — —

Project phases —

(objects with Task

classification set

to “Phase” only)

— — —

Project tasks

(objects with Task

classification

set to “Task” only)

(objects with Task

classification

set to “Task” only)

— — —

Receipts

Time entries —

The following table summarizes the API features available for supported resources. It includes two

columns for the Expansion feature to show the resource endpoints for which the feature is available, and

the referenced objects that can be expanded.

■

For more information about the Filtering feature, see Filtering.

■

For more information about the Pagination feature, see Pagination.

■

For more information about the Sorting feature, see Sorting.

■

For more information about the Expansion feature, see Referenced Objects and Expansion.

REST API

Supported Resources, Methods and API Features 8

Resources Filtering Pagination Sorting Expansion

(Endpoints)

Expansion

(Referenced Objects)

Attachments

(Use the endpoints and

methods specific to the

object the attachments are

associated with)

— —

Contacts — —

Expense reports —

Job codes — —

Projects —

Project milestones —

Project phases —

Project tasks —

Receipts —

Time entries —

Users (display name only) — — — —

Workspaces — — — —

REST API

REST API Known Limitations 9

REST API Known Limitations

The following table lists features and configuration settings that are only partially supported or not

currently supported. The “Feature or Setting Type” column indicates whether it is a standard OpenAir

feature, an API feature, an Application setting, Global setting, User setting or Role permission controlled

by account administrators, or an optional feature controlled by OpenAir Customer Support and

documented in Optional Features. Other limitations specific to your account configuration may apply.

Feature / Setting Feature or

Setting Type

Partially / Not

Supported

Notes

User proxy Standard Not currently

supported



UTF-8



Partially

supported

The REST API largely supports both Latin1 and

UTF-8 encoded characters in the response.

There are some known issues for specific

cases.

Approval actions (Submit,

Approve, Reject, Unapprove)

Standard Not currently

supported



Bulk actions Standard Partially

supported

The ability to create, update, or delete

multiple resources in the same collection is

only supported for projects. Deleting multiple

attachments is also supported.

Form messages set in form

permissions and form rules.

Standard Not currently

supported

See Form permissions form in OpenAir

Repeat receipt Standard Not currently

supported

See Receipt entity properties form in OpenAir.

Selection from sorted

dropdown list of available values

Standard Not currently

supported

See Receipt entity properties form in OpenAir.

Sorting Standard Not currently

supported

The ability to specify a sort order for the list

of resources returned in the response is not

currently supported.

Upsert operation using an

external ID parameter

REST API Not currently

supported

This method is not currently supported. The

upsert operation would enable you to create a

record or update an existing record, using an

external ID as a parameter. It would be useful

for synchronizing data between OpenAir and

an external system.

Hide the "Expense type

location" field on receipts

Application Partially

supported

Administration > Application Settings >

Expenses > other Settings.

In some circumstances, the REST API accepts

values for the hidden "Expense type location"

field if the new value is the same as the

existing value or the value set automatically by

OpenAir.

Hide the "Reimbursable/Non-

reimbursable" drop-down on

receipts

Application Partially

supported

Administration > Application Settings >

Expenses > other Settings.

In some circumstances, the REST API accepts

values for the hidden "Reimbursable/Non-

reimbursable" field if the new value is the

REST API

REST API Known Limitations 10

Feature / Setting Feature or

Setting Type

Partially / Not

Supported

Notes

same as the existing value or the value set

automatically by OpenAir.

Foreign currency receipt

markup (%)

Application Not currently

supported

Administration > Application Settings >

Expenses > other Settings.

Minimum amount required to

submit an envelope

Application Not currently

supported

Administration > Application Settings >

Expenses > other Settings.

Requires support for approval actions.

Enable line item rejection of

receipts

Application Not currently

supported

Administration > Application Settings >

Expenses > other Settings.

Requires support for approval actions.

Enable expense authorizations Application Not currently

supported

Administration > Application Settings >

Expenses > other Settings.

Hide the "Advanced required"

field on expense authorizations

Application Not currently

supported

Administration > Application Settings >

Expenses > other Settings.

Allow an approver to edit

a submitted expense

authorization

Application Not currently

supported

Administration > Application Settings >

Expenses > other Settings.

Requires support for approval actions.

Show the phase name on task

drop-downs and pickers

Global Not currently

supported

Administration > Global settings > Account >

Optional features.

Requires support for selection from

dropdown list of available values

Custom Field Allocation

Worksheets

Optional Partially

supported

Administration > Global Settings > Reports >

Enabled Features (Global).

The validation enforcing 100% total allocation

is not fully supported.

Adjust an Approved Expense

Report

Optional Not currently

supported

Administration > Global Settings > Reports >

Enabled Features (Expenses).

Suppress Email Notifications or

Add Addresses to Notifications

Optional Not currently

supported

Administration > Global Settings > Reports >

Enabled Features (Global).

Allow employee to delete

(individually or in bulk) open,

submitted or rejected envelopes

Role Not currently

supported

Administration > Global Settings > Users >

Roles > [Select a role].

Requires support for bulk actions

Allow the user to un-approve an

expense report

User Not currently

supported

Administration > Global Settings > Users >

Employees > [Select an employee].

Requires support for approval actions.

Allow the user to un-approve an

authorization

User Not currently

supported

Administration > Global Settings > Users >

Employees > [Select an employee].

Requires support for expense authorizations

and approval actions.

The user can un-export expense

reports

User Not currently

supported

Administration > Global Settings > Users >

Employees > [Select an employee].

REST API

REST API Known Limitations 11

Feature / Setting Feature or

Setting Type

Partially / Not

Supported

Notes

The user can mark expense

reports exported

User Not currently

supported

Administration > Global Settings > Users >

Employees > [Select an employee].

Setting associated with the OpenAir

Integration Manager add-on application.

REST API

Authentication 12

Authentication

The REST API supports authentication by OAuth 2.0 bearer token exclusively. You must send the OAuth

2.0 access token as a bearer token in the Authorization header for each request.

Integration applications must be registered in OpenAir to use the REST API to access OpenAir data, and

users must give the application explicit permission to access OpenAir on their behalf.

For more information about using the OAuth 2.0 authorization framework, see OAuth 2.0 Authorization.

Important: All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API

requests without authentication will also fail.

Example

The following request sends a bearer token in the Authorization header.

GET /rest/v1/rest/v1/job-codes/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir.

Authentication Errors

Your client application needs to handle the following cases when the authentication may fail. The REST API

may return one of the errors listed in the following table if the authentication fails. The response includes

a HTTP Status and WWW-Authenticate header with information about the error.

HTTP Status WWW-Authenticate Header

Reason

400 Bad request error="invalid_request",

error_description="Invalid Bearer token

format"

The Authorization header sent in the request

must have the correct format for Bearer token

authentication. For example, a missing space

between “Bearer” and the token would cause a 400

Bad Request error.

401 Unauthorized error="insufficient_scope",

error_description="The access token is

invalid"

The bearer token sent in the request is not valid.

Possible reasons include:

■

Invalid scope — Tokens are issued for a specific

scope. The scope of the access token does not

allow access to the REST API.

401 Unauthorized error="invalid_token",

error_description="The access token is

invalid"

The bearer token sent in the request is not valid.

Possible reasons include:

■

Expired access token — Access tokens are

valid for the period specified in the application

configuration in OpenAir.

■

Authorization revoked — Users can revoke an

application at any time.

REST API

Authentication Errors 13

HTTP Status WWW-Authenticate Header

Reason

■

Disabled application — Account administrators

can disable an application at any time.

■

Application removed — Account administrators

can remove an application at any time.

■

Access not allowed for the client IP address

— The IP Restriction feature is enabled for the

OpenAir account and the client IP address is not

in the allowlist for the user associated with the

bearer token.

REST API

OAuth 2.0 Authorization 14

OAuth 2.0 Authorization

OpenAir supports OAuth 2.0, a robust authorization framework. This authorization framework enables

client applications to use a token to access OpenAir through the XML API, SOAP API, or REST API. The

application accesses the protected resources on behalf of a user who gave an explicit permission for the

access. This method eliminates the need for API integrations to store user credentials.

This feature is available if API Access is enabled for your account. It includes the following elements:

■

Administrators can register up to 20 integration applications with OpenAir and enable or disable

these applications in the Administration module. For more information, see Managing API Integration

Applications.

■

Administrators can use web services reports to audit and revoke authorizations granted by OpenAir

users to integration applications. For more information, see Auditing and Managing OAuth 2.0

Authorizations.

■

Application Developers can use the OAuth 2.0 authorization code flow to get an access token

then use the access token to access your OpenAir data using the XML API or SOAP API. For more

information, see OAuth 2.0 for Integration Applications Developers.

Note: OpenAir only supports the OAuth 2.0 authorization code grant type.

■

End-users can give applications explicit permission to access OpenAir on their behalf and they can

revoke this permission at any time. For more information, see Authorizing Applications to Access

OpenAir on Your Behalf.

Note: The first time a registered application attempts to access OpenAir on their behalf,

users must sign in using the same trusted sign-in page they normally use to sign in to OpenAir

then give the application explicit permission. The OAuth 2.0 feature supports the following user

authentication mechanisms:

□

Password authentication by OpenAir — Users enter their Company ID, User ID and

Password on the OpenAir sign-in page.

□

SAML authentication:

▬

Service Provider initiated Single Sign-on — Users enter their sign-in details on your

company Single Sign-on form.

▬

Identity Provider initiated Single Sign-on — Users must sign in using their Identity

Provider Single Sign-on form before the application attempts to access OpenAir on

their behalf. When the application attempts to access OpenAir, the authorization screen

appears automatically. Users do not need to enter their sign-in details again if the Single

Sign-on session has not expired.

Managing API Integration Applications

Integration applications using OAuth 2.0 to obtain access to your OpenAir data must be registered

and enabled by an account administrator. To register and manage your integration applications, go to

Administration > Global Settings > Account > API Integration Applications.

REST API

Managing API Integration Applications 15

Note: API Access must be enabled for your account to connect tools and services to OpenAir

using the API. The API Integration Application page is not available if API Access is not enabled. To

enable API Access for your account, contact OpenAir Customer Support or your OpenAir account

manager.

All your registered applications are listed in a grid. Details include the name of the application and

the date and time when it was last updated.

To register a new application, click ADD NEW APP. This button is disabled if you reach the limit of

20 registered applications. See Adding a New Application.

To enable or disable an application, click ENABLE or DISABLE in the top right corner of the

corresponding box. See Enabling, Disabling, or Removing Registered Applications

To edit an application configuration, click the edit icon in the bottom right corner of the

corresponding box. See Application Configuration.

To remove an application configuration from the list of registered applications, click the delete

icon in the bottom right corner of the corresponding box. See Enabling, Disabling, or

Removing Registered Applications.

To select one or more applications, check the box next to each application you want to select.

You can only select multiple applications if they are either all enabled, or all disabled. You can

then enable, disable or remove the selected applications. See Enabling, Disabling, or Removing

Registered Applications.

REST API

Managing API Integration Applications 16

Note: All times are given as Eastern Standard Time (EST).

Adding a New Application

You can register up to 20 applications. Each application needs a Client ID and Client Secret to obtain

access to OpenAir using OAuth 2.0. The Client ID and Client Secret are generated by OpenAir as part of

the registration process and are unique to each application.

REST API

Managing API Integration Applications 17

Important: The Client Secret is a private key the application uses to request an authorization

code from OpenAir. It should not be shared or stored in public code repositories.

The Client Secret is displayed only one time. You will not be able to retrieve it after you close the

Application Credentials dialog.

If you misplace the Client Secret, you can edit the application configuration and generate a new

Client Secret for the application.

To register a new application with OpenAir:

Do one of the following:

■

Go to Administration > Global settings > Account > API Integration Applications, and click ADD

NEW APP.

■

From any page in OpenAir, click the Create button and click API integration application.

The Add New Application popup window appears.

Enter the following information:

■

Application name (Required) — Enter a display name for your application in OpenAir. The

name must be unique to the application. You will not be able to use a name already used by

another registered application.

■

Description — Enter a few sentences to tell your employees what the application and how

it will help them. Your employees will use this information to decide whether they allow this

application to access OpenAir on their behalf.

■

Redirect URI (Required) — Enter a link users should be redirected to after granting or denying

the application permission to access OpenAir on their behalf.

REST API

Managing API Integration Applications 18

Important: Client applications use the redirect URI when requesting access to

OpenAir. Ensure you enter the redirect URI supplied by the application developers.

Click Save. The Application Credentials popup window appears.

Copy the Client Secret and store it in a safe place. The Client Secret is displayed only one time. You

will not be able to retrieve it after you close this window.

REST API

Managing API Integration Applications 19

Check the box to confirm you have copied and stored the Client Secret in a safe place then Click

Close.

Enabling, Disabling, or Removing Registered Applications

You must enable an application to allow this application to obtain access to OpenAir using OAuth 2.0.

You can disable an application to prevent this application from obtaining access to OpenAir using OAuth

2.0. If you disable an application, OpenAir automatically revokes all permissions given by users for the

application to access OpenAir on their behalf. Employees will not be able to use the disabled application.

You can remove a disabled application from the list of registered applications. All permissions,

authorizations and application credentials associated with the application configuration will be deleted.

This action cannot be undone.

To enable or disable a registered application:

Go to Administration > Global settings > Account > API Integration Applications.

Click ENABLE or DISABLE in the top right corner of the corresponding box. A confirmation popup

window appears.

Click ENABLE or DISABLE to enable or disable the application. Click Cancel to cancel the operation

and return to the API Integration Applications page.

REST API

Managing API Integration Applications 20

To remove a registered application:

Go to Administration > Global settings > Account > API Integration Applications.

Click the delete icon in the bottom right corner of the corresponding box. A confirmation popup

window appears.

Click REMOVE to remove the application. Click Cancel to cancel the operation and return to the API

Integration Applications page.

To enable, disable, or remove multiple applications at the same time:

Go to Administration > Global settings > Account > API Integration Applications.

Check the box for each application you want to enable, disable, or remove. Notice that you can only

select multiple applications if they are either all enabled, or all disabled. After you select the first

application, the application that are not available for selection appear in light gray color. Notice

also that some of the buttons in the top right corner of the list of registered applications become

available and change from light gray color to dark gray or green.

Click ENABLE, DISABLE, or REMOVE to perform the corresponding action on all selected

applications. A confirmation popup window appears. Click ENABLE, DISABLE, or REMOVE to

confirm. Click Cancel to cancel the operation and return to the API Integration Applications page.

Application Configuration

You can view the configuration details of your registered applications, including their unique Client ID

from the Application Configuration form. You can change the application name, description or Redirect

URI or generate a new Client Secret for the application.

To open the Application Configuration page for a registered application, go to Administration > Global

Settings > Account > API Integration Applications and click the edit icon in the bottom right corner of

the corresponding box.

The General section of the form lists the main application detail:

■

You can change the Application name, Description and Redirect URI.

Important: Client applications use the redirect URI when requesting access to

OpenAir. Ensure you enter the redirect URI supplied by the application developers. If

you need to change the redirect URI, disable the application, change the redirect URI

and enable the application again.

■

You can view when the application was registered under Created.

REST API

Managing API Integration Applications 21

Note: All times are given as Eastern Standard Time (EST).

You can view the Client ID — the unique identifier a client application needs to send to OpenAir

along with a client secret as part of the OAuth 2.0 authorization code flow.

Use the Tokens Lifetime section to configure the validity period of the access and refresh tokens:

■

Access token lifetime — Select the expiration time of access tokens. Available values go from

5 to 60 minutes in 5–minute increments. The default access token lifetime is 15 minutes.

Note: The validity period of access tokens cannot be greater than the session timeout

set for your account. If the Access token lifetime value is greater than the session

timeout value, the session timeout value is used for the access token validity period.

The application configuration form shows the current values for the session timeout

and access token validity period for reference.

To change the session timeout value , go to Administration > Global settings > Account

> Security.

■

Refresh token lifetime — Select the expiration time of refresh tokens. Available values go

from 1 to 31 days in one–day increments. The default access token lifetime is 1 day.

Note: Before the OpenAir 2021.2 release, you could set the refresh token lifetime to

values from 1 to 24 hours in one–hour increments. Values for the refresh token lifetime

set before the OpenAir 2021.2 release show in days (decimal values) instead of hours

As part of the OAuth 2.0 authorization code flow, authorized applications need to exchange an

authorization code for an access token and refresh token to obtain access to OpenAir. The access

token has a short expiration time. When the access token expires, the client application can use

the refresh token to obtain a new access token without user interaction until the refresh token

expires or the authorization is revoked.

Note: Access tokens normally remain valid for their entire lifetime. However, the access

token becomes invalid before it is due to expire if any of the OpenAir business rules

have changed and the access token is refreshed. Business rule changes may include any

changes to your company's OpenAir account configuration, or to the access privileges or

role permissions of the employee who authorized the client application.

Each refresh token can be used one time only. Refresh in an access token generates a new

access token and a new refresh token.

To generate a new Client Secret, click Regenerate Secret — You may need to generate a new

client secret if you misplace or delete the client secret accidentally or if your client secret becomes

compromised.

The new client secret will be valid immediately. The old client secret will continue to be valid for 24

hours after you generate a new one. This allows time to update any enabled application with the

new client secret.

If you made any changes to the configuration details in the General section, the Save button is

enabled. Click Save to save changes and return to the API Integration Applications page or click

Cancel to close the configuration form without saving.

REST API

Managing API Integration Applications 22

Auditing and Managing OAuth 2.0 Authorizations

Account administrators can use web services reports to audit and revoke authorizations granted by

OpenAir users to integration applications utilizing OAuth 2.0 to connect to OpenAir data.

■

API integration application authorization logs — User authorizations granted to custom or third

party applications registered with your OpenAir account in Administration > Account > API integration

applications.

■

OpenAir add-on service authorization logs — User authorizations granted to OpenAir add-on

services (OpenAir Mobile and other add-on service applications).

REST API

Auditing and Managing OAuth 2.0 Authorizations 23

The reports include information about which integration applications were authorized, when, and

by which users. The reports also include a link to revoke the authorization given for an integration

application by a user.

To access the OAuth 2.0 authorizations logs (if the Report Management feature is

enabled):

In OpenAir, go to Reports > Management.

Enter “web services” in the Search saved reports by name box. The Report Management UI

shows the list of web-services tabular reports.

Click the report name, then click New to create a new report.

Add columns and define filters as required.

(Optional) Click Untitled in the top bar and enter a name for your report.

(Optional) Click Save to save the report you created for later use. The Report Management UI will

list the report under on Saved reports tab.

Click Run to run the report.

To access the OAuth 2.0 authorizations logs (if the Report Management feature is

not enabled):

In OpenAir, go to Reports > Detail.

Click the report name under the Web services heading. The report options form appears.

(Optional) Set a date range for the Authorization granted filter. Defaults to All.

Click Report layout and select the columns to include, or keep the default layout.

(Optional) Click Employee and select the employees to include in the report.

REST API

Auditing and Managing OAuth 2.0 Authorizations 24

(Optional) Click API integration application and select the applications to include in the report.

(Optional) Check the Save this report as box and enter a name for the report

(Optional) Click Save to save the report. The report will be accessible in Reports > Saved reports.

Click Run to run the report.

OAuth 2.0 for Integration Applications Developers

OpenAir supports two methods to access OpenAir data using XML API or SOAP API requests:

■

Using user credentials (Company ID, User ID, password) and, in the case of SOAP web services (SOAP

API), a session ID.

■

Using OAuth 2.0 access tokens.

OAuth 2.0 bearer token authentication is the only supported method to access OpenAir data using the

REST API.

In the OAuth 2.0 scenario, client applications use one of the OAuth 2.0 grant types to get an access token

after the user authorizes the application. The user’s identity is verified by an authentication service, which

issues the access token. The access token can then be used to gain authenticated access to OpenAir

through the XMl API, SOAP API or REST API.

This section describes how to get an access token using the OAuth 2.0 authorization code grant type in

your applications, and how to use the access token in your API calls.

Note: OpenAir only supports the OAuth 2.0 authorization code grant type, which defines a

particular workflow client applications can use to obtain the access token.

OAuth 2.0 Authorization Code Flow

Application developers can use the OAuth 2.0 redirection-based authorization code grant type to

obtain an access token. This method eliminates the need for client applications to collect and store user

credentials.

The authorization code flow includes the following steps:

Getting the user’s explicit permission to access OpenAir on their behalf. See Getting the User’s

Permission.

The client application opens a browser and directs the user to the OpenAir identity

authentication service with the necessary URL query string parameters.

The user enters user credentials in the OpenAir sign-in page or in a third-party identity

provider Single Sign-on form . The authenticated user is then prompted to authorize the

application’s access request.

Receiving the authorization code — OpenAir issues an authorization code. The user is

redirected back to the client application with the authorization code in the query string. See

Receiving the Authorization Code.

Exchanging the authorization code for an access token — The client application must

exchange the authorization code for an access token and a refresh token. See Exchanging the

Authorization Code for an Access Token.

An additional step — Refreshing an access token — is required to get a new access token after the

previously issued access token has expired. See Refreshing an Access Token.

REST API

OAuth 2.0 for Integration Applications Developers 25

Note: You must send a request to one of the OAuth 2.0 endpoints for each of these steps. For

information about OAuth 2.0 URLs, see OAuth 2.0 Endpoints URL Schema and Account-Specific

URLs.

You can then use OAuth 2.0 token based authentication for your API calls. See Using OAuth 2.0 Access

Tokens in Your API Requests.

OAuth 2.0 Endpoints URL Schema and Account-Specific URLs

For each step of the OAuth 2.0 authorization code flow, you must send requests to the authorization

server using URLs specific to each type of request.

The following URL shows how you construct a request URL:

https://<account-domain>/login/oauth2/v1/<endpoint><query-string>

■

The first part of the URL must include your account-specific domain <account-domain> and the service

path for OAuth 2.0. For more information about your account-specific domain name, see the help

topic Your OpenAir Account URLs.

■

The second part of the URL depends on the endpoint you want to access

Description

authorize Use the authorization endpoint to get the user’s explicit permission and receive an

authorization code in response if the user authorizes the app to access OpenAir on their

behalf. The request URL includes a query string with request parameter.

https://<account-domain>/login/oauth2/v1/authorize?<query-string>

See Getting the User’s Permission and Receiving the Authorization Code.

token Use the token endpoint to exchange the authorization code for an access token or to refresh

an access token. Request parameters are passed in the request headers and body.

REST API

OAuth 2.0 for Integration Applications Developers 26

Description

https://<account-domain>/login/oauth2/v1/token

See Exchanging the Authorization Code for an Access Token and Refreshing an Access Token.

Getting the User’s Permission

To begin the OAuth 2.0 authorization code flow, the client application must direct the user to the

authorization server — OpenAir — using a GET request.

Send a GET request to the authorization endpoint using a URL like the following example:

https://company-id.app.openair.com/login/oauth2/v1/authorize?

response_type=code&redirect_uri=https://example-app.com/

redirect&client_id=174_h1FiXfWsJtLJG0DG&scope=xml+soap+rest&state=ryjp37y2qa28hdseck1gat

The GET request URL includes the authorization endpoint for the OpenAir account followed by a query

string: https://<account-domain>/login/oauth2/v1/authorize?<query-string>.

The request parameters are described in the following table.

Request parameter Description

response_type The value of the response_type parameter is always code. It tells the authorization server

that the client application is initiating the OAuth 2.0 authorization code flow.

redirect_uri The valid redirect URI where the application will process the authorization code. The

user should be redirected to this URI after allowing or denying the access request. The

redirect URI must match the redirect URI specified on the application configuration form

in OpenAir.

client_id The public identifier for the client application. The Client ID is generated by OpenAir when

an administrator registers the client application.

scope One or more plus-separated scope values indicating the access requested by the

application. The scope determines which component API the application will be able to

access.

■

OpenAir currently supports the following scope values: xml, soap, rest.

■

OpenAir accepts multiple scope values. The scope values are case insensitive.

■

Authorized applications have the same permissions and data access privileges as the

user authorizing the application within the selected scope.

state A random string generated by the client application, which is used to prevent cross-site

request forgery (CSRF) attacks. For more information see the OAuth 2.0 specification

RFC6749 Section 10.12.

After the application sends the GET request, OpenAir redirects the user to the OpenAir sign-in page.

OpenAir may redirect the user to a third-party Identity provider Single Sign-on form, if SAML SSO is

enabled for the account and the user. After successful authentication, OpenAir displays an authorization

screen prompting the user to approve the application’s access request.

Receiving the Authorization Code

After obtaining the user’s explicit permission, OpenAir initiates a redirect to the redirect URI specified in

the GET request with the authorization code and the state as query parameters.

REST API

OAuth 2.0 for Integration Applications Developers 27

The redirect query parameters are described in the following table.

Redirect parameter Description

state The client application should check that the state in the redirect matches the state set in the

GET request initiating the OAuth 2.0 authorization code flow. Validating the state sent to and

returned from the authorization server can be used to prevent cross-site request forgery

(CSRF) attacks.

code The authorization code issued by OpenAir.

■

It is a unique single use code issued only for the client application requesting access.

■

The authorization code is valid for 10 minutes. The client application must exchange the

authorization code for an access token before the authorization expires.

The following sample redirects illustrate successful and unsuccessful authorization.

■

Application successfully authorized.

https://example-app.com/redirect?

state=ryjp37y2qa28hdseck1gat&code=JTlQ43UvYDKbhI_SpEWsIE_bTpbou2-

kYeeLtKiMuR1iqZ3W3roqM4rmRC8fFCOJtBI6a85AnJPefx2szW9g4jCY

■

Application not authorized.

https://example-app.com/redirect?error_description=The+resource+owner+or+authorization+server

+denied+the+request&error=access_denied&state=ryjp37y2qa28hdseck1gat

Exchanging the Authorization Code for an Access Token

The application can use the authorization code to obtain an access token and a refresh token using a

POST request.

Send a POST request to the token endpoint.

■

The POST request URL is https://<account-domain>/login/oauth2/v1/token

■

The request must include the client ID and the client secret in the HTTP authorization request header.

□

The client authentication method used in a header of the request follows the HTTP Basic

authentication scheme. For more information, see RFC 7617.

□

The format is client_id:clientsecret.

□

The string value is Base64 encoded.

■

The request must include the parameters grant_type, code and redirect_uri in the request body.

□

Request parameters must be encoded based on the HTML specification for application/x-www-

form-urlencoded media type. For more information, see URL Specification 5.1.

The request parameters are described in the following table.

Request parameter Description

grant_type The value of the grant_type parameter is authorization_code. It tells the token endpoint

that the client application is using the OAuth 2.0 authorization code grant type.

code The authorization code issued by OpenAir and received by the client application in the

redirect.

redirect_uri The valid redirect URI. The redirect URI must match the redirect URI specified on the

application configuration form in OpenAir and when requesting the authorization code.

REST API

OAuth 2.0 for Integration Applications Developers 28

Request parameter Description

client_id The public identifier for the client application. The Client ID is generated by OpenAir when

an administrator registers the client application.

client_secret The client secret for the application. This ensures that the request to get the access

token is made only from the application, and not from a potential attacker that may have

intercepted the authorization code.

Example POST request:

POST /login/oauth2/v1/token HTTP/1.1

Host: company-id.app.openair.com

Authorization: Basic MTc0X2gxRmlYZldzSnRMSkcwREc6dmNGVGFORTNuVVhSdUoyOWpoRWxYU0g3THBYd2J4VEdkbUpIb1FNdm9fano0dmxkT0ZQSVRGSi1aRl

RvWVIyRzZnbmwwZHFYZWVpRlVJb0tuUkdTZlEK

Content-Type: application/x-www-form-urlencoded

code=JTlQ43UvYDKbhI_SpEWsIE_bTpbou2-kYeeLtKiMuR1iqZ3W3roqM4rmRC8fFCOJtBI6a85AnJPefx2szW9g4jCY&redirect_uri=https%3A%2F%2Fexam

ple-app.com%2Fredirect&grant_type=authorization_code

The token endpoint will verify all the parameters in the request to ensure that the authorization code is

valid and that the client ID and client secret match. If all the request headers and parameters are valid,

the token endpoint generates an access token and refresh token and includes them in the response.

The token endpoint returns the response as a JSON object with the properties described in the following

table.

JSON object properties Description

access_token The access token in JSON Web Token (JWT) format. The access token is valid for the

period configured in OpenAir for the application. See Application Configuration.

refresh_token The refresh token in JSON JWT format. The refresh token is valid for the period

configured in OpenAir for the application. See Application Configuration.

expires_in The access token expiration time in seconds. The access token is valid for the period

configured in OpenAir for the application. See Application Configuration.

type The value of the type property is always bearer. For more information, see the OAuth

2.0 specification — RFC 6750.

Example response (successful token request):

HTTP/1.1 200 OK

Content-Type: application/json

Cache-Control: no-store

Pragma: no-cache

{

"refresh_token":"WGxpeGNVTm1mNGhaS2E1djFQQ2twV1pKcWpOU0pXUkhZUU5oMTR1MFU5OUtLY3N1NkZKOG9SMHp4UnNuMjYyRTJGcm9NVUo5OWxEND

FzcW5WSDFsUEhoSF8xNzQ",

"expires_in":900,

"access_token":"eNNJ1GXD25-6IUylF6RZT33HqhoqSAAK53F0kxT62fBoKreDoc8Y_-Gnk2lUIqNbhwguHnxDtxUsJMY6NrDoiBnd",

"token_type":"bearer"

}

If the request fails, the token endpoint returns a JSON object with the error and error_descrtiption

properties. See Token Request Errors.

The client application can now use the access token to make API requests. This completes the

authorization flow.

The access token is only valid for a short period of time and within the scope it was issued for. The client

application will need to refresh the access token to continue making API requests after it expires.

REST API

OAuth 2.0 for Integration Applications Developers 29

Refreshing an Access Token

The access token has a short expiration time (15 minutes). When the access token expires, the client

application can use the refresh token to obtain a new access token using a POST request.

■

You can use the expiration time value (expires_in) to refresh access tokens before it is due to expire.

■

You can refresh access tokens if an API request returns an authentication failed error.

■

Each refresh token can be used one time only. Refresh in an access token generates a new access

token and a new refresh token.

Send a POST request to the OpenAir token endpoint. The POST request is similar to that used to

exchange an authorization code for an access token except it now uses the parameters set in the

following table.

Request parameter Description

grant_type The value of the grant_type parameter is refresh_token. It tells the token endpoint that

the client application is requesting to refresh an access token.

refresh_token A valid refresh_token. Refresh tokens are valid for the period configured in OpenAir for

the application. See Application Configuration.

scope (Optional) The requested scope must be within the scope the original access token was

issued for. If omitted, the new access token will be issued for the same scope as the

original access token.

redirect_uri The valid redirect URI.

client_id The public identifier for the client application.

client_secret The client secret for the application.

Example POST request:

POST /login/oauth2/v1/token HTTP/1.1

Host: company-id.app.openair.com

Authorization: Basic MTc0X2gxRmlYZldzSnRMSkcwREc6dmNGVGFORTNuVVhSdUoyOWpoRWxYU0g3THBYd2J4VEdkbUpIb1FNdm9fano0dmxkT0ZQSVRGSi1aRl

RvWVIyRzZnbmwwZHFYZWVpRlVJb0tuUkdTZlEK

Content-Type: application/x-www-form-urlencoded

refresh_token=WGxpeGNVTm1mNGhaS2E1djFQQ2twV1pKcWpOU0pXUkhZUU5oMTR1MFU5OUtLY3N1NkZKOG9SMHp4UnNuMjYyRTJGcm9NVUo5OWxENDFzcW5WSDFsUE

hoSF8xNzQ&redirect_uri=https%3A%2F%2Fexample-app.com%2Fredirect&grant_type=refresh_token

The token endpoint will verify all the parameters in the request to ensure that the refresh token is valid

and that the client ID and client secret match. If all the request headers and parameters are valid, the

token endpoint generates an access token and refresh token and includes them in the response.

The token endpoint returns the response as a JSON object with the properties described in the following

table. The response includes both a new access token and a new refresh token.

JSON object properties Description

access_token The access token in JSON Web Token (JWT) format. The access token is valid for the

period configured in OpenAir for the application. See Application Configuration.

refresh_token The refresh token in JSON JWT format. The refresh token is valid for the period

configured in OpenAir for the application. See Application Configuration.

expires_in The access token expiration time in seconds. The access token is valid for the period

configured in OpenAir for the application. See Application Configuration.

type The value of the type property is always bearer. For more information, see the OAuth

2.0 specification — RFC 6750.

REST API

OAuth 2.0 for Integration Applications Developers 30

Note: Access tokens normally remain valid for their entire lifetime. However, the access token

becomes invalid before it is due to expire if there are any changes in the OpenAir configuration, or

in the access privileges or role permissions of the employee who authorized the client application,

and the application uses the access token is refreshed.

Example response (successful token request):

HTTP/1.1 200 OK

Content-Type: application/json

Cache-Control: no-store

Pragma: no-cache

{

"refresh_token":"N25RdE82N0FIMnBDRTQ1d3hITHN6dXRwQ3dNdzVHWHMydWd3WWFqUXMwMWgrcTB3UHBFQ3VLaUZQTlRuR0J3U09LaWcvWWJ2UHpPS2hWUUtx

QlJCMzBHVF8xNzQ",

"expires_in":900,

"access_token":"pWprqUHkgaOWai7fSjaNaN5ywpDr7a7W6hLiq-b1vBBAT48zxAPTyy-wpTNxyfwJieQzZ5E1HEOsG1hNtwJpILR5",

"token_type":"bearer"

}

If the request fails, the token endpoint returns a JSON object with the error and error_descrtiption

properties. See Token Request Errors.

Token Request Errors

Your client application needs to handle the following cases when the request to exchange an

authorization code for an access token or to refresh a token fails. The token endpoint may return one of

the errors listed in the following table if the token request fails.

■

Errors are listed in descending priority order. Only the first error is returned if there are more than

one.

■

Some of the errors are specific to one of the two possible types of request ( grant_type).

error error_description grant_type

Reason

unsupported_grant_type The authorization grant

type is not supported by

the authorization server



The grant_type must be

either authorization_code or

refresh_token.

invalid_request Authorization header not

sent



Request headers must include a

Basic Authorization header.

invalid_request No credentials provided



The Client Id and Client Secret

must be sent in the request

Authorization header.

access_denied Authorization code is not

valid

authorization_code The authorization code must be

valid. Possible reasons include:

■

Expired authorization code

— The authorization code is

valid for 10 minutes.

■

Authorization revoked

— Users can revoke an

application at any time.

■

Disabled application —

Account administrators can

disable an application at any

time.

■

Application removed —

Account administrators can

REST API

OAuth 2.0 for Integration Applications Developers 31

error error_description grant_type

Reason

remove an application at any

time.

invalid_request redirect_uri or client_id is

not valid

authorization_code The redirect URI and Client ID

must match the information

specified on the application

configuration form in OpenAir.

access_denied Refresh token is not valid refresh_token The refresh token sent in the

request is not valid. Possible

reasons include:

■

Expired refresh token —

Refresh tokens are valid for 24

hours.

■

Authorization revoked

— Users can revoke an

application at any time.

■

Disabled application —

Account administrators can

disable an application at any

time.

■

Application removed —

Account administrators can

remove an application at any

time.

invalid_scope Changing scopes is not

supported

refresh_token Tokens are issued for a specific

scope. The scope of the token

requested must be within the

scope of the token sent in the

request. For example, if the scope

of the original token includes both

xml and rest, the scope of the

access token requested can be

rest only.

access_denied Authorization failed



The Client Id and Client Secret

pair sent in the request is

not valid. Note that account

administrators may generate

a new Client Secret for the

application in OpenAir.

access_denied API access via OAuth2 is

disabled



API access is not enabled for the

OpenAir account.

REST API

OAuth 2.0 for Integration Applications Developers 32

Note: If applicable, the client application can initiate the OAuth 2.0 authorization code flow

again to obtain a new authorization code and exchange it for an access token. The end user will

be directed to the sign-in page and required to enter valid user credentials. If the user revoked

the application the authorization screen will appear. If the application is still authorized, the

authorization endpoint will return a new authorization code immediately after the successful user

authentication.

Using OAuth 2.0 Access Tokens in Your API Requests

You can use OAuth 2.0 access token authorization instead of password authentication or Session ID

in your API requests. The XML API, SOAP API and REST API support authorization using access tokens.

OAuth 2.0 access token authorization is the only supported authentication method with the REST API.

■

In your XML API requests, use the Auth XML command. See the help topic OAuth 2.0 Access Token

Authentication.

■

In your SOAP API requests, use the SessionHeader web services method complex type to hold the

access token. See the help topic Using SessionHeader for OAuth2.0 Token Based Authentication.

■

In your REST API requests, send the access token as a bearer token in the HTTP authorization header.

See Authentication.

Note: For REST API requests,the access token lifetime will either be the Access token

lifetime set on the application configuration form in OpenAir, or the Session timeout set in

Administration > Global settings > Account > Security options, whichever is the lower.

Note: Both the XML API and SOAP API continue to support password authentication. The SOAP

API continues to support SessionID.

Authorization Errors

API access must be enabled and API requests must use a valid access token with a valid scope.

■

The access token must exist.

■

The access token must not be expired.

■

The user who gave the application permission to access OpenAir must be active. The same access

token can be used if the user is set to active again.

■

The application must be enabled for the OpenAir account. The same access token can be used if the

application is disabled and then enabled again.

■

The access token must be used within the scope it was issued for. For example, if the authorization

code was obtained for the scope xml+rest , the client application cannot use the access token in a

SOAP API request.

The error code and message returned depend on the API:

■

The XML API returns error code 420 and message Authentication failed.

■

The SOAP API returns error code 9 and message Logged out.

■

The REST API returns HTTP status 401 Unauthorized and the response includes a WWW-Authenticate

header error="invalid_token", error_description="The access token is invalid".

An invalid OAuth 2.0 access token authorization has priority over a valid password authentication. You

cannot use password authentication (Company ID, User ID, password) — or a valid Session ID in the SOAP

session header — as a fallback for an invalid access token.

REST API

Authorizing Applications to Access OpenAir on Your Behalf 33

Authorizing Applications to Access OpenAir on Your

Behalf

Integration applications let you connect OpenAir with other applications and they extend what you can

do with OpenAir. Integration applications may use the OAuth 2.0 authorization protocol to gain access to

your company's OpenAir account.

The first time an application using the OAuth 2.0 protocol attempts to access OpenAir on your behalf, you

will need to give this application your explicit permission.

To authorize an application, you will typically use the following steps:

The application opens a browser and directs you to the same trusted sign-in page you normally

use to sign in to OpenAir — the OpenAir sign-in page or your company Single Sign-on form

appears.

Enter your sign-in details and click Log in.

An authorization page will appear indicating that the application <application name> would like to

access your OpenAir data.

Read the content of the authorization page attentively. It should describe what the application

does and how it will help you. It should also say what the application can do, for example:

■

The application will be able to access all data you have access to.

■

The application will be able to perform all actions permitted by your role and user privileges.

Important: For Administrators — Business rules configured for your company's

OpenAir account are applied when an integration application interacts with your OpenAir

data through the REST API. However, they are not applied when an integration application

interacts with your OpenAir data through the SOAP API or XML API — application

developers must enforce business rules within their integration application if required.

Business rules include OpenAir account configuration settings and access control

mechanisms, as well as any user scripts deployed on your company's OpenAir account.

Click ALLOW to authorize the application or click CANCEL if you do not want the application to

access OpenAir on your behalf.

Note: The steps may vary depending on the method you use to sign in to OpenAir:

■

If you normally enter your company ID, user ID and password on the OpenAir sign-in page, or

if you enter your company ID on the OpenAir sign-in page and then your password on your

company single sign-on page, the above steps apply.

■

If you normally need to enter all sign-in details on your company single sign-on page to access

OpenAir without going to the OpenAir sign-in page first (Identity Provider initiated Single Sign-

on), you must sign in and launch OpenAir before the application attempts to access OpenAir on

your behalf. The authorization page appears automatically. Follow steps 3 and 4 above. You do

not need to re-enter your sign-in details.

Integration applications are registered and managed by your account administrator. They need to be

enabled on your account before they can attempt to connect to OpenAir and request your permission.

REST API

Authorizing Applications to Access OpenAir on Your Behalf 34

Note: Integration applications are registered and managed by your account administrator. They

need to be enabled on your company's OpenAir account before they can attempt to connect to

OpenAir and request your permission.

Account administrators can disable an application at any time.

■

If you have authorized an application and this application is disabled by an administrator, the

application will no longer be able to interact with OpenAir.

■

If an administrator enables this application again, you will need to give this application your

explicit permission again before you can continue to work with it in connection with OpenAir.

After you authorize an application, it will be able to interact with OpenAir on your behalf until you revoke

the authorization.

To view the application you have authorized, go to User Menu > Personal Settings > Authorized

Applications. All your authorized applications are listed in a grid. Details include the name of the

application and the date and time when it was last updated.

Note: All times are given as Eastern Standard Time (EST).

To revoke an application, click REVOKE in the top right corner of the corresponding box, then click

REVOKE in the confirmation message. The application no longer shows in the authorized applications

REST API

Authorizing Applications to Access OpenAir on Your Behalf 35

list. If a revoked application attempts to access OpenAir on your behalf, you will be prompted to give this

application your explicit permission again.

REST API

Request Format 36

Request Format

This section describes how to format REST API requests. Each request includes the following parts:

■

Request Method

■

Request URL

■

Request Headers

■

Request Body (when creating or updating a record)

For example requests, see Examples.

Request Method

The REST API uses standard HTTP methods or verbs. The following table lists the CRUD operations you

can perform using the REST API. The table shows example URLs for each operation and whether the

method expects a request body.

For more information about methods supported for each resources, see Supported Resources, Methods

and API Features.

For more information about request URLs, see Request URL.

For more information about request bodies, see Request Body.

Operation HTTP Method Example Resource Endpoint Path Request Body

Create a record POST /expense-reports/ JSON object

Retrieve all records GET /expense-reports/ None

Retrieve the record with internal ID

= {id}

GET /expense-reports/{id} None

Update the record with internal ID

= {id}

PUT /expense-reports/{id} JSON object

Delete the record with internal ID =

{id}

DELETE /expense-reports/{id} None

Discover available methods and

fetch the endpoint reference

OPTIONS /expense-reports/ None

Request URL

You can access OpenAir resources through the REST API by using URLs specific to each resource, and

pass parameters in the query string to specify the information you need in the response.

REST API

Request URL 37

The request URL includes:

Base URL — The base URL includes your account-specific domain, with a unique account

identifier usually based on your Company ID, and the REST API service path.

Environment Base URL

Production https://<company-id>.app.openair.com/rest/v1

Sandbox https://<company-id>.app.sandbox.openair.com/rest/v1

Note: The base URL is typically sent in the Host header.

The examples in this document include the base URL for a production account in the Host

header, and use company-id as the unique account identifier. Substitute company-id with

your account identifier, which is typically based on your company ID.

Resource endpoint path

■

There is a predictable resource endpoint path for each entity supported.

Entity Path

Attachments /attachments/ NOT SUPPORTED — Use the endpoints specific to the object the

attachments are associated with)

Contacts /contacts/

Expense reports /expense-reports/

Job codes /job-codes/

Projects /projects/

/projects/bulk (bulk actions)

Project milestones /project-milestones/

Project phases /project-phases/

Project tasks /project-tasks/

Receipts /receipts/

Time entries /time-entries/

■

The path may also include URL parameters. For example:

□

{id} — The internal ID of the specific record you want to retrieve, update or delete.

■

The path may also include additional path segments in the following cases:

□

The core entity object can be a parent to other entity objects. For example, /expense-

reports/{id}/receipts/ points to the subcollection of receipts that have the expense

report with the specified internal ID as parent and /expense-reports/{id}/receipts/

{ticket_id} point to a specific receipt within that subcollection.

□

The path points to a subset of entity objects, for which different business logic may apply.

See Insert an Overlapping Expense Report (/expense-reports/overlapping/ endpoint path),

for example.

Query string — A query string may be used to specify what information you need in the

response, to specify the filter set to apply, or to use the pagination, filtering, and referenced object

expansion features.

REST API

Request Headers 38

Note: For more information about endpoints, methods and parameters available for each

supported resource collection, see REST API Endpoint Reference or consult the Generated API

Documentation JSON.

Request Headers

The request headers include:

■

Host — The base URL is typically sent in the Host header.

■

Authorization — Requests must include the OAuth 2.0 bearer token in the Authorization header. See

Authentication.

■

Content-Type — POST and PUT requests include a request body. Use this header to specify the type

of content. The REST API supports the following content types:

□

JSON ( application/json) — for all POST and PUT requests.

□

form-data ( multipart/form-data) — to insert a new attachment. See Add an Attachment to an

Expense Report and Add an Attachment to a Receipt

Request Body

POST requests must include a request body. The body can be either of the following:

■

A JSON-encoded string with the object to be created.

■

Form-data with the file to be uploaded, when adding a new attachment.

PUT requests must include a JSON-encoded request body with the key-value pairs for the fields to be

updated.

The following requirements apply to the JSON object in the request body:

■

For PUT and POST requests:

□

Only include valid attribute-value pairs, that is valid attributes and valid values in the correct data

type and format.

□

Not include read-only attributes. Hidden fields are read-only. The REST API returns an error if an

attribute-value pair for a hidden field is included in a POST or PUT request body.

■

For POST requests:

□

Include all required attributes.

For more information about valid, read-only and required attributes for each resource, see the resource

schema object in REST API Endpoint Reference, or consult the Generated API Documentation JSON.

Examples

The following examples demonstrate the request URL format.

GET request example

The following request retrieves a filtered and paginated list of expense reports. The request URL includes:

REST API

Examples 39

■

The resource endpoint /expense-reports

■

A query string which illustrates some of the available query parameters:

□

fields — to return the exact fields you need. See Response Data Modifiers.

□

filterSetId — to apply a specific filter set which determines what data the authenticated user has

access to and can view or update. The request will return only the objects that the authenticated

user has access to when the specified filter set is active in OpenAir. See Active Filter Set.

□

limit and offset — to delimit the number of objects returned in a page and identify the exact

page to return. See Pagination.

□

q — to return only the objects according to the filter criteria specified. See Filtering.

GET /rest/v1/expense-reports?fields=id,attachments&filterSetId=3&limit=10&offset=10&q=created BETWEEN ['2020-01-01','2020-06-30']

AND currency IS 'EUR' HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

PUT request example

The following request updates the receipt with the internal ID 3825. The request URL includes:

■

The resource endpoint /receipts/

■

The resource ID {id}

■

A query string which illustrates some of the available query parameters:

□

fields — to return the exact fields you need. See Response Data Modifiers.

□

filterSetId — to apply a specific filter set which determines what data the authenticated user has

access to and can view or update. The request will update the object only if the authenticated user

has access to that object when the specified filter set is active in OpenAir. See Active Filter Set.

□

return_object — to include the object updated in the response instead of returning only the

internal ID of the object updated. See Response Data Modifiers.

□

q — to return only the objects according to the filter criteria specified. See Filtering.

PUT /rest/v1/rest/v1/receipts/3825?fields=id,attachments&filterSetId=3&return_object=1 HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"cfCheckboxReceipts": true,

"date": "2020-06-30",

"currency": "USD",

"isTaxIncludedInCost": false,

"notes": "Receipt updated using OpenAir REST API"

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

REST API

Response Format 40

Response Format

The response returned includes the following parts:

■

HTTP Response Code — The REST API uses standard 3–digit HTTP response status codes. See Errors.

■

HTTP Response headers — All headers have the meanings defined by the HTTP specification. The

REST API returns a JSON-encoded response and response headers always include Content-Type:

application/json.

■

HTTP Response Body — The REST API returns the response as a JSON-encoded object. The JSON-

encoded may include the properties listed in the following table.

Property Description

message A string containing a brief message about the status of your request — e.g. “Success”.

data An array containing the actual response elements. See Returned Data.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, and links to other pages, if a list is returned and if the resource endpoint

supports pagination. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

errorFields An object returned if the request fails with a HTTP status code 400, listing fields with validation

errors. See Errors.

included An array contains expanded objects referenced by internal ID in the data array, and specified in the

request using the expand parameter. See Referenced Objects and Expansion.

REST API

Returned Data 41

Returned Data

The response object includes a data property for all successful POST, GET, PUT or DELETE requests. The

content of the data array depends on the method used in the request. By default, data contains:

■

A single object or up to 1000 objects, if you use a GET request to retrieve a single resource or a list

of resources. The object contains key-value pairs for all fields. For more information about fields

returned, see REST API Endpoint Reference or Generated API Documentation JSON.

■

The internal ID of the object created, updated, or deleted, if you use a POST, PUT or DELETE request to

insert, modify or delete a resource.

The response object includes a meta property for successful requests if the response is paginated, or if

there are objects referenced by internal ID in the data array that support expansion. See Pagination and

Referenced Objects and Expansion.

Response Data Modifiers

You can use the following query parameters to modify the default response data.

Parameter Description

fields A comma-separated list of attributes to include in the response. If not specified, the response

includes all attributes for each object returned. The comma-separated list may include spaces (or

%20 in the URL encoded string).

You can use the fields query parameter to return exactly the fields you need in the response.

Supported methods: POST, GET, PUT.

Note: The GET /contacts/ and GET /job-codes/ methods to retrieve a list of contacts

and job codes, respectively, do not currently support the fields parameter.

return_object If set to any value other than 0 (zero), the response will include the object created or updated in

the data array. You can use both the return_object and fields parameters to return exactly the

fields you need.

Otherwise, the response will include only the internal ID of the object created or updated in the

data array.

Supported methods: POST, PUT.

REST API

Attribute Naming Convention, Data Types and Formats 42

Attribute Naming Convention, Data Types

and Formats

Attribute names are case sensitive and use camelCase, a naming convention in which each word within

a compound word is capitalized except for the first word. Attribute names do not include dash and

underscore characters. For example, note the initial lowercase t and the uppercase L and I for the

taxLocationId ExpenseReport attribute, which corresponds to the tax_location_id field in the Envelope

table described in the OpenAir data dictionary, or tax_locationid in the oaEnvelope SOAP API complex

type and <Envelope> XML API data type.

The REST API uses data types and formats defined by the OpenAPI Specification (OAS). The OAS identifies

four primitive data types: Boolean, integer, number, and string. Primitive data types have an optional

modifier property: format. The REST API uses several known formats to define the data type used for each

attribute in the JSON-encoded requests and responses. In this guide and in the generated API reference

documentation, the following notation is used to indicate the data type and format: type($format).

The following tables shows the data types and formats used by the REST API:

type format Notation Description

Boolean



Boolean true / false

integer int64 integer($int64) long integer

number double number($double) double precision floating point number

number float number($float) single precision floating point number

string



string string of unicode code points

Note: Some OpenAir Accounts may be configured

to use UTF-8 character encoding instead of Latin1. The

REST API supports both Latin1 and UTF-8 encoded

characters in the response.

string date string($date) string using the date format YYYY-MM-DD, where YYYY is the four-

digit year, MM the two-digit month, and DD the two-digit day of the

month — Example: 2020–09–19

string date-time string($date-time) string using the date-time format YYYY-MM-DD hh:mm:ss, where hh

is the two-digit hours, mm the two-digit minutes, and ss the two-

digit seconds — Example: 2020–09–19 17:56:38

Note: This format is used for system-generated and

read-only fields. The format applies to the following

attributes in the data returned: created, updated, and

exported.

Note however that the date-time format is not

supported in query expressions used for Filtering.

REST API

Custom Fields 43

Custom Fields

The REST API supports custom fields associated with the supported resources or OpenAir entities.

■

Custom fields are queryable. See Filtering. However, review the current limitations — Custom Fields

Limitations in the REST API.

■

Attribute names for custom fields do not use the same naming convention as built-in fields. Custom

field attribute names are formed using the custom field name as set in OpenAir with the prefix cf. For

example, the attribute for a custom field with the name amex_transaction_number in OpenAir will be

cfamex_transaction_number.

The following table shows the data types and formats corresponding to each custom field type in

OpenAir:

Custom Field Type Data Type and Format

Check box Boolean

Numeric

■

integer($int64) if Decimal point is set to 0 (zero) on the custom fields properties

form

■

number($float) otherwise

Date string($date)

[All other custom field types] string

Custom Fields Limitations in the REST API

Review the following limitations:

■

Custom field types other than check box , numeric, and date are treated as string. The string value

may depend according to the custom field type. For example, tag custom field type values include an

HEX color code as well as the display text, multiple selection and pick list include all selected values in a

string but in no determined order.

■

Error message for custom dropdown fields do not support UTF-8 encoded dropdown values.

■

When using custom fields with the filtering feature. See also Filtering.

□

Custom field types other than check box , numeric, and date are treated as string. You can only

use the query operators available for the relevant data type and format string data types when

querying other custom field types.

□

Custom field types multiple selection and pick list are supported but may not be handled correctly.

Use the operators CONTAIN and CONTAIN_NOT with these custom field types and compare with a

valued including only one of the possible multiple selection or pick list field values.

REST API

Active Filter Set 44

Active Filter Set

You can specify the filter set you want to apply to your request by using the filterSetId query parameter.

The active filter set determines what data can be viewed or modified.

Note: In OpenAir, filter sets define what data the authenticated user has permission to view or

update. Each user has at least one filter set assigned — the primary filter set. If more than one

filter set are assigned to a user, that user can set an filter set as active to control the data available

in OpenAir. For more information, see Security.

The filterSetId is the internal ID of the filter set to be applied.

■

When specified, the request is successful only if the data is accessible when the specified filter set is

active in OpenAir. For example:

□

A GET request only returns an object if the object can be accessed when the specified filter set is

active.

□

A POST request only creates an object if all items associated with this object can be accessed when

the specified filter set is active.

□

A PUT request only updates an object if the object and all the updated object properties can be

accessed when the specified filter set is active.

□

A DELETE request only deletes an object if the object can be accessed when the specified filter set is

active.

■

Otherwise and by default, the primary filter set associated with the user who authorized the

application is applied.

Important: Review the following guidelines:

■

The filter set with the specified internal ID must exist and must be associated with the user

who authorized the application as per the access token.

■

If the request concerns multiple objects, the requests returns, creates, updates or deletes only

the objects that can be viewed or modified when the specified filter set is active. In the case

of POST, PUT, and DELETE requests, the REST API returns the HTTP response code 207 Multiple

statuses returned. See also Errors.

■

Filter sets may overlay with other access control features such as role permissions, and form

permissions, for example.

REST API

Filtering 45

Filtering

You can search the collection of resources by using the q query parameter to specify search criteria. If

you use the q parameter when retrieving a list of resources using the GET method, the response will only

include the objects matching the conditions specified in the request.

The query expression can include a single clause or combine several clauses.

■

Each clause includes a field name and a comparison operator — See Queryable Fields and

Comparison Operators.

■

Clauses may include one or more values — See Values in Query Clauses.

■

To combine clause, you can use logical operators and parenthesis ( ) — See Logical Operators and

Precedence.

Important: The query expression must be URL-encoded to be included as part of the URL

query string. The request will fail otherwise. The examples in this guide do not show URL-encoded

query expressions for ease of reading. For example, the query expression q=created BETWEEN

[‘2020-01-01’,’2020-06-30’] AND currency IS ‘EUR’ should be encoded to q=created%20BETWEEN

%20[%272020-01-01%27,%272020-06-30%27]%20AND%20currency%20IS%20%27EUR%27.

Please review the current limitations for this feature — See Limitations.

Queryable Fields

The field descriptions in the Generated API Documentation JSON or the REST API Endpoint Reference

indicate whether you can use the field in your query clauses. Look for the [Query allowed] mention in the

schema object field descriptions.

Comparison Operators

The comparison operators you can use depend on the field data type and format. The following table lists

the comparison operators available for each data type and format.

There are different classes of operators:

■

Unary operators operate on only one operand — the field name. A unary operator is typically used in

this format: fieldName OPERATOR

■

Binary operators operate on two operands — the field name and a value. A binary operator is typically

used in this format: fieldName OPERATOR value

■

Ternary operators operate on three operands — the field name and two values. A ternary operator is

typically used in this format: fieldName OPERATOR [value1,value2]

■

N-ary operators operate on N operands — the field name and one or more values. A ternary operator

is typically used in this format: fieldName OPERATOR [value1,value2,value3,...]

Data Type (Format) Query Operators Class Examples

[All data types and

formats]

EMPTY, EMPTY_NOT Unary description EMPTY

REST API

Values in Query Clauses 46

Data Type (Format) Query Operators Class Examples

Boolean IS, IS_NOT Binary isActive IS true

integer($int64)

number($double)

number($float)

EQUAL, EQUAL_NOT, GREATER,

GREATER_NOT, GREATER_OR_EQUAL,

GREATER_OR_EQUAL_NOT, LESS, LESS_NOT,

LESS_OR_EQUAL, LESS_OR_EQUAL_NOT,

Binary userId EQUAL 237

total LESS_OR_EQUAL 148.5

integer($int64)

number($double)

number($float)

BETWEEN, BETWEEN_NOT, WITHIN,

WITHIN_NOT

Ternary total BETWEEN [25,148.5]

integer($int64)

number($double)

number($float)

ANY_OF, ANY_OF_NOT N-ary userId ANY_OF [217, 237,

638,755,829]

string CONTAIN, CONTAIN_NOT, IS, IS_NOT,

START_WITH, START_WITH_NOT, END_WITH,

END_WITH_NOT

Binary description CONTAIN “meal”

string($date)

string($date-time)

AFTER, AFTER_NOT, BEFORE, BEFORE_NOT,

ON, ON_NOT, ON_OR_AFTER,

ON_OR_AFTER_NOT, ON_OR_BEFORE,

ON_OR_BEFORE_NOT

Binary accountingDate ON_OR_BEFORE

“2020–09–30”

string($date)

string($date-time)

BETWEEN, BETWEEN_NOT, Ternary created BETWEEN [“2020–01–01”,

“2020–06–30”]

Values in Query Clauses

Query clauses may include one or more values. Multiple values are The following table lists the accepted

value formats for each data type and format.

Data Type (Format) Value Format Examples

Boolean lowercase, Titlecase, or numeric Boolean values, with or without

single or double quotes

true, False, ‘true’,

“False”, 1, ‘0’, “1”

integer($int64)

number($double)

number($float)

numeric values, with or without single or double quotes 126.32, ‘126.32’,

“126.32”

string string values, with single or double quotes 'USD', “CAD”

string($date) string values using the date format YYYY-MM-DD, with single or

double quotes

'2020–09–19', “2020–09–

19”

REST API

Logical Operators and Precedence 47

Data Type (Format) Value Format Examples

string($date-time)

Note: The date-time format is not supported for

values in query expressions. Use the date format YYYY-

MM-DD in query clauses for the read-only fields created,

updated, and exported, even though values are returned

as string($date-time).

Logical Operators and Precedence

You can combine clauses in your query expression using the logical operators AND and OR. The operator

AND takes precedence over the operator OR. You can use parenthesis () to mark precedence in your query

expression.

Consider the example isAdjusting IS false AND (currency IS 'CAD' OR userId EQUAL 237) AND

accountingDate EMPTY — the request returns the objects meeting all the following criteria:

■

isAdjusting IS false — The expense report is not an adjusting expense report.

■

currency IS 'CAD' OR userId EQUAL 237 — Either the expense report currency is Canadian Dollars or

the internal ID for the Employee is 237.

■

accountingDate EMPTY — The accounting date is not set.

Limitations

The following limitations currently apply to the filtering feature:

■

The query expression passed using the q parameter in query string can be up to around 5500

characters long. Longer query strings return an invalid request error.

■

OpenAir custom field types other than Check box , Numeric, and Date are treated as string. You can

only use the query operators available for the relevant data type and format string data types when

querying other custom field types. See also Custom Fields.

■

OpenAir custom field types Multiple selection and Pick list may not be handled correctly with some

string query operators. Use the operators CONTAIN and CONTAIN_NOT with these custom field types. See

also Custom Fields.

REST API

Pagination 48

Pagination

Some resources support GET methods to retrieve a list of resources. The response may be returned in

one or more pages depending on the number of objects to be returned. For some resources, you can use

the limit and offset parameters to control the response pagination.

Parameters

Parameter Description Default

limit A limit on the length of the page. You can set the maximum number of objects to

be returned per page between 1 and 1000.

100

offset A cursor for use in pagination. The response will skip the number of matching

objects (or rows) specified using the offset parameter and return the page of

objects starting with the next object (or row) in the list. The offset must be a

positive number divisible by the page limit.

Response

A paginated response includes the meta property in the JSON-encoded object returned. For a paginated

response, the meta property has the following attributes:

Property Description

rowsPerPage The number of objects (or rows) per page.

totalPages The total number of pages in the list.

totalRows The total number of objects (or rows) in the list.

links An array of objects containing direct links to other pages and their relation to the page returned:

■

first — the URL for the first page. Not included if the page returned is the first page.

■

prev — the URL for the previous page. Not included if the page returned is the first page.

■

self — the URL for the current page (the page requested).

■

next — the URL for the next page. Not included if the page returned is the last page.

■

last — the URL for the last page. Not included if the page returned is the last page.

Example

The following example skips the first 90 objects and returns a page of 10 objects starting from the 91th

object in the list of results.

GET /rest/v1/receipts?limit=10&offset=90 HTTP/1.1

The response includes the meta attribute with information about the page ( rowsPerPage — the number of

objects per page), the list (totalPages and totalRows — the total number of pages and objects in the list,

respectively), and direct links to the first, previous, next and last page, as well as the requested page.

REST API

Example 49

{

"message" : "success",

"data" : [

{...}

"meta" : { "rowsPerPage": 10,

"totalPages": 85,

"totalRows": 841,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/receipts?limit=10"

{

"rel": "prev",

"href": "https://company-id.app.openair.com/rest/v1/receipts?limit=10&offset=80"

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/receipts?limit=10&offset=90"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/receipts?limit=10&offset=20"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/receipts?limit=10&offset=840"

}

]

}

REST API

Sorting 50

Sorting

You can use the orderBy parameter when retrieving a list of resources using the GET method to sort the

returned list by the specified attribute in ascending or descending order.

■

You can specify an ascending sort order or descending sort order using a + sign (ascending) or -

sign (descending) before the attribute name. An ascending sort order is used if the sort order is not

specified.

Examples:

□

GET /rest/v1/receipts?orderBy=date lists receipts and sort them in ascending order of receipt

date (oldest first).

□

GET /rest/v1/receipts?orderBy=+date lists receipts and sort them in ascending order of receipt

date (oldest first).

□

GET /rest/v1/receipts?orderBy=-date lists receipts and sort them in descending order of receipt

date (most recent first).

■

The Sorting feature supports single level sorting only. Entering a comma-separated list of attributes

will return an error. A secondary sorting level by internal ID is applied by default. When reading a list of

receipts sorted by date, for example, if two receipts have the same receipt date, the response lists the

receipt with the lower internal ID (id) first.

■

The Sorting feature supports standard indexed fields only. See Sortable fields.

■

Sorting by a hidden sortable field is allowed. The returned list of resources is sorted in the order

specified even if the sortable field is hidden due to form permissions, form permission rules or other

account configuration setting.

Sortable fields

The Sorting feature supports standard indexed fields only. The field descriptions in the Generated

API Documentation JSON or the REST API Endpoint Reference indicate whether you can sort the list of

resources by the field. Look for the [Sorting allowed] mention in the schema object field descriptions.

Parameters

Parameter Description

orderBy The attribute to sort the list by. The attribute must be sortable – Look for the [Sorting allowed]

mention in the schema object field descriptions.

Use a plus sign (+) or minus sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the sort order is not specified.

Response

A sorted list of resources. The response includes the meta property in the JSON-encoded object returned.

For a sorted response, the meta property has the following attribute in addition to other relevant

attributes (see also Pagination, for example).

REST API

Example 51

Property Description

orderBy An array of one object containing the following properties:

■

reversed — true if the list is sorted in descending order, or false if the list is sorted in ascending

order.

■

field — the attribute used to sort the list by.

Example

The following example returns a page of 5 receipt objects in descending order of receipt date.

Request:

GET /rest/v1/receipts?orderBy=-date&fields=date,id&limit=5 HTTP/1.1

Response:

{

"message" : "success",

"data" : [

{

"date": "2022-10-03",

"id": 146

{

"date": "2022-10-03",

"id": 152

{

"date": "2022-10-03",

"id": 186

{

"date": "2022-09-26",

"id": 116

{

"date": "2022-09-23",

"id": 98

}

"meta" : { "rowsPerPage": 5,

"totalPages": 44,

"totalRows": 9,

"orderBy": [

{

"reversed": true,

"field": "date"

}

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/receipts?orderBy=-date&fields=date,id&limit=5"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/receipts?orderBy=-date&fields=date,id&limit=5&offset=5"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/receipts?orderBy=-date&fields=date,id&limit=5&offset=40"

}

]

REST API

Example 52

}

REST API

Referenced Objects and Expansion 53

Referenced Objects and Expansion

You can expand objects referenced by internal ID in the main response elements (data array), if the

referenced object type supports expansion. It can be used to return additional data in the same response

without the need for separate requests. Some of this additional data is only available when using

expansion.

If there are any attributes available for expansion in the main response elements (data array), the

response automatically includes a relationships property in the response metadata (meta object) with

information about the attributes available for expansion and the referenced objects (object type and

internal ID).

To include the expanded objects in your response, use the expand query parameter. The JSON-encoded

object returned will include the included property, an array of expanded objects.

For information about available expansions and supported object types, see Available Expansions and

Supported Object Types.

Parameters

Parameter Description

expand A comma-separated list of attributes available for expansion. The comma-separated list may include

spaces (or %20 in the URL encoded string).

Note: Review the following:

■

If you use the expand parameter with a POST or PUT request and return_object is set to

any value other than 0 (zero), the expand value must contain only attributes referencing a

supported object type. If the comma-separated list includes at least one attribute that is

not available for expansion, the request fails — an error is returned and the object is not

added or updated. For more information about attributes available for expansion and

supported object types, see Available Expansions and Supported Object Types.

Response

An expanded response includes the meta and included properties in the JSON-encoded object returned.

Note: The main response element (data array) must include resource objects with attributes

available for expansions for the following properties to be returned. Referenced objects metadata

and expanded objects can be included in responses to GET request used to retrieve a list of objects

or a single object, or in responses to PUT and POST requests if the return_object query parameter

is set to any value other than 0 (zero).

Property Description

meta The response metadata object includes a relationships property — an array of objects containing

information about attributes available for expansion in the main response elements (data array), and

about referenced objects.

The relationships array is always included if there are any attributes available for expansion in the

main response elements (data array).

REST API

Example 54

Property Description

Each object in the relationships array includes a key-value pair for each attribute available for

expansion, where the key is the attribute available for expansion, and the value is an object with the

following properties:

■

data — An object with the following attributes:

□

type — The referenced object type.

□

id — The internal ID of the referenced object is returned even If the object is referenced by

a metavalue (negative integer) instead of an internal ID in the main response element (data

array). The response substitutes the internal ID of the object for the metavalue reference. For

information about possible metavalue references, see object property descriptions in REST API

Endpoint Reference.

The key-value pair is omitted if there are no referenced objects (if the internal ID of the referenced

object is 0).

The response metadata object also includes a warning property if the number expandable objects

referenced in the main response elements is over the maximum number of expanded objects that can

be returned by a single REST API request. For example: “Could not return all expanded objects. The

response contains only the first 1,000 expanded objects. Use the limit parameter to reduce

the number of main response objects and expanded objects returned.”.

included An array of expanded objects. The objects in the included array have the following attributes:

■

type — The expanded object type.

■

data — The expanded object.

Each expanded object in the included array is unique. If the object is referenced multiple times in the

main response elements (data array), the expanded object is only included once in the included array.

The number of expanded objects that can be returned in the included array is limited to 1,000 objects

by default. If the number of expandable objects referenced in the main response elements (data array)

exceeds 1,000 objects that can be returned by a single request, the included array contains only the

first 1,000 expanded objects. The response also includes a warning message in the meta object. To

avoid this situation, use the limit parameter to reduce the number of main response objects and

expanded objects returned. For more information about the limit parameter, see Pagination.

Note: To review your requirements, and increase the maximum number of expanded

objects that can be returned by a single REST API request, contact OpenAir Customer Support.

Note that there will be a performance trade off if the maximum number of expanded object is

increased.

Example

The following request returns the list of attachments associated with the receipt with the internal ID 467

with expansions for the lockedBy, uploadedBy and workspaceId attributes.

GET /rest/v1/receipts/467/attachments?expand=lockedBy,uploadedBy,workspaceId

The response includes the following properties:

■

meta — the response metadata includes relationships information about the attributes available

for expansion (uploadedBy and workspaceId) and the referenced object internal IDs and types

(userDisplayName and workspace, respectively). The lockedBy attribute is omitted as the referenced

object internal ID is 0 for all the main response elements in the data array (no referenced objects).

■

included — an array of expanded userDisplayName and workspace objects.

{

REST API

Available Expansions and Supported Object Types 55

"included": [

{

"data": {

"id": 12,

"displayName": "Marc Collins"

"type": "userDisplayName"

{

"data": {

"created": "2020-12-10 08:09:21",

"name": "Altima Technology",

"updated": "2020-12-10 08:09:21",

"id": 103

"type": "workspace"

}

"data" : [

{

"workspaceId": 103

"isFolder": false,

"fileName": "receipt1.jpg",

"name": "receipt1.jpg",

"isLocked": false,

"uploadedBy": 12,

"lockedBy": 0,

"isExcludedFromAlert": false,

"size": 17762,

"attachmentCategoryId": 0,

"created": "2020-12-13 07:01:00",

"notes": "",

"updated": "2020-12-13 07:01:00",

"id": 1056,

"fileType": "JPEG image data, JFIF standard 1.00, comment: \"LEAD Technologies Inc. V1.01\""

}

"message" : "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 12 }

"workspaceId": {

"data": { "type": "workspace", "id": 103 }

}

"rowsPerPage": 100,

"totalPages": 1,

"totalRows": 1,

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/receipts/467/attachments?expand=lockedBy,workspaceId,upload

edBy"

}

]

}

Available Expansions and Supported Object Types

The following object types support expansion:

■

attachment — See Attachment object properties.

■

userDisplayName — The userDisplayName object type is available only as an expanded object and has

the following attributes:

REST API

Available Expansions and Supported Object Types 56

Property Description Type

id The unique internal identifier of the workspace. integer($int64)

displayName The display name of the user. string

■

workspace — The workspace object type is available only as an expanded object and has the following

attributes:

Property Description Type

created The date the workspace was created. string($date-time)

id The unique internal identifier of the workspace. integer($int64)

name The name of the workspace. string

updated The date the workspace was last updated or modified. string($date-time)

The following table lists the main response attributes available for expansion:

Main response object Attribute Referenced object type Description

Attachment lockedBy userDisplayName Returns the display

name of the

employee who locked

the attachment for

editing.

Attachment uploadedBy userDisplayName Returns the display

name of the

employee who

uploaded the

attachment file.

Attachment workspaceId workspace Returns the

workspace the

attachment is

associated with, if

the attachment is a

workspace document.

ExpenseReport attachments attachment Returns the metadata

for all attachments

associated with the

expense report.

ExpenseReport userId userDisplayName Returns the display

name of the

employee associated

with the expense

report.

Project attachments attachment Returns the metadata

for all attachments

associated with the

project.

Project bookingApprover,

bookingRequestApprover, budgetApprover,

expenseAllowanceApprover,

expenseApprover,

expenseAuthorizationApprover,

userDisplayName Returns the display

name of the

employee.

REST API

Available Expansions and Supported Object Types 57

Main response object Attribute Referenced object type Description

invoiceApprover, projectApprover1,

projectApprover2, projectApprover3,

purchaseOrderApprover,

purchaseRequestApprover,

revenueApprover , timesheetApprover ,

userId

ProjectMilestones,

ProjectPhase,

ProjectTask

attachments attachment Returns the metadata

for all attachments

associated with the

project milestone,

phase, or task.

Receipt attachments attachment Returns the metadata

for all attachments

associated with the

receipt.

Receipt userId userDisplayName Returns the display

name of the

employee associated

with the receipt.

TimeEntry userId userDisplayName Returns the display

name of the

employee associated

with the time entry.

REST API

Errors 58

Errors

The REST API uses conventional HTTP response codes to indicate the success or failure of a request. The

codes can be in one of the following ranges:

■

2xx if the request is successful.

■

4xx if the request fails due to the information provided in the request — it indicates an error in the

request.

■

5xx if the request fails due to a problem with the OpenAir server.

Your client application needs to handle errors when the request fails. The following table lists common

response codes and possible reasons for failing requests. The JSON-encoded response should always

include the message property, a string containing a brief message about the status of your request.

HTTP Status Code Description Reasons

200 OK The request was successful.



207 Multiple

statuses returned

Part of the request was

successful, part of the request

failed.

Possible reasons include:

■

Some of the requested resources do not exist or access

to these resources is denied. For example, if you send

a request to delete multiple attachments associated

with a receipt, the REST API returns an error if any of the

attachments listed are not associated with the receipt

but the listed attachments that are associated with the

receipt are deleted successfully.

400 Bad Request The request is unacceptable. Possible reasons include:

■

The request was improperly formed. For example:

□

The Authorization header was not formatted correctly

— See Authentication Errors.

□

For a PUT or POST request, the Content-Type

header is incorrect or there is a syntax error in the

request body and the REST API cannot interpret

the information. In this case the response object

contains the following message string: “<ObjectName>

deserialization failed”.

□

Parameter error — The pagination or filtering

parameters in the request URL are not valid. The

limit parameter may be above the maximum

allowed, the offset may not be divisible by the page

limit, or there may be a problem with the query

expression q.

■

A validation error. There is a problem with the object sent

in the request body. See Validation Errors.

401 Unauthorized Authentication error. The

response includes a WWW-

Authenticate header with

information about the error.

The access token is invalid. See Authentication Errors.

403 Forbidden Permission to perform the

request is denied.

The access token does not allow the client application to

perform the operation requested on the resource specified

in the request. In most cases, this is due to business rules

configured for the OpenAir account, which may include:

REST API

Parameter errors 59

HTTP Status Code Description Reasons

■

Global or Application settings controlled by account

administrators or by OpenAir Customer Support — The

operation is restricted across the entire account.

■

Role permissions, filter sets (default, or specified using

filterSetId), or other user privileges — The client

application is using the REST API to access OpenAir

on behalf of a user who does not have the relevant

privileges to perform the operation requested.

■

Invalid filter set — The request specifies the filter set to

apply using the filterSetId query parameter and the

specified filter set does not exist or is not associated with

the user on behalf of whom the client application is using

the REST API to access OpenAir. See Active Filter Set.

404 Not Found The requested resource does

not exist.

Possible reasons include:

■

The requested resource does not exist.

■

A required URL parameter is missing. For example the

{id} URL parameter is missing in a GET request, and the

resource only supports retrieving a single object.

405 Method Not

Allowed

The method is not allowed. Possible reasons include:

■

The method is not supported for the resource.

■

A required URL parameter is missing. For example the

{id} URL parameter is missing in a PUT or DELETE request.

429 Too Many

Requests

API limit reached. One of the API limits set for the account was reached. See

API Limits.

500 Internal Server

Error

A problem occurred on

OpenAir’s end.

If system errors persist, please check OpenAir system status,

or contact OpenAir Customer Support.

503 Internal Server

Error

The service is temporarily

unavailable.

If the problem persists, please check OpenAir system status,

or contact OpenAir Customer Support.

Parameter errors

Requests return a 400 Bad Request HTTP response code if there is a problem with one of the query

parameters in the request URL. The response JSON object includes the message property only, with an

error description.

Examples of parameter error messages:

■

limit parameter above the maximum allowed — The specified query parameter 'limit' is out of

bounds. Provide value between 1 and 1000

■

The page offset is not divisible by the page limit — Invalid limit and offset values. The offset

must be divisible by the page limit

■

Problem with the query expression q — Filter error: Expected a valid field name, but found

'created AFTER '2020-' instead

Validation Errors

PUT or POST requests return a 400 Bad Request HTTP response code if there is a problem with any key-

value pair in the JSON-encoded request body. The response JSON object includes the following properties:

REST API

Validation Errors 60

■

message — The message string shows “Invalid data”.

■

errorFields — An object containing the fields with errors as attributes, and for each field an array of

objects containing the attributes:

□

type — The type of validation error returned.

□

message — The error message.

The following example shows the response returned if the request attempts to set or update read-only

fields.

HTTP/ 1.1 400 Bad Request

Content-Type: application/json

{

"errorFields": {

"created": [{

"type": "read-only-value",

"message": "Read-only value"

}],

"updated": [{

"type": "read-only-value",

"message": "Read-only value"

}]

"message": "Invalid data"

}

The following table lists the validation error types

Error Type Description

custom-error A custom-error type is usually associated to a form script associated with the entity

property form in OpenAir.

invalid-value The value is not formatted correctly. For example, if the field data type and format is

string($date), the string value must follow the format “yyyy-mm-dd”. If the value in the

request is “2020–10”, the response includes an invalid-value error type for this field

with the message "Invalid date format".

netsuite-integration-error A netsuite-integration-error type is returned if the resource is selected for real-time

OpenAir<>NetSuite integration, and the operation results in an integration error.

permission-error A permission-error type is returned if the access token does not allow the client

application to perform the operation requested for this field due to the form rules or

form permissions configured in OpenAir .

required-field The field is required. The object in the request body must contain a value for this

field. For more information about required fields, see REST API Endpoint Reference or

Generated API Documentation JSON.

read-only-value The field is read-only. The field cannot be set or updated using the REST API. Hidden

fields are read-only. The REST API returns an error if an attribute-value pair for a

hidden field is included in a POST or PUT request body. For more information about

read-only fields, see REST API Endpoint Reference or Generated API Documentation

JSON.

unknown-field The attribute is not a valid attribute for the object to be created or updated. For

more information about valid object attributes, see REST API Endpoint Reference or

Generated API Documentation JSON.

REST API

Validation Errors 61

Error Type Description

Note: Attribute names are case sensitive and use camelCase, a naming

convention in which each word within a compound word is capitalized except

for the first word. For example, note the initial lowercase t and the uppercase

L and I for taxLocationId.

unknown-type Unknown error type.

Note: An evaluation order is used for the different validation rules. If an error of a given type is

encountered, validation stops and a response returned with that given error type. For example,

if the object in the request body includes an invalid attribute name, and an attribute-value pair

for a read-only field, the unknown-field validation rule is evaluated first, and an error response is

returned before the read-only-value validation rule is evaluated.

REST API

API Limits 62

API Limits

OpenAir enforces some limits to control API consumption and manage the demands on OpenAir

application and database servers. These limits apply across all API components — SOAP API, XML API, and

REST API.

There are two types of usage limits

■

Number of objects

□

The API returns a maximum of 1,000 objects per request. Use pagination to retrieve a list of more

than 1,000 objects. The maximum page length is 1000.

▬

REST API – You can set a limit parameter to control the page length. The page length defaults

to 100 if not specified. See Pagination.

▬

XML and SOAP API – You must set a limit attribute to control the page length. See the help

topics Read Attributes and Pagination.

□

The API accepts a maximum of 1,000 objects as arguments per request. To process more than

1,000 objects, do so in batches. You can add, modify, delete, submit, approve, reject or unapprove

a maximum of 1,000 objects using one XML API call or SOAP API command. You can add or modify

only one object using one REST API request, You can delete a maximum of 100 or 1,000 objects,

depending on the object type, using one REST API request.

■

Frequency limits

□

Maximum number of requests allowed within a 24–hour window for your company's OpenAir

account.

□

Maximum number of requests allowed within a 60–second window for your company's OpenAir

account.

API Frequency Limit Error

If the number of API requests made in the last 60 seconds or in the last 24 hours reaches the maximum

allowed, the API returns an error.

■

The XML API returns the error code 556 to the authentication operation [Auth].

■

The SOAP API returns a 403 Access denied.

■

The REST API returns a 429 Too Many Requests error for any request sent within the 24–hour or 60–

second window.

OpenAir sends a warning email when you approach your API frequency limits.

Tip: To work within your API frequency limits and avoid frequency limit errors, batch operations

into each API call and avoid making API calls within a loop. See the help topic Optimize the API

Integration.

Tracking API Usage Against Frequency Limits

This screen shows the API requests limits that are currently set for the account and the number of

requests remaining within the current 24-hour period. It is a useful reference to track your usage level

when using the SOAP API and XML API. This is for reference purposes only, account administrators cannot

change these settings.

To track your API usage against frequency limits, do one of the following:

REST API

RateLimit 63

■

In OpenAir, go to Administration > Global Settings > Account > API Limits. The page screen shows

the API frequency limits for your company's OpenAir account, the thresholds when OpenAir sends a

warning email for each frequency limit, and the number of requests remaining within the current 24-

hour window. You can use this page to track API usage but you cannot change the frequency limit

settings. It is a read-only page for all users.

■

In OpenAir, review web services logs to identify requests contributing toward any usage limit

overages. See Web Services Logs.

■

Use the XML API to read the number of requests remaining within the current 24-hour window. To do

so, use the Read XML API command and the RateLimit object.

Tip: Query the remaining number of requests at various points in your integration application

to identify where your application is sending the highest volume of requests.

Follow API Best Practice Guidelines to see how you can improve your application.

If you have any questions about frequency limits, contact OpenAir Customer Support. For assistance

with your integration applications and to help reduce the number of API requests in your integration

applications, contact OpenAir Professional Services.

RateLimit

The rate limit [RateLimit] is the number of API requests remaining in the current 24-hour window.

Review Usage Guidelines for the RateLimit object.

Note: OpenAir enforces some limits to control API consumption and manage the demands on

OpenAir application and database servers. One such usage limit applies to the number of requests

in any 24-hour window. See API Limits.

— XML SOAP REST

Object RateLimit oaRateLimit —

Supported Commands Read (all) — —

Note: The RateLimit object supports the all read method only.

The RateLimit object has the following properties:

REST API

RateLimit 64

Field Name Description

remain_24h_error Number of calls remaining in a 24 hour window

Usage Guidelines

You can only query the remaining number of requests using the XML API. The OpenAir WSDL lists the

oaRateLimit but the SOAP API does not support reading this object. The REST API does not have an

equivalent method to query the remaining number of requests.

The following XML API sample code queries the remaining number of requests within the current 24-hour

window:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Auth>

<Login>

<access_token>0123456789-ABCDEFGHIJKLMNIOQRSTUVWXYZ0123456789ABCDEF-ABCDEFGHIJKLMNIOQRSTUVWXYZ01234567</access_token>

</Login>

</Auth>

</Read>

</request>

The following XML API sample response indicates that there are 99949 requests remaining within the

current 24-hour window.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<remain_24h_error>99949</remain_24h_error>

</RateLimit>

</Read>

</response>

Note: This request call counts uses up one request in your API frequency limit.

REST API

Web Services Logs 65

Web Services Logs

An optional feature lets you access web services logs in the Reports application in OpenAir. If the feature

is enabled for your account, go to Reports > Detail > Web services > Web services logs, or go to Reports >

Management and search for “Web services logs”. Configure and run the report for auditing purposes or

to help troubleshooting API requests in your integration applications.

■

Each row in the Web services log represents one request and response pair. For the request part,

OpenAir logs the method used, the request URL, the Content-Type header and the request body. For

the response part, OpenAir logs the HTTP response code and the response body.

■

Records in the Web services log are only available for seven days after they are created.

Note: This feature includes an optional component, which may be enabled to help troubleshoot

any issues with the add-on services provided by OpenAir.

If you are using Web services log reports to track your API usage limits, note that API requests

made by OpenAir Mobile apps, OpenAir Integration Manager and other OpenAir add-on services

do not count toward your usage limits.

Important: The Web services log report feature has the following limitations:

■

If you do not use this feature for more than 30 days, the feature is disabled and the log entries

are deleted.

■

Log entries are retained for 7 days only, then they are purged from the database.

REST API

Generated API Documentation JSON 66

Generated API Documentation JSON

If the REST API is enabled for your account, account administrators and employees with the Export

data role permission can access a system-generated API documentation in OpenAPI 3.0 JSON format.

The generated documentation provides a reference for the REST API including resource descriptions,

endpoints and methods, parameters, request body and response examples and schema. It includes

resource attributes for custom fields specific to your OpenAir account. You can then use any OpenAPI 3.0

compatible tool for further processing.

To access and use the generated API documentation:

In OpenAir, go to Administration > Global settings > Account > Integration: Import/Export. You

must be an Administrator or have the relevant role permission to access this screen.

Click REST API documentation. The generated REST API documentation JSON object appears in a

new browser tab.

Click Copy.

Open an OpenAPI 3.0 compatible tool. For example, open the freely available online tool Swagger

Editor in a new browser tab.

Clear any default content and paste the REST API documentation JSON you previously copied to

your clipboard. If using Swagger Editor, you copy the JSON in the left pane, The tool can convert

the JSON to YAML, generates a static web page and shows the web page in the right pane. You can

edit the JSON or YAML and use the resulting static web page as reference to work with the REST

API.

The following screenshots show the generated the REST API documentation as a static web page as

obtained using Swagger Editor.

REST API

Generated API Documentation JSON 67

The page shows a brief overview followed by endpoints and methods reference. Click any of the frame

corresponding to a specific method and endpoint to show reference information for this method and

endpoint, including a description of parameters and responses.

REST API

Generated API Documentation JSON 68

Scroll down to see resource and response models (schema objects), including a description of attributes

(fields).

REST API

Generated API Documentation JSON 69

REST API

Testing the REST API Using Postman 70

Testing the REST API Using Postman

This section provides some tips and guidelines you can use to get started with testing the REST API using

the GUI REST client Postman.

You can download Postman from https://www.getpostman.com/ and install it on your computer. After you

have installed Postman, you will be able to:

■

Define and save a set of environment variables, which you can then used in your requests, export and

import. See Defining and Saving Environment Variables in Postman.

■

Create collections, you can use to save your requests for later use, export, and import. See Creating a

Request Collection in Postman.

■

Create and send HTTP requests with the help of a user interface. See Creating and Sending API

Requests Using Postman.

■

Use the OAuth 2.0 authorization code flow to get a user’s permission and obtain an access token. See

Getting Authorization and Obtaining a New Access Token Using Postman.

■

Refresh access tokens manually or programmatically. Refreshing Access Tokens Using Postman.

Note: These guidelines are given for illustration purposes only. You can use any GUI REST client

of your choosing. You can also use the curl command-line utility to execute HTTP requests. Refer

to the relevant product documentation for detailed information about its setup and usage.

Defining and Saving Environment Variables in

Postman

A Postman environment is a set of key-value pairs. The key represents the name of the variable, which

you can then use in place of the value in your requests. You can set up multiple environments and switch

between them. For example, you can have, the same set of environment variables with different values

to use the same requests with your sandbox or production OpenAir accounts, or with different access

tokens obtained for different users with different permissions and access rights. You can create copies of

your environments, export them as JSON, or share them with other Postman users.

To define and save environment variables in Postman:

Click the Manage Environments button in the top right corner of the main Postman window.

The Manage Environments window appears.

Click Add. The Add Environment window appears.

Type a name for your environment.

Type a variable name and initial value for each environment variables you want to add. You can

use the following example as a model. replace the companyID value with your unique account

domain identifier, and the clientID, clientSecret, and the callbackUrl values with the client ID,

client secret and redirect URI for the application you registered with OpenAir.

REST API

Creating a Request Collection in Postman 71

Click Add and close the Manage Environments window. The new environment is now available in

the environment selection dropdown in the top right corner of the main Postman window.

Creating a Request Collection in Postman

A Postman collection is a set of HTTP requests. You can use collections to save your requests for later use,

copy an entire set of requests, export them as JSON, or share them with other users.

To create a collection in Postman:

In the left pane of the main Postman window, click the Collections tab and click New collection.

The Create a new collection window appears.

Type a name for your collection.

(Optional) Add a description. You can also define a default authorization method for your requests

and define collection variables, if required. These settings are not set at the collection level for the

purpose of this document.

Click Create. The new collection is listed in the left pane. You can save the requests you create to

this collection.

REST API

Creating and Sending API Requests Using Postman 72

Creating and Sending API Requests Using Postman

Postman makes it simpler to create and send request and read responses. It spares you the need to get

your curl syntax right and analyze requests and responses from the command line.

To create and send an API request using Postman:

In the right pane of the main Postman window, click the + tab.

A new untitled request tab appears. New requests use the GET method by default. You can select

any other supported method from the dropdown on the left.

Enter the request URL. You can use the environment variable for the base URL and add the

relevant resource endpoint path. For example, enter {{baseUrl}}/expense-reports/

Click the Params tab and enter any query parameters as key-value pairs. Notice the query

parameters are added to the request URL as you type.

REST API

Creating and Sending API Requests Using Postman 73

Note: Postman URL-encodes query parameter values. The example above shows a URL-

encoded value for the q parameter but it is not necessary to URL-encode the value in the

Params tab.

Click the Authorization tab. Click the Type dropdown and select OAuth 2.0. Enter the Access

Token. You can use the relevant environment variable for the access token — {{accessToken}}.

Enter the Header Prefix Bearer and ensure Add authorization data to is set to Request Headers.

Note: The first time you send a request or if the refresh token saved in your environment

variables is no longer valid, you may need to get a new access token. See Getting

Authorization and Obtaining a New Access Token Using Postman.

If you are creating a POST or PUT request, click the Body tab. Select the raw option and select

JSON from the type dropdown on the right of the radio buttons. Enter the JSON object for the

resource you want to insert. The Postman editor indicates possible syntax errors with a red line on

the right.

Click Save, Enter or edit the request name, select the collection you want to save this request

under, and click Save to <Collection Name>.

REST API

Getting Authorization and Obtaining a New Access Token Using Postman 74

Click Send to send the request.

You can then analyze the response in the bottom pane, which includes the Body and the HTTP

Status code.

Getting Authorization and Obtaining a New Access

Token Using Postman

Postman lets you use the user interface to obtain and access token using the OAuth 2.0 Authorization

code flow. You can use this to simulate the OAuth 2.0 Authorization process and obtain an access token

to authenticate your requests.

To get authorization and obtain a new access token using Postman:

Open one of your API Requests and click the Authorization tab. The Authorization should be set as

described in Creating and Sending API Requests Using Postman.

Click Get a New Access Token. The Get new access token window appears.

REST API

Refreshing Access Tokens Using Postman 75

Select the Grant type (Authorization Code), enter the Callback URL, Auth URL, Access Token

URL, Client ID, Client Secret, and Scope (rest), and select the Client Authentication (Send as

Basic Auth header). Except for the values specified, you can use environment variables as shown in

the screenshot above.

Click Request Token. The OpenAir or SSO sign-in page appears in a new window.

Enter your sign-in details and submit.

Note: If this is the first time you authorize the application, the Authorization screen will

appear. Click Allow.

The Manage Access Tokens window appears and shows the tokens obtained.

Select the Access token value making sure you do not select the line break at the end (do not

double click to select the entire string). Right click the selected value, point to Set:<Environment

Name>, and click accessToken. Repeat for the Refresh Token value and set the refreshToken

environment variable.

You can now use the accessToken environment variable in your requests.

Refreshing Access Tokens Using Postman

Access token have a short validity period, you can refresh access tokens using a separate request or you

can add a pre-request script to your API requests to refresh your access token if it has expired before you

send a request.

REST API

Refreshing Access Tokens Using Postman 76

Creating a Token Refresh Request Using Postman

You can create a request to refresh your access token. For more information about the request used to

refresh tokens, see Refreshing an Access Token.

To create a token refresh request in Postman:

Create a new request and use the following:

■

Method — POST

■

Request URL — {{accessTokenUrl}}

■

Body — Select form-data and enter the following key-values:

□

refresh_token — {{refreshToken}}

□

access_token — {{accessToken}}

□

grant_type — refresh_token

□

scope — rest

Click the Tests tab and paste the following script. This test script will save the new access token and

refresh token automatically to your environment variables.

pm.test("Status test", function (){pm.response.to.have.status(200)});

if (pm.response.to.have.status(200)) {

var data = pm.response.json();

pm.environment.set("accessToken", data.access_token);

pm.environment.set("refreshToken", data.refresh_token);

}

Click Save and save the request to your collection for later use. You can use this request to refresh

your access token when it expires.

Refreshing Tokens Automatically Before Each API Request

You can add a pre-request script to your API requests to refresh your access token if it has expired before

you send a request and save the new access token and refresh token automatically to your environment

variables.

Open one your API requests, click the Pre-request Script tab, paste the following script, and click Save.

REST API

Refreshing Access Tokens Using Postman 77

The first time the script runs, it will create the environment variable accessTokenExpires. The variable will

be used to save the time the new access token is due to expire. The script compares the current time with

the time the current access token is due to expire and only requests a new access token if the current

access token has expired.

var now = new Date().getTime();

var accessTokenExpires = pm.environment.get("accessTokenExpires");

if (accessTokenExpires === undefined) {

accessTokenExpires = now;

}

if (accessTokenExpires && now >= accessTokenExpires) {

var options = {

method: 'POST',

url: pm.environment.get("accessTokenUrl"),

header: {

"content-type": "application/json"

auth: {

"type": "basic",

"basic": [{

"key": "username",

"value": pm.environment.get("clientID")

}, {

"key": "password",

"value": pm.environment.get("clientSecret")

}]

body: {

mode: 'formdata',

formdata: [{

key: "refresh_token",

value: pm.environment.get("refreshToken"),

disabled: false,

description: {

content: "",

type: "text/plain"

}

}, {

key: "redirect_uri",

value: pm.environment.get("callbackUrl"),

disabled: false,

description: {

content: "",

type: "text/plain"

}

}, {

key: "grant_type",

value: "refresh_token",

disabled: false,

description: {

content: "",

type: "text/plain"

}

}, {

key: "scope",

value: "rest",

disabled: false,

description: {

content: "",

type: "text/plain"

}

}, ]

}

};

console.log(options);

pm.sendRequest(options, function(refreshError, refreshResponse) {

if (refreshError) console.log(refreshError);

var jsonRefreshResponse = refreshResponse.json();

if (jsonRefreshResponse.access_token) {

pm.test("Token refreshed and saved", () => {

REST API

Refreshing Access Tokens Using Postman 78

pm.expect(refreshResponse).to.have.property('code', 200)

});

pm.environment.set("accessToken", jsonRefreshResponse.access_token);

pm.environment.set("refreshToken", jsonRefreshResponse.refresh_token);

var t = new Date();

t.setSeconds(t.getSeconds() + jsonRefreshResponse.expires_in);

pm.environment.set("accessTokenExpires", t.getTime());

} else {

pm.test("Refresh token request failed - Get new access and refresh tokens by clicking \"Get New Access Token\" in the

Authorization tab, save the values in the appropriate environment variables, and try sending the request again", () => {

pm.expect(refreshResponse).to.have.property('code', 200)

});

};

});

}

REST API

REST API Endpoint Reference 79

REST API Endpoint Reference

This section provides reference information for the supported endpoints and methods. The following

table lists the available resource collection endpoints, the corresponding table in the OpenAir database

as documented in the OpenAir data dictionary, and a summary of methods supported for each resource

collection.

REST API resources Database Table Supported methods

Attachments attachment Use the endpoints and method specific to the object

the attachments are associated with

Contacts contact POST, GET, PUT, DELETE, OPTIONS

Expense Reports envelope POST, GET, PUT, DELETE, OPTIONS

Job Codes job_code POST, GET, PUT, DELETE, OPTIONS

Projects project POST, GET, PUT, DELETE, OPTIONS

Project Milestones project_task (classification set to M

for milestones)

GET

Project Phases project_task (classification set to P

for phases)

GET

Project Tasks project_task (classification set to T

for tasks)

POST, GET

Receipts ticket POST, GET, PUT, DELETE, OPTIONS

Time Entries task POST, GET, DELETE, OPTIONS

Attachments

Attachments are files uploaded and stored in OpenAir and associated with records. Each attachment

include the attachment file as well as file metadata.

Available methods

None — To work with attachments, use the endpoints and methods specific to the object the attachments

are associated with.

Attachment object properties

An attachment is a file uploaded and stored in OpenAir and associated with a record. Each attachment

includes file metadata as well as the file itself. The Attachment object includes the file metadata.

The Attachment object has the following properties:

Property Description Type Read-only Query

allowed

Sorting

allowed

attachment

CategoryId

The internal ID of the

attachment category.

integer($int64) — Yes Yes

REST API

Attachments 80

Property Description Type Read-only Query

allowed

Sorting

allowed

created The date the attachment was

created.

string($date-time) Yes Yes —

fileName The filename of the attached

file.

string — Yes Yes

fileType The file type. This is used for

tracking purposes.

string Yes Yes —

hasThumbnail A 1/0 field indicating if a

thumbnail image is available

for the attachment. Returned

only if the Attachment

Thumbnail and Attachment

Viewer feature is enabled for

the OpenAir account.

string Yes Yes —

id The unique internal identifier

of the attachment.

integer($int64) Yes Yes Yes

isExcludedFrom

Alert

A 1/0 field indicating if the

attachment is excluded from

the alert system.

Boolean — Yes —

isFolder A 1/0 field indicating if other

attachment records have this

attachment record as a parent.

Boolean — Yes —

isLocked A 1/0 field indicating if the

attachment is locked for

editing.

Boolean — Yes —

isViewable A 1/0 field indicating if the

attachment is viewable

using the Attachment Viewer

feature. Returned only if the

Attachment Thumbnail and

Attachment Viewer feature

is enabled for the OpenAir

account.

Boolean Yes Yes —

lockedBy The internal ID of the

employee who uploaded the

file. The value is 0 (zero) if

unlocked.

integer($int64) — Yes —

name The display name of the

attachment.

string — Yes Yes

notes Notes about the attachment.

This attribute is used for

keyword search.

string — Yes —

size The file size in bytes. number($float) Yes Yes —

updated The date the attachment was

last updated or modified.

string($date-time) Yes Yes Yes

REST API

Attachments 81

Property Description Type Read-only Query

allowed

Sorting

allowed

uploadedBy The internal ID of the

employee who uploaded the

file.

integer($int64) Yes Yes —

workspaceId The internal ID of the

workspace associated with

the attachment. The value is 0

(zero) if the attachment is not

associated with a workspace.

integer($int64) Yes Yes —

Note: Access to certain object types and object attributes depend on the business logic

configured for the OpenAir account. It may vary depending on the role and access privileges

associated with the access token and with the user who authorized the application.

Required and read-only attributes also depend on the business logic configured for each specific

OpenAir account. Some fields such as id, created, and updated are system-generated and always

read-only.

Contacts

Contact records contain information about individuals working for, or associated with customers.

Available methods

■

POST /contacts/ — Insert a Contact

■

GET /contacts/ — Get the List of Contacts

■

GET /contacts/{id} — Get a Contact

■

PUT /contacts/{id} — Update a Contact

■

DELETE /contacts/{id} — Delete a Contact

■

OPTIONS /contacts/ — Discover Available Methods and Fetch the Endpoint Reference for Contacts

Contact object properties

A contact is a person working for, or associated with a customer.

The Contact object has the following properties:

Property Description Type Read-only Query

allowed

Sorting

allowed

accountingCode Optional accounting

code that can be used for

integration with external

accounting systems.

string — Yes —

address1 First line of the contact's

address.

string — — —

address2 Second line of the contact's

address.

string — — —

REST API

Contacts 82

Property Description Type Read-only Query

allowed

Sorting

allowed

address3 Third line of the contact's

address.

string — — —

address4 Fourth line of the contact's

address.

string — — —

canBill A 1/0 field indicating if the

contact can be used for

billing.

Boolean — Yes —

canSell A 1/0 field indicating if the

contact an be used for

selling.

Boolean — Yes —

canShip A 1/0 field indicating if the

contact can be used for

shipping.

Boolean — Yes —

city The contact's city. string — — —

country The contact's country. string — — —

created The date the contact

record was created.

string($date-time) Yes Yes —

customerId [REQUIRED] The internal

ID of the associated

customer.

integer($int64) — Yes Yes

email The contact's Email

address.

string — Yes —

externalId The unique external ID of

the contact, if the record

was imported from an

external system.

string — Yes Yes

fax The contact's fax number. string — Yes —

firstName The contact's first name. string — Yes —

id The unique internal

identifier of the contact.

integer($int64) Yes Yes Yes

isActive A 1/0 field indicating if the

contact is active.

Boolean — Yes Yes

jobTitle The contact's job title. string — Yes —

lastName [REQUIRED] The contact's

last name.

string — Yes —

mobile The contact's mobile phone

number.

string — Yes —

nickname The nickname used to

identify the contact.

string — Yes —

notes Notes about the contact. string — Yes —

REST API

Contacts 83

Property Description Type Read-only Query

allowed

Sorting

allowed

phone The contact's phone

number.

string — Yes —

state The contact's State or

Region.

string — — —

title The contact's title. string — Yes —

updated The date the contact

record was last updated or

modified.

string($date-time) Yes Yes —

zip The contact's ZIP code or

postal code.

string — — —

Note: Access to certain object types and object attributes depend on the business logic

configured for the OpenAir account. It may vary depending on the role and access privileges

associated with the access token and with the user who authorized the application.

Required and read-only attributes also depend on the business logic configured for each specific

OpenAir account. Some fields such as id, created, and updated are system-generated and always

read-only.

Insert a Contact

POST /contacts/ — Use this method to create a new contact record.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the

response. If not specified, the response includes all attributes

for the contact returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action

is available when the specified filter set is active in OpenAir.

The filter set with the specified internal ID must exist and

must be associated with the user who authorized the

application as per the access token.

■

Otherwise and by default, the primary filter set associated

with the user who authorized the application is applied.

integer

REST API

Contacts 84

Path parameter Required /

Optional

Description Type

return_object Optional If set to 1, the response will return the contact created.

Otherwise, the response will include only the internal ID of the

contact created.

Boolean

Request body

The Contact object to be created. The object must include valid key-value pairs for all required attributes

and cannot include key-value pairs for read-only attributes. For information about the Contact object

model, see Contact object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Contact object created, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the internal ID of the contact created.

See Returned Data.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/contacts/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"jobTitle": "Head of Finance",

"email": "[email protected]",

"lastName": "Doe",

"firstName": "John",

"nickname": "J. Doe",

"isActive": true,

"customerId": 68,

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

REST API

Contacts 85

Sample response

{

"data": [

{

"id": 24

}

"message": "success"

}

Get the List of Contacts

GET /contacts/ — Use this method to retrieve the list of contacts.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for each contact

returned. See Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

REST API

Contacts 86

Property Description

data An array containing the contacts requested. See Returned Data.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/contacts/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

...

{

...

"message": "success",

"meta": {

"rowsPerPage": 100,

"totalPages": 14,

"totalRows": 1386,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/contacts"

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/contacts"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/contacts?limit=100&offset=100"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/contacts?limit=100&offset=1300"

}

]

}

REST API

Contacts 87

}

Get a Contact

GET /contacts/{id} — Use this method to retrieve the contact record with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the contact. integer

Query string parameter

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the contact

returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the contact object requested. See Returned Data.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Contact #24 not found”.

Sample request

GET /rest/v1/contacts/24 HTTP/1.1

REST API

Contacts 88

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"jobTitle": "Head of Finance",

"externalId": "",

"mobile": "",

"state": "",

"email": "[email protected]",

"city": "",

"fax": "",

"updated": "2020-07-30 03:04:58",

"id": 24,

"lastName": "Doe",

"firstName": "John",

"country": "",

"nickname": "J. Doe",

"isActive": true,

"phone": "",

"address2": "",

"created": "2019-05-18 09:51:46",

"zip": "",

"customerId": 68,

"notes": "",

"address1": "",

"title": ""

}

"message": "success"

}

Update a Contact

PUT /contacts/{id} — Use this method to update the contact record with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the contact. integer

Query string parameter

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the

response. If not specified, the response includes all attributes

for the contact returned.

string

REST API

Contacts 89

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action

is available when the specified filter set is active in OpenAir.

The filter set with the specified internal ID must exist and

must be associated with the user who authorized the

application as per the access token.

■

Otherwise and by default, the primary filter set associated

with the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will include

the contact updated. Otherwise, the response will include only

the internal ID of the contact updated.

Boolean

Request body

An object including valid key-value pairs for the fields to be updated. The object cannot include key-

value pairs for read-only attributes. For information about the Contact object model, see Contact object

properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Contact object updated, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the ID of the contact updated.

See Returned Data.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Contact #24 not found”.

Sample request

PUT /rest/v1/contacts/24 HTTP/1.1

Host: company-id.app.openair.com

Content-Type: appplication/json

Authorization: Bearer <OAuth2_access_token>

{

REST API

Contacts 90

"jobTitle": "Head of Finance",

"email": "[email protected]",

"customerId": 68,

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 24

}

"message": "success"

}

Delete a Contact

DELETE /contacts/{id} — Use this method to delete the contact record with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the contact. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

REST API

Contacts 91

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Contact #24

not found”.

Sample request

DELETE /rest/v1/rest/v1/contacts/24 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 24

}

"message": "success"

}

Discover Available Methods and Fetch the Endpoint

Reference for Contacts

OPTIONS /contacts/ — Use this method to discover the methods available and fetch the OpenAPI 3.0

JSON endpoint reference for contacts.

Parameters

None

Response definitions

A successful request returns the OpenAPI 3.0 JSON endpoint reference in the response body. The

JSON object returned contains metadata information about the resource endpoint. It is similar to the

Generated API Documentation JSON, only it is restricted to the resource endpoint path specified in the

request.

The response also includes the following header:

Header Description

Access-Control-Allow-Methods A comma-separated list of HTTP methods available for the requested

resource collection endpoint.

REST API

Contacts 92

Sample request

OPTIONS /rest/v1/contacts/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The response includes the OpenAPI 3.0 endpoint reference for the resource endpoint as a JSON object in

the response body, as well as the following headers:

Content-Type: application/json; charset=utf-8

Content-Length: 6955

Connection: keep-alive

Cache-control: no-cache, no-store, pre-check=0, post-check=0, must-revalidate, max-age=0, s-max-age=0

Pragma: no-cache

Expires: 0

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, PUT, POST, DELETE, OPTIONS

Access-Control-Allow-Headers: Content-Type

Access-Control-Max-Age: 86400

Vary: Accept-Encoding,User-Agent

Content-Encoding: gzip

Expense Reports

Expense reports are collections of expense items (receipts) that employees can use in OpenAir to claim

reimbursement.

Available methods

■

POST /expense-reports/ — Insert an Expense Report

■

POST /expense-reports/overlapping/ — Insert an Overlapping Expense Report (Overlapping expense

reports are expense reports submitted for overlapping periods).

■

GET /expense-reports/ — Get the List of Expense Reports

■

GET /expense-reports/{id} — Get an Expense Report

■

PUT /expense-reports/{id} — Update an Expense Report

■

DELETE /expense-reports/{id} — Delete an Expense Report

■

GET /expense-reports/{id}/receipts — Get the List of Receipts in an Expense Report

■

GET /expense-reports/{id}/receipts/{ticket_id} — Get a Receipt associated with an Expense

Report

■

POST /expense-reports/{id}/attachments — Add an Attachment to an Expense Report

■

GET /expense-reports/{id}/attachments — Get the List of Attachments Associated with an Expense

Report

REST API

Expense Reports 93

■

GET /expense-reports/{id}/attachments/{attachment_id} — Get an Attachment Associated with an

Expense Report

■

GET /expense-reports/{id}/attachments/{attachment_id}/download — Get an Attachment File

Associated with an Expense Report

■

GET /expense-reports/{id}/attachments/{attachment_id}/thumbnail — Get the Thumbnail for an

Attachment Associated with an Expense Report

■

PUT /expense-reports/{id}/attachments/{attachment_id} — Replace an Attachment to an Expense

Report

■

DELETE /expense-reports/{id}/attachments/{attachment_id} — Delete an Attachment Associated

with an Expense Report

■

DELETE /expense-reports/{id}/attachments/{attachment_ids} — Delete Attachments Associated

with an Expense Report

■

OPTIONS /expense-reports/ — Discover Available Methods and Fetch the Endpoint Reference for

Expense Reports

ExpenseReport object properties

An expense report is a collection of expense items (receipts) that employees can use in OpenAir to claim

reimbursement.

The ExpenseReport object has the following properties:

Property Description Type Read-only Query allowed Sorting allowed

accountingDate The accounting period date of the

expense report.

string($date) — Yes Yes

advance The amount of any cash advance on the

expense report.

number($float) — Yes —

approveDate The date the expense report was

approved.

string($date) Yes Yes —

attachments The attachments associated with this

expense report. Array of internal IDs for

attachment objects.

Array of {”id”: <

integerValue>}

objects.

Yes — —

balance The outstanding balance on the

expense report.

number($float) — Yes —

created The date the expense report was

created.

string($date-time) Yes Yes —

currency The currency for monetary values in the

expense report. Three-letter currency

code.

string — Yes —

customerId The internal ID of the associated

customer.

integer$(int64) — Yes Yes

date The date of the expense report. string($date) — Yes Yes

description The description of the expense report

(e.g. reason for the trip).

string — Yes —

endDate The ending date of the expense report

(only used with auto-naming).

string($date) — Yes Yes

exported The date and time the record was

marked as "exported".

string($date-time) — Yes —

externalId The unique external ID of the expense

report, if the record was imported from

an external system.

string — Yes Yes

REST API

Expense Reports 94

Property Description Type Read-only Query allowed Sorting allowed

id The unique internal identifier of the

expense report.

integer($int64) Yes Yes Yes

isAccounting A 1/0 field indicating if an envelope was

submitted to an accounting partner.

Boolean Yes Yes Yes

isAdjusting A 1/0 field indicating if the expense

report is an adjusting expense report.

Boolean Yes Yes —

isForeignCurrencyExchange

Intolerance

A 1/0 field indicating if the record is

within the specified foreign currency

tolerance as defined in database data

definitions.

Boolean Yes Yes Yes

name [REQUIRED] The name of the expense

report.

string — Yes —

notes Notes about the expense report. string — Yes —

projectId The internal ID of the associated

project.

integer($int64) — Yes Yes

startDate The starting date of the expense report

(only used with auto-naming).

string($date) — Yes Yes

status The status of the expense report.

Possible values:

■

O — open

■

S — submitted

■

A — approved

■

R — rejected

string — Yes Yes

submitDate The date the expense report was

submitted.

string($date) Yes Yes —

taxLocationId Default tax location for this expense

report.

integer($int64) — Yes Yes

total The total value of all the receipts in the

expense report.

number($float) — Yes —

totalReceipts The total number of receipts in the

expense report.

integer($int64) Yes Yes —

totalReimburse The total amount of reimbursable

expenses in the expense report.

number($float) Yes Yes —

trackingNumber [REQUIRED] The expense report

tracking number.

string — Yes Yes

updated The date the expense report was last

updated or modified.

string ($date-time) Yes Yes —

userId The internal ID of the associated

employee.

integer($int64) Yes Yes Yes

Note: Access to certain object types and object attributes depend on the business logic

configured for the OpenAir account. It may vary depending on the role and access privileges

associated with the access token and with the user who authorized the application.

Required and read-only attributes also depend on the business logic configured for each specific

OpenAir account. Some fields such as id, created, and updated are system-generated and always

read-only.

Insert an Expense Report

POST /expense-reports/ — Use this method to create a new expense report.

REST API

Expense Reports 95

Note: You cannot use this method to create an expense report if the start date and end date

overlap with another expense report. To insert an overlapping expense report, you must use the

dedicated method and endpoint. See Insert an Overlapping Expense Report.

Overlapping expense reports may not be allowed at all or may be restricted depending on the role

permissions associated with the access token (The role permissions of the user on behalf of whom

the client application is accessing OpenAir).

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the expense

report returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

expense report created. Otherwise, the response will include only

the internal ID of the expense report created.

Boolean

Request body

The ExpenseReport object to be created. The object must include valid key-value pairs for all required

attributes and cannot include key-value pairs for read-only attributes. For information about the

ExpenseReport object model, see ExpenseReport object properties.

REST API

Expense Reports 96

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The ExpenseReport object created, if the return_object parameter was set to any value other than

0 (zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the expense report created.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/expense-reports/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"date": "2020-10-01",

"isAdjusting": false,

"currency": "USD",

"userId": 237,

"name": "September 2020 Expenses",

"isAccounting": false,

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

REST API

Expense Reports 97

"id": 2689

}

"message": "success"

}

Insert an Overlapping Expense Report

POST /expense-reports/overlapping/ — Use this method to create a new expense report record if the

expense report period overlaps with the period covered by an existing expense report. The expense

report period is determined by the attributes startDate and endDate.

Note: Check the account configuration before using this endpoint. Overlapping expense reports

may not be allowed at all or may be restricted depending on the role permissions associated with

the access token (The role permissions of the user on behalf of whom the client application is

accessing OpenAir).

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the expense

report returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

integer

REST API

Expense Reports 98

Path parameter Required /

Optional

Description Type

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

return_object Optional If set to any value other than 0 (zero), the response will return the

expense report created. Otherwise, the response will include only

the internal ID of the expense report created.

Boolean

Request body

The ExpenseReport object to be created. The object must include valid key-value pairs for all required

attributes and cannot include key-value pairs for read-only attributes. For information about the

ExpenseReport object model, see ExpenseReport object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The ExpenseReport object created, if the return_object parameter was set to any value other than

0 (zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the expense report created.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/expense-reports/overlapping/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

REST API

Expense Reports 99

"date": "2020-10-10",

"isAdjusting": false,

"currency": "USD",

"userId": 237,

"name": "September 2020 Additional Expenses ",

"isAccounting": false,

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 2695,

}

"message": "success"

}

Get the List of Expense Reports

GET /expense-reports/ — Use this method to retrieve a list of expense reports.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion. The

comma-separated list may include spaces (or %20 in the URL encoded

string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object is set

to any value other than 0 (zero), and the comma-separated

list includes at least one attribute that is not available for

expansion, the request fails — an error is returned and the

object is not added or updated. For more information about

attributes available for expansion and supported object

types, see Available Expansions and Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If not

specified, the response includes all attributes for each expense report

returned. Response Data Modifiers.

string

REST API

Expense Reports 100

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is available

when the specified filter set is active in OpenAir. The filter set with

the specified internal ID must exist and must be associated with

the user who authorized the application as per the access token.

■

Otherwise and by default, the primary filter set associated with the

user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus sign (-)

before the attribute name to specify an ascending (+) or descending

(-) sort order. An ascending sort order is used if the sort order is not

specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the expense reports requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/expense-reports/ HTTP/1.1

Host: company-id.app.openair.com

REST API

Expense Reports 101

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

...

{

...

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

"type": "attachment"

}

"userId": {

"data": {

"id": 54,

"type": "userDisplayName"

}

...

"rowsPerPage": 100,

"totalPages": 14,

"totalRows": 1386,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/expense-reports"

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/expense-reports"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/expense-reports?limit=100&offset=100"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/expense-reports?limit=100&offset=1300"

}

]

}

Get an Expense Report

GET /expense-reports/{id} — Use this method to retrieve the expense report with the specified internal

ID.

REST API

Expense Reports 102

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion. The

comma-separated list may include spaces (or %20 in the URL encoded

string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object is set

to any value other than 0 (zero), and the comma-separated

list includes at least one attribute that is not available for

expansion, the request fails — an error is returned and the

object is not added or updated. For more information about

attributes available for expansion and supported object

types, see Available Expansions and Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If not

specified, the response includes all attributes for the expense report

returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is available

when the specified filter set is active in OpenAir. The filter set with

the specified internal ID must exist and must be associated with

the user who authorized the application as per the access token.

■

Otherwise and by default, the primary filter set associated with the

user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the expense report requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

REST API

Expense Reports 103

Property Description

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/expense-reports/237 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"totalReceipts": 2,

"isForeignCurrencyExchangeIntolerance": false,

"externalId": "",

"status": "A",

"date": "2019-10-01",

"isAdjusting": false,

"accountingDate": "2019-09-30",

"taxLocationId": 0,

"currency": "USD",

"updated": "2019-10-21 03:04:57",

"totalReimburse": 1260,

"submitDate": "2019-10-01",

"id": 237,

"attachments": [],

"userId": 54,

"name": "September Expenses",

"isAccounting": false,

"total": 1260,

"description": "September 2019 Expenses",

"created": "2019-10-01 14:12:38",

"balance": 1000,

"notes": "",

"endDate": "0000-00-00",

"approveDate": "2019-10-21",

"exported": "0000-00-00 00:00:00",

"trackingNumber": "1113",

"startDate": "0000-00-00" }

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

"type": "attachment"

}

REST API

Expense Reports 104

"userId": {

"data": {

"id": 54,

"type": "userDisplayName"

}

]

}

Update an Expense Report

PUT /expense-reports/{id} — Use this method to update the expense report with the specified internal

ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the expense

report returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

REST API

Expense Reports 105

Path parameter Required /

Optional

Description Type

return_object Optional If set to any value other than 0 (zero), the response will include

the expense report updated. Otherwise, the response will include

only the internal ID of the expense report updated.

Boolean

Request body

An object including valid key-value pairs for the fields to be updated. The object cannot include key-value

pairs for read-only attributes. For information about the ExpenseReport object model, see ExpenseReport

object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The ExpenseReport object updated, if the return_object parameter was set to any value other than

0 (zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the ID of the expense report updated.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Expense report #237 not

found”.

Sample request

PUT /rest/v1/expense-reports/237 HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"externalId": "568",

"accountingDate": "2019-10-30",

"currency": "CAD",

REST API

Expense Reports 106

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 237

}

"message": "success"

}

Delete an Expense Report

DELETE /expense-reports/{id} — Use this method to delete the expense report record with the specified

internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Expense

report #237 not found”.

REST API

Expense Reports 107

Sample request

DELETE /rest/v1/expense-reports/24 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 24

}

"message": "success"

}

Get the List of Receipts in an Expense Report

GET /expense-reports/{id}/receipts/ — Use this method to retrieve the collection of receipts in the

expense report with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for each

receipt returned. Response Data Modifiers. For information about

Receipt object properties, see Receipt object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

integer

REST API

Expense Reports 108

Path parameter Required /

Optional

Description Type

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the list of receipts in the expense report with the specified internal ID. See

Returned Data. For information about Receipt object properties, see Receipt object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Expense report #237 not

found”.

Sample request

GET /rest/v1/expense-reports/237/receipts/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

REST API

Expense Reports 109

Sample response

{

"data": [

{

"foreignCurrencySymbol": "",

"expenseReportId": 237,

"date": "2019-10-01",

"costPerUnit": 680,

"taxLocationId": 0,

"foreignCurrencyRate": 0,

"projectTaskId": 0,

"updated": "2019-10-21 03:04:58",

"id": 2659,

"slipId": 0,

"paymentTypeId": 0,

"total": 680,

"description": "Miscellaneous",

"itemId": 7,

"customerId": 50,

"totalTaxPaid": 0,

"costCenterId": 0,

"trackingNumber": "1",

"isForeignCurrencyExchangeIntolerance": false,

"externalId": "",

"userLocationId": 0,

"isNonBillable": false,

"accountingDate": "0000-00-00",

"foreignCurrencyCost": 0,

"currency": "USD",

"foreignCurrencyTotalTaxPaid": 0,

"projectId": 54,

"isTaxIncludedInCost": false,

"attachments": [3719],

"userId": 49,

"quantity": 1,

"created": "2019-10-01 14:12:50",

"isReimbursable": true,

"totalNoTax": 680,

"notes": ""

{

"foreignCurrencySymbol": "",

"expenseReportId": 237,

"date": "2019-10-01",

"costPerUnit": 580,

"taxLocationId": 0,

"foreignCurrencyRate": 0,

"projectTaskId": 0,

"updated": "2019-10-21 03:04:58",

"id": 2674,

"slipId": 0,

"paymentTypeId": 0,

"total": 580,

"description": "Miscellaneous",

"itemId": 7,

"customerId": 50,

"totalTaxPaid": 0,

"costCenterId": 0,

"trackingNumber": "2",

"isForeignCurrencyExchangeIntolerance": false,

"externalId": "",

"userLocationId": 0,

"isNonBillable": true,

"accountingDate": "0000-00-00",

"foreignCurrencyCost": 0,

"currency": "USD",

"foreignCurrencyTotalTaxPaid": 0,

"projectId": 54,

"isTaxIncludedInCost": false,

"attachments": [3745],

"userId": 49,

REST API

Expense Reports 110

"quantity": 1,

"created": "2019-10-01 14:13:03",

"isReimbursable": true,

"totalNoTax": 580,

"notes": ""

}

"message": "success",

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

3719

"type": "attachment"

}

"userId": {

"data": {

"id": 49,

"type": "userDisplayName"

}

{

"attachments": {

"data": {

"id": [

3745

"type": "attachment"

}

"userId": {

"data": {

"id": 49,

"type": "userDisplayName"

}

"rowsPerPage": 100,

"totalPages": 1,

"totalRows": 2,

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/expense-reports/237/receipts"

}

]

}

Get a Receipt associated with an Expense Report

GET /expense-reports/{id}/receipts/{ticket_id} — Use this method to retrieve a receipt with the

specified receipt ID in the expense report with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

REST API

Expense Reports 111

Path parameter Required / Optional Description Type

{ticket_id} Required The internal ID of the receipt. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for each

receipt returned. Response Data Modifiers. For information about

Receipt object properties, see Receipt object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the receipt requested. See Returned Data. For information about Receipt object

properties, see Receipt object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Expense report #237 not

found”.

Sample request

GET /rest/v1/expense-reports/237/receipts/2674 HTTP/1.1

REST API

Expense Reports 112

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"foreignCurrencySymbol": "",

"expenseReportId": 237,

"date": "2019-10-01",

"costPerUnit": 580,

"taxLocationId": 0,

"foreignCurrencyRate": 0,

"projectTaskId": 0,

"updated": "2019-10-21 03:04:58",

"id": 2674,

"slipId": 0,

"paymentTypeId": 0,

"total": 580,

"description": "Miscellaneous",

"itemId": 7,

"customerId": 50,

"totalTaxPaid": 0,

"costCenterId": 0,

"trackingNumber": "2",

"isForeignCurrencyExchangeIntolerance": false,

"externalId": "",

"userLocationId": 0,

"isNonBillable": true,

"accountingDate": "0000-00-00",

"foreignCurrencyCost": 0,

"currency": "USD",

"foreignCurrencyTotalTaxPaid": 0,

"projectId": 54,

"isTaxIncludedInCost": false,

"attachments": 3719,

"userId": 49,

"quantity": 1,

"created": "2019-10-01 14:13:03",

"isReimbursable": true,

"totalNoTax": 580,

"notes": ""

}

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

3719

"type": "attachment"

}

"userId": {

"data": {

"id": 49,

"type": "userDisplayName"

}

REST API

Expense Reports 113

Add an Attachment to an Expense Report

POST /expense-reports/{id}/attachments — Use this method to add an attachment to the expense

report with the specified internal ID. This method can be used for any of the following cases:

■

Create a new attachment and associate it with the expense report.

■

Associate a workspace document with the expense report. Workspace documents are Attachment

objects associated with a custom workspace.

Note: If the Attachment Thumbnail and Attachment Viewer feature is enabled for your OpenAir

account, a thumbnail is generated automatically when you add an attachment of a supported

format. The file_name must be included in the request and must include a supported file

extension. For more information about the Attachment Thumbnail feature, including supported file

format and filename extensions, see Optional Features.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment returned. For the Attachment object properties, see

Attachment object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

integer

REST API

Expense Reports 114

Path parameter Required /

Optional

Description Type

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

return_object Optional If set to any value other than 0 (zero), the response will return the

attachment created. Otherwise, the response will include only the

internal ID of the attachment created.

Boolean

Request body

This method accepts either one of the content types described in the following table:

Content-Type header Body Use case

multipart/form-data Form data with the following key-value pair:

■

file — The file to be uploaded. The file

and file metadata will be used to create

the new Attachment object.

■

Create a new attachment and

associate it with the expense

report.

application/json JSON object with the following key-value pair:

■

id — The internal ID of the workspace

document to be associated with the

expense report.

■

Associate a workspace document

with the expense report.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Attachment object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the attachment created.

See Returned Data. For the Attachment object properties, see Attachment object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

REST API

Expense Reports 115

Sample request

POST /rest/v1/expense-reports/237/attachments/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: multipart/form-data boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Authorization: Bearer <OAuth2_access_token>

----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"

@C:\Users\mcollins\Desktop\2020-12-08_18-47-31.png

----WebKitFormBoundary7MA4YWxkTrZu0gW

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

Get the List of Attachments Associated with an Expense

Report

GET /expense-reports/{id}/attachments — Use this method to retrieve the list of attachments

associated with the expense report with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for each

attachment returned. Response Data Modifiers. For information

about Attachment object properties, see Attachment object

properties.

string

filterSetId Optional The internal ID of the filter set to be applied. integer

REST API

Expense Reports 116

Path parameter Required /

Optional

Description Type

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the list of attachments associated with the expense report with the specified

internal ID. See Returned Data. For information about Attachment object properties, see Attachment

object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Expense report #237 not

found”.

Sample request

GET /rest/v1/expense-reports/237/attachments/?fields=fileName,isLocked,uploadedBy,size,id,fileType HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

REST API

Expense Reports 117

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"fileName": "2020-11-20_13-25-06.png",

"isLocked": false,

"id": 4982,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 114659

{

"fileName": "2020-12-08_14-46-24.png",

"isLocked": false,

"id": 56,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 123754

"message": "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

"rowsPerPage": 100,

"totalPages": 1,

"totalRows": 2,

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/expense-reports/237/attachments"

}

]

}

Get an Attachment Associated with an Expense Report

GET /expense-reports/{id}/attachments/{attachment_id} — Use this method to retrieve the attachment

record with the specified attachment ID associated with the expense report with the specified internal ID.

The response contains the attachment metadata only and not the file.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

REST API

Expense Reports 118

Path parameter Required / Optional Description Type

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment metadata returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the attachment metadata requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Attachment #598 not

found”.

Sample request

GET expense-reports/237/attachments/4982?fields=fileName,isLocked,uploadedBy,size,id,fileType HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

REST API

Expense Reports 119

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"fileName": "2020-11-20_13-25-06.png",

"isLocked": false,

"id": 4982,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 114659

}

"message": "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

]

}

Get an Attachment File Associated with an Expense Report

GET /expense-reports/{id}/attachments/{attachment_id}/download — Use this method to retrieve the

file associated with the attachment record with the specified attachment ID associated with the expense

report with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

REST API

Expense Reports 120

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#598 not found”.

A successful request also returns the attachment file.

Sample request

GET expense-reports/237/attachments/4982/download HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The attachment file.

Get the Thumbnail for an Attachment Associated with an

Expense Report

GET /expense-reports/{id}/attachments/{attachment_id}/thumbnail — Use this method to retrieve the

thumbnail file associated with the attachment record with the specified attachment ID associated with

the expense report with the specified internal ID. Available only if the Attachment Thumbnail feature is

enabled for your OpenAir account.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

integer

REST API

Expense Reports 121

Path parameter Required /

Optional

Description Type

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#598 not found” or “Attachment #213 thumbnail not found”.

A successful request also returns the attachment thumbnail file.

Sample request

GET expense-reports/237/attachments/4982/thumbnail HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The attachment thumbnail file.

Replace an Attachment to an Expense Report

PUT /expense-reports/{id}/attachments/{attachment_id} — Use this method to replace an attachment

to the expense report with the specified internal ID.

Important: This method can only be used to replace an attachment directly associated with the

expense report. It cannot be used for workspace document associated with the expense report

either to replace the workspace document or to associate a different workspace document in its

place.

Note: If the Attachment Thumbnail and Attachment Viewer feature is enabled for your OpenAir

account, a thumbnail is generated automatically when you add an attachment of a supported

format. The file_name must be included in the request and must include a supported file

extension. For more information about the Attachment Thumbnail feature, including supported file

format and filename extensions, see Optional Features.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

REST API

Expense Reports 122

Path parameter Required / Optional Description Type

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment returned. For the Attachment object properties, see

Attachment object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

attachment created. Otherwise, the response will include only the

internal ID of the attachment created.

Boolean

Request body

This method accepts the following content type:

Content-Type header Body

multipart/form-data Form data with the following key-value pair:

■

file — The file to be uploaded. The file and file metadata will be used to replace

the existing Attachment object with a new Attachment object.

Response definitions

A successful request returns a JSON object with the following properties:

REST API

Expense Reports 123

Property Description

data An array containing one of the following:

■

The Attachment object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the attachment created.

See Returned Data. For the Attachment object properties, see Attachment object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

PUT /rest/v1/expense-reports/237/attachments/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: multipart/form-data boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Authorization: Bearer <OAuth2_access_token>

----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"

@C:\Users\mcollins\Desktop\2020-12-08_18-47-31.png

----WebKitFormBoundary7MA4YWxkTrZu0gW

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

Delete an Attachment Associated with an Expense Report

DELETE /expense-reports/{id}/attachments/{attachment_id} — Use this method to delete the

attachment with the specified attachment ID associated with the expense report with the specified

REST API

Expense Reports 124

internal ID, or clear the association between the workspace document with the specified attachment ID

and the expense report with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the expense report. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#4985 not found”.

Sample request

DELETE /rest/v1/expense-reports/237/attachments/4982 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

REST API

Expense Reports 125

"data": [

{

"id": 4982

}

"message": "success"

}

Delete Attachments Associated with an Expense Report

DELETE /expense-reports/{id}/attachments/{attachment_ids} — Use this method to delete attachments

with the specified attachment IDs associated with the expense report with the specified internal ID, or

clear the association between the workspace document with the specified attachment ID and the expense

report with the specified internal ID.

Parameters

Path parameters

Path parameter Required /

Optional

Description Type

{id} Required The internal ID of the expense report. integer

{attachment_ids} Required A comma-separated list of internal IDs for the

attachments. The list must not include more than

1000 attachment IDs.

integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message If your request includes multiple attachment IDs, both valid and invalid, the request will complete

successfully for valid attachment IDs and return an error message for invalid attachment IDs — e.g.

"Access to Attachment #693 denied". The response status will be 207 Multiple statuses returned.

REST API

Expense Reports 126

Property Description

If your request more than 1,000 attachment IDs, an error is returned — e.g. "Bulk action limit

reached, sent 1001 entities of 1000 allowed".

Sample request

DELETE /rest/v1/expense-reports/237/attachments/4982,4983 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"4982" : {

"data": [{

"id": "4982"

}],

"message": "success"

"4983" : {

"data": [{

"id": "4983"

}],

"message": "success"

}

"message": "success"

}

Discover Available Methods and Fetch the Endpoint

Reference for Expense Reports

OPTIONS /expense-reports/ — Use this method to discover the methods available and fetch the

OpenAPI 3.0 JSON endpoint reference for expense reports.

Parameters

None

Response definitions

A successful request returns the OpenAPI 3.0 JSON endpoint reference in the response body. The

JSON object returned contains metadata information about the resource endpoint. It is similar to the

Generated API Documentation JSON, only it is restricted to the resource endpoint path specified in the

request.

The response also includes the following header:

REST API

Expense Reports 127

Header Description

Access-Control-Allow-Methods A comma-separated list of HTTP methods available for the requested

resource collection endpoint.

Sample request

OPTIONS /rest/v1/expense-reports/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The response includes the OpenAPI 3.0 endpoint reference for the resource endpoint as a JSON object in

the response body, as well as the following headers:

Content-Type: application/json; charset=utf-8

Content-Length: 6955

Connection: keep-alive

Cache-control: no-cache, no-store, pre-check=0, post-check=0, must-revalidate, max-age=0, s-max-age=0

Pragma: no-cache

Expires: 0

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, PUT, POST, DELETE, OPTIONS

Access-Control-Allow-Headers: Content-Type

Access-Control-Max-Age: 86400

Vary: Accept-Encoding,User-Agent

Content-Encoding: gzip

Job Codes

Job code records are general job categories that can be used to classify employees. Each job code can

have a generic cost for estimation and billing.

Available methods

■

POST /job-codes/ — Insert a Job Code

■

GET /job-codes/ — Get the List of Job Codes

■

GET /job-codes/{id} — Get a Job Code

■

PUT /job-codes/{id} — Update a Job Code

■

DELETE /job-codes/{id} — Delete a Job Code

■

OPTIONS /job-codes/ — Discover Available Methods and Fetch the Endpoint Reference for Job Codes

JobCode object properties

A job code is a general job category with a generic cost that can be used for estimation and billing.

The JobCode object has the following properties:

REST API

Job Codes 128

Property Description Type Read-only Query

allowed

Sorting

allowed

accountingCode Optional accounting

code that can be used for

integration with external

accounting systems.

string — Yes —

created The date the job code was

created.

string($date-time) Yes Yes —

currency The currency for monetary

values in the job code

record. Three-letter

currency code.

string — Yes —

externalId The unique external

record ID, if the record was

imported from an external

system.

string — Yes Yes

genericResourceId The internal ID of the

generic resource used in

full-time equivalent (FTE)

forecasting.

integer($int64) — Yes Yes

id The unique internal

identifier of the job code.

integer($int64) Yes Yes Yes

isActive A 1/0 field indicating if the

job code is active.

Boolean — Yes Yes

loadedCost The cost per hour. number($float) — Yes —

name [REQUIRED] The display

name of the job code.

string — Yes Yes

notes Notes about the job code. Boolean — Yes —

updated The date the job code was

last updated or modified.

string($date-time) Yes Yes —

Note: Access to certain object types and object attributes depend on the business logic

configured for the OpenAir account. It may vary depending on the role and access privileges

associated with the access token and with the user who authorized the application.

Required and read-only attributes also depend on the business logic configured for each specific

OpenAir account. Some fields such as id, created, and updated are system-generated and always

read-only.

Insert a Job Code

POST /job-codes/ — Use this method to create a new job code record.

Parameters

Path parameters

None

REST API

Job Codes 129

Query string parameter

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the

response. If not specified, the response includes all attributes

for the job code returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action

is available when the specified filter set is active in OpenAir.

The filter set with the specified internal ID must exist and

must be associated with the user who authorized the

application as per the access token.

■

Otherwise and by default, the primary filter set associated

with the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return

the job code created. Otherwise, the response will include only

the internal ID of the job code created.

Boolean

Request body

The JobCode object to be created. The object must include valid key-value pairs for all required attributes

and cannot include key-value pairs for read-only attributes. For information about the JobCode object

model, see JobCode object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The JobCode object created, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the internal ID of the job code created.

See Returned Data.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/job-codes/ HTTP/1.1

Host: company-id.app.openair.com

REST API

Job Codes 130

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"loadedCost": 130,

"isActive": true,

"genericResourceId": 12,

"name": "Senior Consultant",

"currency": "USD"

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 8

}

"message": "success"

}

Get the List of Job Codes

GET /job-codes/ — Use this method to retrieve the list of job codes.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for each job

code returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

REST API

Job Codes 131

Path parameter Required /

Optional

Description Type

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the job code objects requested. See Returned Data.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/job-codes/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

...

{

...

"message": "success",

"meta": {

"rowsPerPage": 100,

REST API

Job Codes 132

"totalPages": 2,

"totalRows": 138,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/job-codes"

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/job-codes"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/job-codes?limit=100&offset=100"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/job-codes?limit=100&offset=100"

}

]

}

Get a Job Code

GET /job-codes/{id} — Use this method to retrieve the job code record with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the job code. integer

Query string parameter

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the job code

returned. Response Data Modifiers.

fields

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

REST API

Job Codes 133

Property Description

data An array containing the job code object requested. See Returned Data.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “JobCode #8 not found”.

Sample request

GET /rest/v1/job-codes/8 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"loadedCost": 130,

"externalId": "45",

"isActive": true,

"genericResourceId": 12,

"name": "Senior Consultant",

"accountingCode": "",

"currency": "USD",

"created": "2019-02-20 13:42:15",

"notes": "",

"updated": "2020-09-30 03:04:57",

"id": 8

}

"message": "success"

}

Update a Job Code

PUT /job-codes/{id} — Use this method to update the job code record with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the job code. integer

REST API

Job Codes 134

Query string parameter

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the

response. If not specified, the response includes all attributes

for the job code returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action

is available when the specified filter set is active in OpenAir.

The filter set with the specified internal ID must exist and

must be associated with the user who authorized the

application as per the access token.

■

Otherwise and by default, the primary filter set associated

with the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will include

the job code updated. Otherwise, the response will include

only the internal ID of the job code updated.

Boolean

Request body

An object including valid key-value pairs for the fields to be updated. The object cannot include key-

value pairs for read-only attributes. For information about the JobCode object model, see JobCode object

properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The JobCode object updated, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the ID of the job code updated.

See Returned Data.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “JobCode #8 not found”.

Sample request

PUT /rest/v1/job-codes/8 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

REST API

Job Codes 135

{

"loadedCost": 137.5,

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 8

}

"message": "success"

}

Delete a Job Code

DELETE /job-codes/{id} — Use this method to delete the job code record with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the job code. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “JobCode #8

not found”.

REST API

Job Codes 136

Sample request

DELETE /rest/v1/job-codes/8 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 8

}

"message": "success"

}

Discover Available Methods and Fetch the Endpoint

Reference for Job Codes

OPTIONS /job-codes/ — Use this method to discover the methods available and fetch the OpenAPI 3.0

JSON endpoint reference for job codes.

Parameters

None

Response definitions

A successful request returns the OpenAPI 3.0 JSON endpoint reference in the response body. The

JSON object returned contains metadata information about the resource endpoint. It is similar to the

Generated API Documentation JSON, only it is restricted to the resource endpoint path specified in the

request.

The response also includes the following header:

Header Description

Access-Control-Allow-Methods A comma-separated list of HTTP methods available for the requested

resource collection endpoint.

Sample request

OPTIONS /rest/v1/job-codes/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

REST API

Job Codes 137

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The response includes the OpenAPI 3.0 endpoint reference for the resource endpoint as a JSON object in

the response body, as well as the following headers:

Content-Type: application/json; charset=utf-8

Content-Length: 6955

Connection: keep-alive

Cache-control: no-cache, no-store, pre-check=0, post-check=0, must-revalidate, max-age=0, s-max-age=0

Pragma: no-cache

Expires: 0

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, PUT, POST, DELETE, OPTIONS

Access-Control-Allow-Headers: Content-Type

Access-Control-Max-Age: 86400

Vary: Accept-Encoding,User-Agent

Content-Encoding: gzip

Projects

Projects are unique sequences of tasks that must be completed to reach a certain outcome.

Available methods

■

POST /projects/ — Insert a Project

■

POST /projects/from-template/ — Create a Project from Template

■

POST /projects/bulk/ — Insert Multiple Projects

■

GET /projects/ — Get the List of Projects

■

GET /projects/{id} — Get a Project

■

PUT /projects/{id} — Update a Project

■

PUT /projects/bulk/{ids} — Update Multiple Projects

■

DELETE /projects/{id} — Delete a Project

■

DELETE /projects/bulk/{ids} —Delete Multiple Projects

■

POST /projects/{id}/attachments — Add an Attachment to a Project

■

GET /projects/{id}/attachments — Get the List of Attachments Associated with a Project

■

GET /projects/{id}/attachments/{attachment_id} — Get an Attachment Associated with a Project

■

GET /projects/{id}/attachments/{attachment_id}/download — Get an Attachment File Associated

with a Project

■

GET /projects/{id}/attachments/{attachment_id}/thumbnail — Get the Thumbnail for an

Attachment Associated with a Project

■

PUT /projects/{id}/attachments/{attachment_id} — Replace an Attachment to a Project

■

DELETE /projects/{id}/attachments/{attachment_id} — Delete an Attachment Associated with a

Project

■

DELETE /projects/{id}/attachments/{attachment_ids} — Delete Attachments Associated with a

Project

■

OPTIONS /projects/ — Discover Available Methods and Fetch the Endpoint Reference for Projects

REST API

Projects 138

Project object properties

A project is a unique sequence of tasks that must be completed to reach a certain outcome.

The Project object has the following properties:

Property Description Type Read-only Query allowed Sorting

allowed

accountingCode Optional accounting code that can be used for

integration with external accounting systems.

string — Yes —

attachments The attachments associated with this project.

Array of internal IDs for attachment objects.

Array of {”id”:

} objects.

Yes — —

autoBillCapValue The autobilling cap amount, in the currency

used for the project.

number($float) — Yes —

billingCode The project billing code. Used in bulk invoicing. string — Yes Yes

billingContactId The internal ID of the billing contact, if different

from the designated billing contact for the

customer.

integer($int64) — Yes Yes

bookingApprovalProcess The internal ID of the approval process for

bookings to the project. Mutually exclusive with

bookingApprover.

integer($int64) — Yes —

bookingApprover The internal ID of the User who approves

bookings to the project, if a single approver

process is used. Mutually exclusive with

bookingApprovalProcess.

Other possible values:

■

-1 — the booked resource’s manager.

■

-2 — the manager of the booked resource's

manager.

■

-3 — the project owner.

■

-4 — self (booked resource).

■

-9 — submitter. This option may not be

available depending on your OpenAir

account configuration.

integer($int64) — Yes —

bookingRequestApproval

Process

The internal ID of the approval process for

booking requests to the project, depending on

the OpenAir account configuration. Mutually

exclusive with bookingRequestApprover.

The internal ID of the booking request approval

process for the project. Mutually exclusive with

bookingRequestApprover.

integer($int64) — Yes —

bookingRequestApprover The internal ID of the User who approves

booking requests to the project, if a single

approver process is used. Mutually exclusive

with bookingApprovalProcess.

The internal ID of the employee who approves

booking requests to the project, if a single

approver process is used. Mutually exclusive

with bookingApprovalProcess.

Other possible values:

■

-1 — the requested resource or the

requester's manager, depending on your

OpenAir account configuration.

■

-2 — the manager of the booked resource or

requester's manager.

■

-3 — the project owner.

integer($int64) — Yes —

REST API

Projects 139

Property Description Type Read-only Query allowed Sorting

allowed

■

-4 — self (booked resource or the

requester).

■

-9 — submitter (requester). This option may

not be available depending on your OpenAir

account configuration.

budget The budgeted revenue for the project. number($float) — Yes —

budgetApprovalProcess The internal ID of the approval process for

budget associated with the project. Mutually

exclusive with budgetApprover.

integer($int64) — Yes —

budgetApprover The internal ID of the User who approves

budgets for the project, if a single approver

process is used. Mutually exclusive with

budgetApprovalProcess.

Other possible values:

■

-1 — the budget owner’s manager.

■

-2 — the manager of the budget owner’s

manager.

■

-3 — the project owner.

■

-4 — self (budget owner).

integer($int64) — Yes —

budgetCost The budgeted cost for the project. number($float) — Yes —

budgetTime The budgeted amount of time for the project in

hours.

number($float) — Yes —

categoryFilter A comma-delimited list of internal IDs of

categories (services) against which time can be

booked for the project.

string — Yes —

contactId The internal ID of the contact associated with

the project.

integer($int64) — Yes Yes

copyApprovers A 1/0 field indicating whether to copy the

project approvers associated with the project or

project template specified in templateProjectId.

Used only with POST /projects/from-template/.

Boolean — — —

copyBookings A 1/0 field indicating whether to copy the

bookings associated with the project or project

template specified in templateProjectId. Used

only with POST /projects/from-template/.

Boolean — — —

copyCpExcludeFilters A 1/0 field indicating whether to copy the

customers and projects to exclude from

denominator when calculating user allocation

% from the project or project template specified

in templateProjectId. Used only with POST /

projects/from-template/.

Boolean — — —

copyCustomFields A 1/0 field indicating whether to copy the

custom field values from the project or project

template specified in templateProjectId. Used

only with POST /projects/from-template/.

Boolean — — —

copyDashboardSettings A 1/0 field indicating whether to copy the

dashboard settings from the project or project

template specified in templateProjectId. Used

only with POST /projects/from-template/.

Boolean — — —

copyExpensePolicy A 1/0 field indicating whether to copy the

expense policy associated with the project or

project template specified in templateProjectId.

Used only with POST /projects/from-template/.

Boolean — — —

copyInvoiceLayout

Settings

A 1/0 field indicating whether to copy the

invoice layout settings associated with the

project or project template specified in

Boolean — — —

REST API

Projects 140

Property Description Type Read-only Query allowed Sorting

allowed

templateProjectId. Used only with POST /

projects/from-template/.

copyIssues A 1/0 field indicating whether to copy the issues

associated with the project or project template

specified in templateProjectId. Used only with

POST /projects/from-template/.

Boolean — — —

copyLoadedCost A 1/0 field indicating whether to copy the loaded

costs from the project or project template

specified in templateProjectId. Used only with

POST /projects/from-template/.

Boolean — — —

copyNotification

Settings

A 1/0 field indicating whether to copy the

notification settings from the project or project

template specified in templateProjectId. Used

only with POST /projects/from-template/.

Boolean — — —

copyProjectAssignment

Profiles

A 1/0 field indicating whether to copy the

project assignment profiles associated with

the project or project template specified in

templateProjectId. Used only with POST /

projects/from-template/.

Boolean — — —

copyProjectBillingAuto

Setting

A 1/0 field indicating whether to copy the

automated project autobilling settings from

the project or project template specified in

templateProjectId. Used only with POST /

projects/from-template/.

Boolean — — —

copyProjectBilling

Rules

A 1/0 field indicating whether to copy the

project billing rules associated with the

project or project template specified in

templateProjectId. Used only with POST /

projects/from-template/.

Boolean — — —

copyProjectBudget

Groups

A 1/0 field indicating whether to copy the

project budget groups associated with the

project or project template specified in

templateProjectId. Used only with POST /

projects/from-template/.

Boolean — — —

copyProjectPricing A 1/0 field indicating whether to copy the

project pricing associated with the project or

project template specified in templateProjectId.

Used only with POST /projects/from-template/.

Boolean — — —

copyRevenueRecognition

AutoSettings

A 1/0 field indicating whether to copy the

project revenue recognition autorun settings

associated with the project or project template

specified in templateProjectId. Used only with

POST /projects/from-template/.

Boolean — — —

copyRevenueRecognition

Rules

A 1/0 field indicating whether to copy the

project revenue recognition rules associated

with the project or project template specified

in templateProjectId. Used only with POST /

projects/from-template/.

Boolean — — —

costCenterId The internal ID of the cost center associated

with the project.

integer($int64) — Yes Yes

created The date the project was created. string($date-

time)

Yes Yes —

creditInvoiceLayoutId The internal ID of the credit memo (negative

invoice) layout associated with the project.

integer($int64) — Yes Yes

currency The currency for monetary values in the project

record. Three-letter currency code.

string — Yes —

customerId The internal ID of the customer associated with

the project .

integer($int64) — Yes Yes

REST API

Projects 141

Property Description Type Read-only Query allowed Sorting

allowed

dashboardFrom The item that determines if the dashboard is

enabled.

Possible values:

■

S — Project stage

■

P — Project

string — Yes —

dashboardMessage The dashboard message. string — Yes —

expenseAllowance

ApprovalProcess

The internal ID of the approval process

for allowance reports associated with

the project. Mutually exclusive with

expenseAllowanceApprover.

integer($int64) — Yes —

expenseAllowance

Approver

The internal ID of the User who approves

allowance reports associated with the project,

if a single approver process is used. Mutually

exclusive with expenseAllowanceApproval

Process.

Other possible values:

■

-1 — the allowance report owner’s manager.

■

-2 — the manager of the allowance report

owner’s manager.

■

-3 — the project owner.

■

-4 — self (allowance report owner).

integer($int64) — Yes —

expenseApprovalProcess The internal ID of the approval process for

expense reports associated with the project.

Mutually exclusive with expenseApprover.

integer($int64) — Yes —

expenseApprover The internal ID of the User who approves

expense reports associated with the project.,

if a single approver process is used. Mutually

exclusive with expenseApprovalProcess.

Other possible values:

■

-1 — the expense report owner’s manager.

■

-2 — the manager of the expense report

owner’s manager.

■

-3 — the project owner.

■

-4 — self (expense report owner).

integer($int64) — Yes —

expenseAuthorization

ApprovalProcess

The internal ID of the approval process

for expense authorizations associated

with the project. Mutually exclusive with

expenseAuthorizationApprover.

integer($int64) — Yes —

expenseAuthorization

Approver

The internal ID of the User who approves

expense authorizations associated with the

project, if a single approver process is used.

Mutually exclusive with expenseAuthorization

ApprovalProcess.

Other possible values:

■

-1 — the expense authorization owner’s

manager.

■

-2 — the manager of the expense

authorization owner’s manager.

■

-3 — the project owner.

■

-4 — self (expense authorization owner).

integer($int64) — Yes —

externalId The unique external ID of the project, if the

record was imported from an external system.

string — Yes Yes

REST API

Projects 142

Property Description Type Read-only Query allowed Sorting

allowed

filterSets The filter sets associated with this project. Array

of internal IDs for filter sets.

Users who have access to any of the filter sets

associated with the project have accessto the

project. Required if the Require a filter set

selection when adding or editing project

box is checked on the filter ste setting sform

in OpenAir (Administration > Global Settings >

Account > Filter Set Settings).

Array of {”id”:

} objects.

— Yes —

finishDate The calculated finish date of the project. string($date) Yes Yes Yes

hierarchyNodes The hierarchy nodes associated with this

project. Array of internal IDs for hierarchy

nodes.

Only hierarchy nodes associated with a

hierarchy that is shown on the project property

form (Show this hierarchy when editing

projects box checked on the hierarchy entity

form in OpenAir) are included.

Array of {”id”:

} objects.

— Yes —

id The unique internal identifier of the project. integer($int64) Yes — Yes

invoiceApprovalProcess The internal ID of the approval process for

invoices associated with the project. Mutually

exclusive with invoiceApprover.

integer($int64) — Yes —

invoiceApprover The internal ID of the User who approves

invoices associated with the project, if a single

approver process is used. Mutually exclusive

with invoiceApprovalProcess.

Other possible values:

■

-1 — the invoice owner’s manager.

■

-2 — the manager of the invoice owner’s

manager.

■

-3 — the project owner.

■

-4 — self.

integer($int64) — Yes —

invoiceLayoutId The internal ID of the invoice layout associated

with the project.

integer($int64) — Yes Yes

invoiceText Text to display on every invoice. string — Yes —

isActive A 1/0 field indicating if the project is active. Boolean — Yes Yes

isAutoBill A 1/0 field indicating if the project can be billed

automatically. Available only if project billing

rules are not used.

Boolean — Yes —

isAutoBillCap A 1/0 field indicating if there is a cap on the

amount that can be billed automatically for the

project. Available only if project billing rules are

not used.

Boolean — Yes —

isAutoBillOverriden A 1/0 field indicating if the project-specific

autobilling settings should be used instead

of account-wide autobilling settings. Project-

specific autobilling settings are held in the

auto_bill table. Available only if project billing

rules are not used.

Boolean — Yes —

isDashboardEnabled A 1/0 field indicating if the project dashboard is

enabled, when dashboardFrom is set to P.

Boolean — Yes Yes

isPortfolioProject A 1/0 field indicating if the project is a portfolio

project.

Boolean — Yes —

mspLinkType The Microsoft Project import status.

Possible values:

string — Yes —

REST API

Projects 143

Property Description Type Read-only Query allowed Sorting

allowed

■

Empty value — Not imported

■

I — Imported and locked for edit

■

U — Imported and open for edit

name [REQUIRED] The name of the project task. string — Yes Yes

newsFeedId The internal ID of the news feed associated with

the project.

integer($int64) — Yes Yes

notes Notes about the project. string — Yes —

notifyAssignees A 1/0 field indicating whether to send

notification email to assigned employees when

a task associated with the project is added,

modified, or deleted.

Boolean — Yes —

notifyAssignmentCc A comma-delimited list of internal IDs of

employees to be copied (Cc) into assignment

notification email.

Other possible listed values:

■

-1 — the assignee’s manager.

■

-2 — the manager of the assignee’s

manager.

■

-3 — the project owner.

■

-5 — the customer owner.

string — Yes —

notifyIssueAssignedTo A 1/0 field indicating whether to send

notification email to the assigned employee

when an issue is assigned to an employee.

Boolean — Yes —

notifyIssueClosed

AssignedTo

A 1/0 field indicating whether to send

notification email to the assigned employee

when an issue is progressed to a closed issue

stage.

Boolean — Yes —

notifyIssueClosed

CustomerOwner

A 1/0 field indicating whether to send

notification email to the customer owner when

an issue is progressed to a closed issue stage.

Boolean — Yes —

notifyIssueClosed

ProjectOwner

A 1/0 field indicating whether to send

notification email to the project owner when an

issue is progressed to a closed issue stage.

Boolean — Yes —

notifyIssueCreated

CustomerOwner

A 1/0 field indicating whether to send

notification email to the customer owner when

an issue is created.

Boolean — Yes —

notifyIssueCreated

ProjectOwner

A 1/0 field indicating whether to send

notification email to the project owner when an

issue is created.

Boolean — Yes —

notifyOwner A 1/0 field indicating whether to send

notification email to the project owner when

ownership is changed.

Boolean — Yes —

notifySrSubmitted

ProjectOwner

A 1/0 field indicating whether to send

notification email to the project owner when a

schedule request is submitted for a user booked

or assigned to the project.

Boolean — Yes —

onlyOwnerCanEdit A 1/0 field indicating whether only the project

owner can edit this project.

Boolean — Yes —

payrollTypeFilter A comma-delimited list of internal IDs of payroll

types against which time can be booked for the

project.

string — Yes —

portfolioProjectId The internal ID of the portfolio project

associated with the project, if the project is a

subordinate project.

integer($int64) — Yes Yes

REST API

Projects 144

Property Description Type Read-only Query allowed Sorting

allowed

projectApprover1 The internal ID of the first project approver

[User] that is substituted into the approval

processes.

Other possible value:

■

-6 — the first additional project approver.

integer($int64) — Yes —

projectApprover2 The internal ID of the second project approver

[User] that is substituted into the approval

processes.

Other possible value:

■

-7 — the second additional project approver.

integer($int64) — Yes —

projectApprover3 The internal ID of the third project approver

[User] that is substituted into the approval

processes.

Other possible value:

■

-8 — the third additional project approver.

integer($int64) — Yes —

projectLocationId The internal ID of the project location associated

with the project.

integer($int64) — Yes Yes

projectStageId The internal ID of the project stage associated

with the project.

integer($int64) — Yes Yes

purchaseOrderApproval

Process

The internal ID of the approval process for

purchase orders associated with the project.

Mutually exclusive with purchaseOrderApprover.

integer($int64) — Yes —

purchaseOrderApprover The internal ID of the User who approves

purchase orders associated with the project,

if a single approver process is used. Mutually

exclusive with purchaseOrderApprovalProcess.

Other possible values:

■

-1 — the purchase order owner’s manager.

■

-2 — the manager of the purchase order

owner’s manager.

■

-3 — the project owner.

■

-4 — self (purchase order owner).

integer($int64) — Yes —

purchaseRequest

ApprovalProcess

The internal ID of the approval process

for purchase requests associated with

the project. Mutually exclusive with

purchaseRequestApprover.

integer($int64) — Yes —

purchaseRequest

Approver

The internal ID of the User who approves

purchase requests associated with the project,

if a single approver process is used. Mutually

exclusive with purchaseRequestApprovalProcess.

Other possible values:

■

-1 — the purchase request owner’s

manager.

■

-2 — the manager of the purchase request

owner’s manager.

■

-3 — the project owner.

■

-4 — self (purchase request owner).

integer($int64) — Yes —

rate The hourly billing rate for the project. number($float) — Yes —

rateCardId The rate card to be used for projected billing, if

not zero.

integer($int64) — Yes Yes

REST API

Projects 145

Property Description Type Read-only Query allowed Sorting

allowed

revenueApprovalProcess The internal ID of the revenue container

approval process for the project. Mutually

exclusive with revenueApprover.

integer($int64) — Yes —

revenueApprover The internal ID of the employee who approves

revenue containers for the project, if a single

approver process is used. Mutually exclusive

with revenueApprovalProcess.

Other possible values:

■

-1 — the revenue container owner’s

manager.

■

-2 — the manager of the container owner’s

manager.

■

-3 — the project owner.

■

-4 — self.

integer($int64) — Yes —

sgaLabor The allocated cost (SG and A) overhead

percentage applied to labor for profitability

analysis.

number($float) — Yes —

shippingContactId The internal ID of the shipping contact

associated with the project, if different from the

designated shipping contact for the customer.

integer($int64) — Yes —

soldToContactId The internal ID of the sold to contact associated

with the project, if different from the designated

sold to contact for the customer.

integer($int64) — Yes —

startDate The scheduled start date of the project. string($date) — Yes Yes

syncWorkspace A 1/0 field indicating whether to synchronize

the project resources with membership of the

workspace associated with the project.

Boolean — Yes —

taskBudgetCost The total projected cost across all tasks in the

project, if task budgeting is enabled.

number($float) Yes Yes —

taskBudgetRevenue The total projected billing across all tasks in the

project, if task budgeting is enabled.

number($float) Yes Yes —

taxLocationId The internal ID of the of the tax location

associated with the project.

integer($int64) — Yes Yes

taxRateFederal The federal tax rate for the project. number($float) — Yes —

taxRateState The state/HST tax rate for the project. number($float) — Yes —

templateProjectId The internal ID of the project or project

template to be copied. Used only with POST /

projects/from-template/.

integer($int64) — — —

timesheetApproval

Process

The internal ID of the approval process for

timesheets associated with the project. Mutually

exclusive with timesheetApprover.

integer($int64) — Yes —

timesheetApprover The internal ID of the User who approves

timesheets associated with the project, if a

single approver process is used. Mutually

exclusive with timesheetApprovalProcess.

Other possible values:

■

-1 — the timesheet owner’s manager.

■

-2 — the manager of the timesheet owner’s

manager.

■

-3 — the project owner.

■

-4 — self (timesheet owner).

integer($int64) — Yes —

REST API

Projects 146

Property Description Type Read-only Query allowed Sorting

allowed

timetypeFilter A comma-delimited list of internal IDs of time

types against which time can be booked for the

project.

string — Yes —

updated The date the project was last updated or

modified.

string($date-

time)

Yes Yes —

userFilter A comma-delimited list of internal IDs of

employees who can edit the project.

string — Yes —

userId The internal ID of the employee associated with

the project — the project owner.

integer($int64) — Yes Yes

Note: Access to certain object types and object attributes depend on the business logic

configured for the OpenAir account. It may vary depending on the role and access privileges

associated with the access token and with the user who authorized the application.

Required and read-only attributes also depend on the business logic configured for each specific

OpenAir account. Some fields such as id, created, and updated are system-generated and always

read-only.

Insert a Project

POST /projects/ — Use this method to create a new project.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

returned.

string

filterSetId Optional The internal ID of the filter set to be applied. integer

REST API

Projects 147

Path parameter Required /

Optional

Description Type

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

return_object Optional If set to any value other than 0 (zero), the response will return

the project created. Otherwise, the response will include only the

internal ID of the project created.

Boolean

Request body

The Project object to be created. The object must include valid key-value pairs for all required attributes

and cannot include key-value pairs for read-only attributes. For information about the Project object

model, see Project object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Project object created, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the internal ID of the project created.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/projects/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

REST API

Projects 148

{

"attachments": [{"id": 6459}],

"budget": 500000,

"contactId": 537,

"currency": "EUR",

"customerId": 489,

"finishDate": "2022-12-31",

"name": "Hardware deployment",

"userId": 174

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 2689

}

"message": "success"

}

Insert Multiple Projects

POST /projects/bulk/ — Use this method to create new projects.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

returned.

string

REST API

Projects 149

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return

the project created. Otherwise, the response will include only the

internal ID of the project created.

Boolean

Request body

The Project objects to be created. Each object must include valid key-value pairs for all required

attributes and cannot include key-value pairs for read-only attributes. For information about the Project

object model, see Project object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Project objects created, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the internal ID of the project created.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

If your request includes multiple projects, both valid and invalid, the request will complete successfully

for valid projects and return an error message for invalid projects — e.g. "Access to Project #372

denied". The response status will be 207 Multiple statuses returned.

REST API

Projects 150

Property Description

If your request more than 100 projects, an error is returned — e.g. "Bulk action limit reached, sent

101 entities of 100 allowed".

Sample request

POST /rest/v1/projects/bulk?return_object=1 HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"1": {

"attachments": [{"id": 6459}],

"budget": 500000,

"contactId": 537,

"currency": "EUR",

"customerId": 489,

"name": "Hardware deployment",

"userId": 174

"2": {

"attachments": [{"id": 6475}],

"budget": 300000,

"contactId": 537,

"currency": "EUR",

"customerId": 489,

"startDate": "2022-12-31",

"name": "Software deployment",

"userId": 174

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"message": "Multiple statuses returned"

"data": [{

"1": {

"message": "Bad data",

"errorFields": {

"startDate":[{

"type": "required-field",

"message": "Required field Start date (DD/MM/YYYY)"

}]

}

"2": {"message": "success", "data": [{"id": 123}]}

}]

}

Create a Project from Template

POST /projects/from-template/ — Use this method to create a new project from another project or from

a project template.

REST API

Projects 151

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return

the project created. Otherwise, the response will include only the

internal ID of the project created.

Boolean

Request body

The Project object to be created. The object must include valid key-value pairs for all required attributes

and cannot include key-value pairs for read-only attributes. For information about the Project object

model, see Project object properties.

The following properties are specific to the POST /projects/from-template/ method. The internal ID of

the template project (templateProjectId) must be included.

Property Description Type Optional /

Required

Query allowed

copyApprovers A 1/0 field indicating whether to copy the project

approvers associated with the project or project

template specified in templateProjectId. Used only

with POST /projects/from-template/.

Boolean Optional —

REST API

Projects 152

Property Description Type Optional /

Required

Query allowed

copyBookings A 1/0 field indicating whether to copy the bookings

associated with the project or project template

specified in templateProjectId. Used only with

POST /projects/from-template/.

Boolean Optional —

copyCpExcludeFilters A 1/0 field indicating whether to copy the

customers and projects to exclude from

denominator when calculating user allocation

% from the project or project template specified

in templateProjectId. Used only with POST /

projects/from-template/.

Boolean — —

copyCustomFields A 1/0 field indicating whether to copy the custom

field values from the project or project template

specified in templateProjectId. Used only with

POST /projects/from-template/.

Boolean Optional —

copyDashboardSettings A 1/0 field indicating whether to copy the

dashboard settings from the project or project

template specified in templateProjectId. Used only

with POST /projects/from-template/.

Boolean Optional —

copyExpensePolicy A 1/0 field indicating whether to copy the expense

policy associated with the project or project

template specified in templateProjectId. Used only

with POST /projects/from-template/.

Boolean Optional —

copyInvoiceLayoutSettings A 1/0 field indicating whether to copy the invoice

layout settings associated with the project or

project template specified in templateProjectId.

Used only with POST /projects/from-template/.

Boolean Optional —

copyIssues A 1/0 field indicating whether to copy the issues

associated with the project or project template

specified in templateProjectId. Used only with

POST /projects/from-template/.

Boolean Optional —

copyLoadedCost A 1/0 field indicating whether to copy the loaded

costs from the project or project template specified

in templateProjectId. Used only with POST /

projects/from-template/.

Boolean Optional —

copyNotificationSettings A 1/0 field indicating whether to copy the

notification settings from the project or project

template specified in templateProjectId. Used only

with POST /projects/from-template/.

Boolean Optional —

copyProjectAssignment

Profiles

A 1/0 field indicating whether to copy the project

assignment profiles associated with the project or

project template specified in templateProjectId.

Used only with POST /projects/from-template/.

Boolean Optional —

copyProjectBillingAuto

Setting

A 1/0 field indicating whether to copy the

automated project autobilling settings from

the project or project template specified in

templateProjectId. Used only with POST /

projects/from-template/.

Boolean Optional —

copyProjectBillingRules A 1/0 field indicating whether to copy the project

billing rules associated with the project or project

template specified in templateProjectId. Used only

with POST /projects/from-template/.

Boolean Optional —

copyProjectBudgetGroups A 1/0 field indicating whether to copy the project

budget groups associated with the project or

project template specified in templateProjectId.

Used only with POST /projects/from-template/.

Boolean Optional —

REST API

Projects 153

Property Description Type Optional /

Required

Query allowed

copyProjectPricing A 1/0 field indicating whether to copy the project

pricing associated with the project or project

template specified in templateProjectId. Used only

with POST /projects/from-template/.

Boolean Optional —

copyRevenueRecognition

AutoSettings

A 1/0 field indicating whether to copy the project

revenue recognition autorun settings associated

with the project or project template specified

in templateProjectId. Used only with POST /

projects/from-template/.

Boolean Optional —

copyRevenueRecognition

Rules

A 1/0 field indicating whether to copy the

project revenue recognition rules associated

with the project or project template specified

in templateProjectId. Used only with POST /

projects/from-template/.

Boolean Optional —

templateProjectId The internal ID of the project or project template to

be copied. Used only with POST /projects/from-

template/.

integer

($int64)

Required —

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Project objects created, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the internal ID of the project created.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/projects/from-template?return_object=1 HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

REST API

Projects 154

Authorization: Bearer <OAuth2_access_token>

{

"name": "New project copied from template",

"customerId": 1,

"hierarchyNodes": [{"id": 72}],

"filterSets": [{"id": 2}, {"id": 3}],

"templateProjectId": 7,

"startDate": "2022-12-31",

"copyProjectBillingRules": 1,

"copyProjectBillingAutoSetting": 1,

"copyProjectPricing": true,

"copyCustomFields": true,

"copyLoadedCost": true,

"copyApprovers": true,

"copyIssues": true,

"copyNotificationSettings": true,

"copyDashboardSettings": true,

"copyInvoiceLayoutSettings": true,

"copyBookings": true,

"copyProjectBudgetGroups": true,

"copyExpensePolicy": true,

"copyProjectAssignmentProfiles": true,

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"message": "success",

"data": [{

"id": 123

}]

}

Get the List of Projects

GET /projects/ — Use this method to retrieve the list of projects.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

returned. Response Data Modifiers.

string

REST API

Projects 155

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the projects requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/projects/ HTTP/1.1

Host: company-id.app.openair.com

REST API

Projects 156

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

...

{

...

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

"type": "attachment"

}

"userId": {

"data": {

"id": 54,

"type": "userDisplayName"

}

...

"rowsPerPage": 100,

"totalPages": 14,

"totalRows": 1386,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/projects"

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/projects"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/projects?limit=100&offset=100"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/projects?limit=100&offset=1300"

}

]

}

Get a Project

GET /projects/{id} — Use this method to retrieve the project with the specified internal ID.

REST API

Projects 157

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

task returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the project task requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “ProjectTask #237 not

found”.

REST API

Projects 158

Property Description

Note: The project task record with the internal ID {id} must have the task classification

field set to Task in OpenAir. If the project task record corresponds to a milestone or a phase,

the API return an error with message “ProjectTask #{id} not found”.

Sample request

GET /rest/v1/projects/2438?fields=attachments,budget,contactId,created,currency,customerId,finishDate,id,name,userId HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"attachments": [{"id": 6459} ],

"budget": 500000,

"contactId": 537,

"created": "2020-10-22 07:08:36",

"currency": "EUR",

"customerId": 489,

"finishDate": "2022-12-31",

"id": 2438,

"name": "Hardware deployment",

"userId": 174

}

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": { "type": "attachments", "id": 6459 }

"userId": {

"data": { "type": "userDisplayName", "id": 174 }

}

"rowsPerPage": 100,

"totalPages": 1,

"totalRows": 1,

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/projects/2438?fields=attachments,budget,contactId,created,cur

rency,customerId,finishDate,id,name,userId"

}

]

}

Update a Project

PUT /projects/ — Use this method to update the project with the specified internal ID.

REST API

Projects 159

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return

the project created. Otherwise, the response will include only the

internal ID of the project created.

Boolean

Request body

An object including valid key-value pairs for the fields to be updated. The object cannot include key-

value pairs for read-only attributes. For information about the Project object model, see Project object

properties.

Response definitions

A successful request returns a JSON object with the following properties:

REST API

Projects 160

Property Description

data An array containing one of the following:

■

The Project object created, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the internal ID of the project created.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

PUT /rest/v1/projects/2689 HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"budget": 800000,

"contactId": 1579,

"currency": "CAD",

"customerId": 489,

"finishDate": "2023-12-31",

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 2689

}

"message": "success"

}

Update Multiple Projects

PUT /projects/bulk/{ids} — Use this method to update projects with the specified internal IDs.

REST API

Projects 161

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return

the project created. Otherwise, the response will include only the

internal ID of the project created.

Boolean

Request body

An object with key-value pairs for each project to be updated. For each project, the key is the project

internal ID and the value is an object including valid key-value pairs for the fields to be updated. The

project objects cannot include key-value pairs for read-only attributes. For information about the Project

object model, see Project object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

REST API

Projects 162

Property Description

■

The Project object created, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the internal ID of the project created.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

If your request includes multiple projects, both valid and invalid, the request will complete successfully

for valid projects and return an error message for invalid projects — e.g. "Access to Project #372

denied". The response status will be 207 Multiple statuses returned.

If your request more than 100 projects, an error is returned — e.g. "Bulk action limit reached, sent

101 entities of 100 allowed".

Sample request

PUT /rest/v1/projects/bulk?return_object=1 HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"367" : {

"name": "Updated project name",

"customerId": 108,

"filterSets": [{"id": 2}, {"id": 3}]

"673": {

"name": "Another updated project",

"customerId": 11,

"startDate": "2023-01-01"

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"message": "Multiple statuses returned"

"data": [{

"367": {

REST API

Projects 163

"message": "Bad data",

"errorFields": {

"customerId":[{

"type": "read-only-value",

"message": "Read-only value"

}]

}

"673": {"message": "success", "data": [{"id": 18}]}

}]

}

Delete a Project

DELETE /projects/{id} — Use this method to delete the project record with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Project

#237 not found”.

Sample request

DELETE /rest/v1/projects/237 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

REST API

Projects 164

Sample response

{

"data": [

{

"id": 237

}

"message": "success"

}

Delete Multiple Projects

DELETE /projects/bulk/{ids} — Use this method to delete the project records with the specified internal

IDs.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{ids} Required A comma-separated list of internal IDs for projects. The

list must not include more than 100 project IDs.

integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success”.

If your request includes multiple project IDs, both valid and invalid, the request will complete

successfully for valid project IDs and return an error message for invalid project IDs — e.g. "Access to

Project #372 denied". The response status will be 207 Multiple statuses returned.

If your request more than 100 project IDs, an error is returned — e.g. "Bulk action limit reached,

sent 101 entities of 100 allowed".

REST API

Projects 165

Sample request

DELETE /rest/v1/projects/bulk/237,327,372 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"1": {

"data": [ {"id": "237"}],

"message": "success"

"2": {

"data": [ {"id": "327"}],

"message": "success"

"3": {

"data": [ {"id": "372"}],

"message": "success"

}

"message": "success"

}

Add an Attachment to a Project

POST /projects/{id}/attachments — Use this method to add an attachment to the project with the

specified internal ID. This method can be used for any of the following cases:

■

Create a new attachment and associate it with the project.

■

Associate a workspace document with the project. Workspace documents are Attachment objects

associated with a custom workspace.

Note: If the Attachment Thumbnail and Attachment Viewer feature is enabled for your OpenAir

account, a thumbnail is generated automatically when you add an attachment of a supported

format. The file_name must be included in the request and must include a supported file

extension. For more information about the Attachment Thumbnail feature, including supported file

format and filename extensions, see Optional Features.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

REST API

Projects 166

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment returned. For the Attachment object properties, see

Attachment object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

attachment created. Otherwise, the response will include only the

internal ID of the attachment created.

Boolean

Request body

This method accepts either one of the content types described in the following table:

Content-Type header Body Use case

multipart/form-data Form data with the following key-value pair:

■

file — The file to be uploaded. The file

and file metadata will be used to create

the new Attachment object.

■

Create a new attachment and

associate it with the project.

application/json JSON object with the following key-value pair:

■

id — The internal ID of the workspace

document to be associated with the

project.

■

Associate a workspace document

with the project.

Response definitions

A successful request returns a JSON object with the following properties:

REST API

Projects 167

Property Description

data An array containing one of the following:

■

The Attachment object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the attachment created.

See Returned Data. For the Attachment object properties, see Attachment object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/projects/237/attachments/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: multipart/form-data boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Authorization: Bearer <OAuth2_access_token>

----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"

@C:\Users\mcollins\Desktop\2020-12-08_18-47-31.png

----WebKitFormBoundary7MA4YWxkTrZu0gW

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

Get the List of Attachments Associated with a Project

GET /projects/{id}/attachments — Use this method to retrieve the list of attachments associated with

the project with the specified internal ID.

REST API

Projects 168

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for each

attachment returned. Response Data Modifiers. For information

about Attachment object properties, see Attachment object

properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the list of attachments associated with the project with the specified internal

ID. See Returned Data. For information about Attachment object properties, see Attachment object

properties.

REST API

Projects 169

Property Description

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Project #237 not found”.

Sample request

GET /rest/v1/projects/237/attachments/?fields=fileName,isLocked,uploadedBy,size,id,fileType HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"fileName": "2020-11-20_13-25-06.png",

"isLocked": false,

"id": 4982,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 114659

{

"fileName": "2020-12-08_14-46-24.png",

"isLocked": false,

"id": 56,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 123754

"message": "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

{

REST API

Projects 170

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

"rowsPerPage": 100,

"totalPages": 1,

"totalRows": 2,

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/projects/237/attachments"

}

]

}

Get an Attachment Associated with a Project

GET /projects/{id}/attachments/{attachment_id} — Use this method to retrieve the attachment record

with the specified attachment ID associated with the project with the specified internal ID. The response

contains the attachment metadata only and not the file.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment metadata returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

REST API

Projects 171

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the attachment metadata requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Attachment #598 not

found”.

Sample request

GET projects/237/attachments/4982?fields=fileName,isLocked,uploadedBy,size,id,fileType HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"fileName": "2020-11-20_13-25-06.png",

"isLocked": false,

"id": 4982,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 114659

}

"message": "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

]

}

REST API

Projects 172

}

Get an Attachment File Associated with a Project

GET /projects/{id}/attachments/{attachment_id}/download — Use this method to retrieve the file

associated with the attachment record with the specified attachment ID associated with the project with

the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#598 not found”.

A successful request also returns the attachment file.

Sample request

GET projects/237/attachments/4982/download HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

REST API

Projects 173

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The attachment file.

Get the Thumbnail for an Attachment Associated with a

Project

GET /projects/{id}/attachments/{attachment_id}/thumbnail — Use this method to retrieve the

thumbnail file associated with the attachment record with the specified attachment ID associated with the

project with the specified internal ID. Available only if the Attachment Thumbnail feature is enabled for

your OpenAir account.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#598 not found” or “Attachment #213 thumbnail not found”.

REST API

Projects 174

A successful request also returns the attachment thumbnail file.

Sample request

GET projects/237/attachments/4982/thumbnail HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The attachment thumbnail file.

Replace an Attachment to a Project

PUT /projects/{id}/attachments/{attachment_id} — Use this method to replace an attachment to the

project with the specified internal ID.

Important: This method can only be used to replace an attachment directly associated with the

project. It cannot be used for workspace document associated with the project either to replace

the workspace document or to associate a different workspace document in its place.

Note: If the Attachment Thumbnail and Attachment Viewer feature is enabled for your OpenAir

account, a thumbnail is generated automatically when you add an attachment of a supported

format. The file_name must be included in the request and must include a supported file

extension. For more information about the Attachment Thumbnail feature, including supported file

format and filename extensions, see Optional Features.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

REST API

Projects 175

Path parameter Required /

Optional

Description Type

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment returned. For the Attachment object properties, see

Attachment object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

attachment created. Otherwise, the response will include only the

internal ID of the attachment created.

Boolean

Request body

This method accepts the following content type:

Content-Type header Body

multipart/form-data Form data with the following key-value pair:

■

file — The file to be uploaded. The file and file metadata will be used to replace

the existing Attachment object with a new Attachment object.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Attachment object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the attachment created.

REST API

Projects 176

Property Description

See Returned Data. For the Attachment object properties, see Attachment object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

PUT /rest/v1/projects/237/attachments/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: multipart/form-data boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Authorization: Bearer <OAuth2_access_token>

----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"

@C:\Users\mcollins\Desktop\2020-12-08_18-47-31.png

----WebKitFormBoundary7MA4YWxkTrZu0gW

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

Delete an Attachment Associated with a Project

DELETE /projects/{id}/attachments/{attachment_id} — Use this method to delete the attachment

with the specified attachment ID associated with the project with the specified internal ID, or clear the

association between the workspace document with the specified attachment ID and the project with the

specified internal ID.

REST API

Projects 177

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#4985 not found”.

Sample request

DELETE /rest/v1/projects/237/attachments/4982 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

REST API

Projects 178

Delete Attachments Associated with a Project

DELETE /projects/{id}/attachments/{attachment_ids} — Use this method to delete attachments

with the specified attachment IDs associated with the project with the specified internal ID, or clear the

association between the workspace document with the specified attachment ID and the project with the

specified internal ID.

Parameters

Path parameters

Path parameter Required /

Optional

Description Type

{id} Required The internal ID of the project. integer

{attachment_ids} Required A comma-separated list of internal IDs for the

attachments. The list must not include more than

1000 attachment IDs.

integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message If your request includes multiple attachment IDs, both valid and invalid, the request will complete

successfully for valid attachment IDs and return an error message for invalid attachment IDs — e.g.

"Access to Attachment #693 denied". The response status will be 207 Multiple statuses returned.

If your request more than 1,000 attachment IDs, an error is returned — e.g. "Bulk action limit

reached, sent 1001 entities of 1000 allowed".

Sample request

DELETE /rest/v1/projects/237/attachments/4982,4983 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

REST API

Projects 179

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"4982" : {

"data": [{

"id": "4982"

}],

"message": "success"

"4983" : {

"data": [{

"id": "4983"

}],

"message": "success"

}

"message": "success"

}

Discover Available Methods and Fetch the Endpoint

Reference for Projects

OPTIONS /projects/ — Use this method to discover the methods available and fetch the OpenAPI 3.0

JSON endpoint reference for projects.

Parameters

None

Response definitions

A successful request returns the OpenAPI 3.0 JSON endpoint reference in the response body. The

JSON object returned contains metadata information about the resource endpoint. It is similar to the

Generated API Documentation JSON, only it is restricted to the resource endpoint path specified in the

request.

The response also includes the following header:

Header Description

Access-Control-Allow-Methods A comma-separated list of HTTP methods available for the requested

resource collection endpoint.

Sample request

OPTIONS /rest/v1/projects/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

REST API

Projects 180

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The response includes the OpenAPI 3.0 endpoint reference for the resource endpoint as a JSON object in

the response body, as well as the following headers:

Content-Type: application/json; charset=utf-8

Content-Length: 6955

Connection: keep-alive

Cache-control: no-cache, no-store, pre-check=0, post-check=0, must-revalidate, max-age=0, s-max-age=0

Pragma: no-cache

Expires: 0

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, OPTIONS

Access-Control-Allow-Headers: Content-Type

Access-Control-Max-Age: 86400

Vary: Accept-Encoding,User-Agent

Content-Encoding: gzip

Project Milestones

Project milestones are reference points in your project life cycle that marks a significant event or goal the

to be completed as part of a project. It includes information about the work to be done, when, by whom,

and at what cost.

Note: The /project-milestones/ endpoint can only be used for project task records with

the task classification field set to Milestone in OpenAir. This is equivalent to records with the

classification property set to M in the project_task table, or in the XML API Projecttask or SOAP

API oaProjecttask datatypes.

For Tasks — project task records with zero duration and the task classification field set to

Milestone in OpenAir, or the classification property set to T in the project_task table, or in the

XML API Projecttask or SOAP API oaProjecttask datatypes — see Project Tasks.

For Phases — project task records that have other project tasks nested under and the task

classification field set to Phase in OpenAir, or the classification property set to P in the

project_task table, or in the XML API Projecttask or SOAP API oaProjecttask datatypes — see

Project Phases.

Available methods

■

GET /project-milestones/ — Get the List of Project Milestones

■

GET /project-milestones/{id} — Get a Project Milestone

ProjectMilestone Object Properties

A project milestone is a reference point in your project life cycle that marks a significant event or goal the

to be completed as part of a project. It includes information about the work to be done, when, by whom,

and at what cost.

REST API

Project Milestones 181

The ProjectMilestone object has the following properties:

Name Description Type Read-Only Query

Allowed

Sorting

Allowed

attachments The attachments associated

with this milestone. Array of

internal IDs for attachment

objects.

Array of {”id”: <

integerValue>}

objects.

Yes — —

calculatedStarts Calculated start date of the

project milestone. If the use

task estimating feature is

turned on, this field will have

the estimated total time the

task will take to complete.

If zero, no estimating has

occurred so the estimate is

the same as the plan.

string($date) Yes Yes —

created Time the record was created. string($date-time) Yes Yes Yes

currency Currency for the money fields

in the record. This should

be the same as the project

currency.

string Yes Yes Yes

customerId The ID of the associated

customer.

integer($int64) Yes Yes Yes

defaultCategory The category to assign to a

timesheet entry assigned to

this task. The feature has to be

enabled for this assignment to

work.

string — Yes Yes

defaultCategory1 A feature, if enabled, would

assign this default_category_1

to the category_1 for

many transactions that

have a category_1_id and

project_task_id by searching

the project_task and project

work breakdown structure for

the first default_category_1

defined.

string — Yes Yes

defaultCategory2 A feature, if enabled, would

assign this default_category_1

to the category_1 for

many transactions that

have a category_1_id and

project_task_id by searching

the project_task and project

work breakdown structure for

the first default_category_1

defined.

string — Yes Yes

defaultCategory3 A feature, if enabled, would

assign this default_category_1

to the category_1 for

many transactions that

have a category_1_id and

string — Yes Yes

REST API

Project Milestones 182

Name Description Type Read-Only Query

Allowed

Sorting

Allowed

project_task_id by searching

the project_task and project

work breakdown structure for

the first default_category_1

defined.

defaultCategory4 A feature, if enabled, would

assign this default_category_1

to the category_1 for

many transactions that

have a category_1_id and

project_task_id by searching

the project_task and project

work breakdown structure for

the first default_category_1

defined.

string — Yes Yes

defaultCategory5 A feature, if enabled, would

assign this default_category_1

to the category_1 for

many transactions that

have a category_1_id and

project_task_id by searching

the project_task and project

work breakdown structure for

the first default_category_1

defined.

string — Yes Yes

externalId If the record was imported

from an external system you

store the unique external

record ID here.

string — Yes Yes

id Unique ID. Automatically

assigned by the system

integer($int64) Yes Yes Yes

idNumber User-defined milestone ID. integer($int64) — Yes Yes

isClosed A 1/0 field indicating if this is

closed milestone.

Boolean — Yes Yes

isNonBillable If set to 1, this is not billable.

This is only applicable for

project billing rules.

Boolean — Yes Yes

name Short description of this

milestone.

string — Yes Yes

notes Notes associated with the

project milestone.

string — Yes Yes

parentId The ID of our immediate

ancestor. If zero or null, this is

a project-level (top-level) task

or phase.

integer($int64) — Yes Yes

predecessors Comma delimited list of task

IDs which must complete

before this milestone can

start.

string Yes Yes —

REST API

Project Milestones 183

Name Description Type Read-Only Query

Allowed

Sorting

Allowed

predecessorsLag Comma delimited list for

task ID:days of lag time for

predecessors. Only populated

if there is a lag time.

string Yes Yes —

predecessorsType Comma delimited list of

task ID:relationship type for

predecessors. Only populated

if the relationship type is not

finish-to-start.

string Yes Yes —

priority The priority of the milestone (1

- 9).

integer($int64) — Yes Yes

projectId The ID of the associated

project.

integer($int64) Yes Yes Yes

projectTaskType

The ID of the associated

projecttask_type. Not for

milestones.

integer($int64) — Yes Yes

seq The sequence number of this

task.

integer($int64) Yes Yes Yes

startDate Optional scheduled starting

date of this task. Overrides

computed date Start_date.

string($date) — Yes Yes

updated Time the record was last

updated or modified

string($date-time) Yes Yes Yes

useAllCanAssign Is everyone able to assign

time/expenses to this task.

Boolean — Yes Yes

Get the List of Project Milestones

GET /project-milestones/ — Use this method to retrieve the list of project milestones.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

milestones returned. Response Data Modifiers.

string

REST API

Project Milestones 184

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the project milestones requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/project-milestones/ HTTP/1.1

REST API

Project Milestones 185

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

...

{

...

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

"type": "attachment"

}

...

"rowsPerPage": 100,

"totalPages": 14,

"totalRows": 1386,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/project-milestones"

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/project-milestones"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/project-milestones?limit=100&offset=100"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/project-milestones?limit=100&offset=1300"

}

]

}

Get a Project Milestone

GET /project-milestones/{id} — Use this method to retrieve the project milestone with the specified

internal ID.

REST API

Project Milestones 186

Parameters

Path parameters

Path parameter Required /

Optional

Description Type

{id} Required The internal ID of the project milestone.

Note: The project milestone record with the

internal ID {id} must have the task classification

field set to Milestone in OpenAir.

integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

milestone returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the project milestone requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

REST API

Project Milestones 187

Property Description

message A string containing a brief message about the status of your request — e.g. “ProjectMilestone #237

not found”.

Note: The project milestone record with the internal ID {id} must have the task

classification field set to Milestone in OpenAir. If the project milestone record corresponds to

a task or a phase, the API return an error with message “ProjectMilestone #{id} not found”.

Sample request

GET /rest/v1/project-milestones/2674 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data" : [

{

"priority" : 5,

"defaultCategory2" : "0",

"defaultCategory1" : "0",

"predecessorsType" : "",

"id" : 5272,

"updated" : "2022-02-10 08:43:29",

"seq" : 6,

"defaultCategory" : "6",

"name" : "End of First Phase",

"useAllCanAssign" : false,

"customerId" : 71,

"customerName" : "Internal",

"predecessors" : "",

"startDate" : "",

"predecessorsLag" : "",

"calculatedStarts" : "2021-07-01",

"isNonBillable" : false,

"projectTaskTypeId" : 0,

"currency" : "USD",

"defaultCategory4" : "0",

"projectId" : 309,

"defaultCategory5" : "0",

"isClosed" : false,

"attachments" : [

{

"id" : 486

{

"id" : 487

{

"id" : 488

}

"created" : "2022-02-03 02:56:19",

"notes" : "",

"parentId" : 0,

"idNumber" : 11,

"defaultCategory3" : "0"

REST API

Project Milestones 188

}

"message" : "success",

"meta" : {

"relationships" : [

{

"attachments" : {

"data" : {

"id" : [

486,

487,

488

"type" : "attachment"

}

]

}

Project Phases

Project phases are work packages to be completed as part of a project. It includes information about the

work to be done, when, by whom, and at what cost.

Note: The /project-phases/ endpoint can only be used for project task records with the task

classification field set to Phase in OpenAir. This is equivalent to records with the classification

property set to P in the project_task table, or in the XML API Projecttask or SOAP API

oaProjecttask datatypes.

For Milestones — project task records with zero duration and the task classification field set to

Milestone in OpenAir, or the classification property set to M in the project_task table, or in the

XML API Projecttask or SOAP API oaProjecttask datatypes — see Project Milestones.

For Tasks — project task records that have other project tasks nested under and the task

classification field set to Task in OpenAir, or the classification property set to T in the

project_task table, or in the XML API Projecttask or SOAP API oaProjecttask datatypes — see

Project Tasks.

Available methods

■

GET /project-phases/ — Get the List of Project Phases

■

GET /project-phases/{id} — Get a Project Phase

ProjectPhase Object Properties

A project phase is a work package to be completed as part of a project. It includes information about the

work to be done, when, by whom, and at what cost.

The ProjectPhase object has the following properties:

REST API

Project Phases 189

Name Description Type Read-

Only

Query

Allowed

Sorting

Allowed

attachments The attachments associated with

this phase. Array of internal IDs for

attachment objects.

Array of {”id”: <

integerValue>}

objects.

Yes — —

calculatedFinishes Calculated finish date. string($date) Yes Yes —

calculatedStarts Calculated start date of the project

phase. If the use task estimating

feature is turned on, this field will

have the estimated total time the

task will take to complete. If zero,

no estimating has occurred so the

estimate is the same as the plan.

string($date) Yes Yes —

created Time the record was created. string($date-time) Yes Yes Yes

currency Currency for the money fields in the

record. This should be the same as

the project currency.

string Yes Yes Yes

customerId The ID of the associated customer. integer($int64) Yes Yes Yes

defaultCategoryOn

Phase

The category to assign to a

timesheet entry assigned to this

task. The feature has to be enabled

for this assignment to work.

string — Yes Yes

defaultCategoryOn

Phase1

A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and project work

breakdown structure for the first

default_category_1 defined.

string — Yes Yes

defaultCategoryOn

Phase2

A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and project work

breakdown structure for the first

default_category_1 defined.

string — Yes Yes

defaultCategoryOn

Phase3

A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and project work

breakdown structure for the first

default_category_1 defined.

string — Yes Yes

defaultCategoryOn

Phase4

A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and project work

breakdown structure for the first

default_category_1 defined.

string — Yes Yes

REST API

Project Phases 190

Name Description Type Read-

Only

Query

Allowed

Sorting

Allowed

defaultCategoryOn

Phase5

A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and project work

breakdown structure for the first

default_category_1 defined.

string — Yes Yes

externalId If the record was imported from

an external system you store the

unique external record ID here.

string — Yes Yes

id Unique ID. Automatically assigned

by OpenAir

integer($int64) Yes Yes Yes

idNumber User-defined phase ID. integer($int64) — Yes Yes

isClosed A 1/0 field indicating if this is closed

phase.

Boolean — Yes Yes

isReadyFor

Recognition

Flag 1/0 indicating if phase is ready

for recognition

Boolean — Yes Yes

name Short description of this phase. string — Yes Yes

notes Notes associated with the project

phase.

string — Yes Yes

parentId The ID of our immediate ancestor.

If zero or null, this is a project-level

(top-level) task or phase.

integer($int64) — Yes Yes

percentComplete This field is an estimate of the

percentage of planned time which

has been completed. It has no

relation to the actual time spent

on a phase. (A 5-hour phase could

consume 50 hours of work but still

be only 25% complete.)

integer($int64) Yes Yes Yes

plannedHours Total number of hours the phase

is estimated to require. This is

the total amount of time the

phase should take if worked on

continuously by one person with

no interruptions. A task with zero

planned hours is also known as a

milestone.

integer($int64) Yes Yes Yes

predecessors Comma delimited list of task IDs

which must complete before this

phase can start.

string Yes Yes —

predecessorsLag Comma delimited list for task

ID:days of lag time for predecessors.

Only populated if there is a lag time.

string Yes Yes —

predecessorsType Comma delimited list of

task ID:relationship type for

predecessors. Only populated if the

relationship type is not finish-to-

start.

string Yes Yes —

REST API

Project Phases 191

Name Description Type Read-

Only

Query

Allowed

Sorting

Allowed

priority The priority of the phase (1 - 9). integer($int64) — Yes Yes

projectId The ID of the associated project. integer($int64) Yes Yes Yes

seq The sequence number of this task. integer($int64) Yes Yes Yes

updated Time the record was last updated or

modified

string($date-time) Yes Yes Yes

Get the List of Project Phases

GET /project-phases/ — Use this method to retrieve the list of project phases.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

phases returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

REST API

Project Phases 192

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the project phases requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/project-phases/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

...

{

...

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

"type": "attachment"

}

...

"rowsPerPage": 100,

REST API

Project Phases 193

"totalPages": 14,

"totalRows": 1386,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/project-phases"

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/project-phases"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/project-phases?limit=100&offset=100"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/project-phases?limit=100&offset=1300"

}

]

}

Get a Project Phase

GET /project-phases/{id} — Use this method to retrieve the project phase with the specified internal ID.

Parameters

Path parameters

Path parameter Required /

Optional

Description Type

{id} Required The internal ID of the project phase.

Note: The project phase record with the internal

ID {id} must have the task classification field set

to Phase in OpenAir.

integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

phase returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

integer

REST API

Project Phases 194

Path parameter Required /

Optional

Description Type

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the project phase requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “ProjectPhase #237 not

found”.

Note: The project task record with the internal ID {id} must have the task classification

field set to Phase in OpenAir. If the project task record corresponds to a milestone or a phase,

the API return an error with message “ProjectPhase #{id} not found”.

Sample request

GET /rest/v1/project-phases/2674 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"priority": 5,

"defaultCategoryOnPhase5": "5",

"isReadyForRecognition": false,

"plannedHours": 121,

"predecessorsType": "",

"id": 5232,

"updated": "2022-01-24 08:23:30",

"seq": 4,

"name": "Initiation",

REST API

Project Phases 195

"customerId": 71,

"defaultCategoryOnPhase1": "3",

"customerName": "Internal",

"predecessors": "",

"predecessorsLag": "",

"calculatedStarts": "2020-09-21",

"calculatedFinishes": "2020-10-02",

"currency": "USD",

"projectId": 299,

"percentComplete": 0,

"defaultCategoryOnPhase2": "1",

"isClosed": false,

"attachments": [],

"created": "2022-01-20 09:32:21",

"defaultCategoryOnPhase4": "3",

"parentId": 0,

"idNumber": 5,

"defaultCategoryOnPhase": "5"

}

"message": "success"

}

Project Tasks

Project tasks are work packages to be completed as part of a project. It includes information about the

work to be done, when, by whom, and at what cost.

Note: The /project-tasks/ endpoint can only be used for project task records with the task

classification field set to Task in OpenAir. This is equivalent to records with the classification

property set to T in the project_task table, or in the XML API Projecttask or SOAP API

oaProjecttask datatypes.

For Milestones — project task records with zero duration and the task classification field set to

Milestone in OpenAir, or the classification property set to M in the project_task table, or in the

XML API Projecttask or SOAP API oaProjecttask datatypes — see Project Milestones.

For Phases — project task records that have other project tasks nested under and the task

classification field set to Phase in OpenAir, or the classification property set to P in the

project_task table, or in the XML API Projecttask or SOAP API oaProjecttask datatypes — see

Project Phases.

Available methods

■

POST /project-tasks/ — Insert a Project Task

■

GET /project-tasks/ — Get the List of Project Tasks

■

GET /project-tasks/{id} — Get a Project Task

■

POST /project-tasks/{id}/attachments — Add an Attachment to a Project Task

■

GET /project-tasks/{id}/attachments — Get the List of Attachments Associated with a Project Task

■

GET /project-tasks/{id}/attachments/{attachment_id} — Get an Attachment Associated with a

Project Task

■

GET /project-tasks/{id}/attachments/{attachment_id}/download — Get an Attachment File

Associated with a Project Task

REST API

Project Tasks 196

■

GET /project-tasks/{id}/attachments/{attachment_id}/thumbnail — Get the Thumbnail for an

Attachment Associated with a Project Task

■

PUT /project-tasks/{id}/attachments/{attachment_id} — Replace an Attachment to a Project Task

■

DELETE /project-tasks/{id}/attachments/{attachment_id} — Delete an Attachment Associated with

a Project Task

■

DELETE /project-tasks/{id}/attachments/{attachment_ids} — Delete Attachments Associated with a

Project Task

ProjectTask Object Properties

A project task is a work package to be completed as part of a project. It includes information about the

work to be done, when, by whom, and at what cost.

The ProjectTask object has the following properties:

Name Description Type Read-

Only

Query

Allowed

Sorting

allowed

assignmentCc A comma-delimited list of internal

IDs of employees to be copied (Cc)

into assignment notification email.

Other possible listed values:

■

-1 — the assignee’s manager.

■

-2 — the manager of the

assignee’s manager.

■

-3 — the project owner.

■

-5 — the customer owner.

string — Yes Yes

assignmentCcEmails A comma-delimited lists of

additional recipient email addresses

to be copied (Cc) into assignment

notification email. Used for

recipients who are not OpenAir

users.

string — Yes Yes

attachments The attachments associated with

this task. Array of internal IDs for

attachment objects.

Array of {”id”:

<integerValue>}

objects.

Yes — —

calculatedFinishes Calculated finish date. string($date) Yes Yes —

calculatedStarts Calculated start date of the project

task. If the use task estimating

feature is turned on, this field will

have the estimated total time the

task will take to complete. If zero,

no estimating has occurred so the

estimate is the same as the plan.

string($date) Yes Yes —

costCenterId The internal ID of the associated

cost center.

integer($int64) — Yes Yes

created Time the record was created. string($date-time) Yes Yes Yes

currency Currency for the money fields in the

record. This should be the same as

the project currency.

string — Yes Yes

customerId The internal ID of the associated

customer.

integer($int64) — Yes Yes

REST API

Project Tasks 197

Name Description Type Read-

Only

Query

Allowed

Sorting

allowed

defaultCategory The category to assign to a

timesheet entry assigned to this

task. The feature has to be enabled

for this assignment to work.

integer($int64) — Yes Yes

defaultCategory1 A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and phase work

breakdown structure for the first

default_category_1 defined.

integer($int64) — Yes Yes

defaultCategory2 A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and phase work

breakdown structure for the first

default_category_1 defined.

integer($int64) — Yes Yes

defaultCategory3 A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and phase work

breakdown structure for the first

default_category_1 defined.

integer($int64) — Yes Yes

defaultCategory4 A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and phase work

breakdown structure for the first

default_category_1 defined.

integer($int64) — Yes Yes

defaultCategory5 A feature, if enabled, would assign

this default_category_1 to the

category_1 for many transactions

that have a category_1_id and

project_task_id by searching the

project_task and phase work

breakdown structure for the first

default_category_1 defined.

integer($int64) — Yes Yes

externalId If the record was imported from

an external system you store the

unique external record ID here.

integer($int64) — Yes Yes

fnltDate The finish no later than date of the

task. The task must be finished by

this date.

string($date) — Yes Yes

hoursRemaining

Estimates



Array of {”id”:

<integerValue>}

objects.

— Yes —

REST API

Project Tasks 198

Name Description Type Read-

Only

Query

Allowed

Sorting

allowed

id Unique ID. Automatically assigned

by OpenAir

Array of {”id”:

<integerValue>}

objects.

Yes Yes Yes

idNumber User-defined phase ID. Array of {”id”:

<integerValue>}

objects.

— — Yes

isClosed A 1/0 field indicating if this is closed

phase.

boolean — Yes Yes

isNonBillable If set to 1, this is not billable. This

is only applicable for project billing

rules.

boolean — Yes Yes

isReadyFor

Recognition

Flag 1/0 indicating if phase is ready

for recognition

boolean — Yes Yes

isSignOffRequired



boolean — Yes Yes

isUsingProject

Assignment

Flag set to 1 if they are using the

project level user assignment.

boolean — Yes Yes

name Short description of this task. string — Yes Yes

notes Notes associated with the project

task.

string — Yes Yes

parentId The internal ID of the immediate

ancestor. If zero or null, this is a

project-level (top-level) task or

phase.

integer($int64) — Yes Yes

percentComplete This field is an estimate of the

percentage of planned time which

has been completed. It has no

relation to the real time spent on

a phase. (A 5-hour phase could

consume 50 hours of work but still

be only 25% complete.)

integer($int64) — Yes Yes

plannedHours Total number of hours the phase is

estimated to require. This is the total

amount of time the phase should

take if worked on continuously by

one person with no interruptions.

A phase with zero planned hours is

also known as a milestone.

number($float) — Yes Yes

predecessors Comma delimited list of task IDs

which must complete before this

phase can start.

string — Yes —

predecessorsLag Comma delimited list for task

ID:days of lag time for predecessors.

Only populated if there is a lag time.

string — Yes —

predecessorsType Comma delimited list of

task ID:relationship type for

predecessors. Only populated if the

relationship type is not finish-to-

start.

string — Yes —

REST API

Project Tasks 199

Name Description Type Read-

Only

Query

Allowed

Sorting

allowed

priority The priority of the phase (1 - 9). integer($int64) — Yes Yes

projectId The internal ID of the associated

project.

integer($int64) — Yes Yes

projectTaskTypeId The internal ID of the associated

project task type. Not for phases.

integer($int64) — Yes Yes

seq The sequence number of this task. integer($int64) — Yes Yes

startDate Optional scheduled starting date of

this task. Overrides computed start

date.

string($date) — Yes Yes

taskBudgetCost If task budgeting is enabled this is

the total cost of the task.

number($float) — Yes Yes

taskBudgetRevenue If task budgeting is enabled this is

the total projected billing for the

task.

number($float) — Yes Yes

taskSplits



Array of {”id”:

<integerValue>}

objects.

— — —

timetypeFilter A timetype filter. This will hold a list

of the timetypes that are allowed to

book time to this task.

Array of {”id”:

<integerValue>}

objects.

— — —

updated Time the record was last updated or

modified

string($date) Yes Yes Yes

useAllCanAssign Is everyone able to assign time/

expenses to this task.

boolean — Yes Yes

useManualTask

Budget

If set to 1 then the task budget

is manually entered rather than

calculated by OpenAir

boolean — Yes Yes

userAssignments A comma separated list of user

nicknames to assign this task to.

(project_task_assign can also be

used.)

Array of {”id”:

<integerValue>}

objects.

— — —

Insert a Project Task

POST /project-tasks/ — Use this method to create a new project task.

Parameters

Path parameters

None

REST API

Project Tasks 200

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

task returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

project task created. Otherwise, the response will include only the

internal ID of the project task created.

Boolean

Request body

The ProjectTask object to be created. The object must include valid key-value pairs for all required

attributes and cannot include key-value pairs for read-only attributes. For information about the

ProjectTask object model, see ProjectTask Object Properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The ProjectTask object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the project task created.

REST API

Project Tasks 201

Property Description

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/project-tasks/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"attachments": [{"id": 6459}],

"budget": 500000,

"contactId": 537,

"currency": "EUR",

"customerId": 489,

"finishDate": "2022-12-31",

"name": "Hardware deployment",

"userId": 174

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 2689

}

"message": "success"

}

Get the List of Project Tasks

GET /project-tasks/ — Use this method to retrieve the list of project tasks.

REST API

Project Tasks 202

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

tasks returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the project tasks requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

REST API

Project Tasks 203

Property Description

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/project-tasks/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

...

{

...

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

"type": "attachment"

}

...

"rowsPerPage": 100,

"totalPages": 14,

"totalRows": 1386,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/project-tasks"

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/project-tasks"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/project-tasks?limit=100&offset=100"

REST API

Project Tasks 204

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/project-tasks?limit=100&offset=1300"

}

]

}

Get a Project Task

GET /project-tasks/{id} — Use this method to retrieve the project task with the specified internal ID.

Parameters

Path parameters

Path parameter Required /

Optional

Description Type

{id} Required The internal ID of the project task.

Note: The project task record with the internal

ID {id} must have the task classification field set

to Task in OpenAir.

integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the project

task returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

REST API

Project Tasks 205

Property Description

data An array containing the project task requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “ProjectTask #237 not

found”.

Note: The project task record with the internal ID {id} must have the task classification

field set to Task in OpenAir. If the project task record corresponds to a milestone or a phase,

the API return an error with message “ProjectTask #{id} not found”.

Sample request

GET /rest/v1/project-tasks/2674 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"priority": 0,

"defaultCategory2": "0",

"defaultCategory1": "0",

"isReadyForRecognition": false,

"plannedHours": 64,

"assignmentCcEmails": "",

"timetypeFilter": [],

"predecessorsType": "",

"isSignOffRequired": false,

"taskSplits": [],

"updated": "2020-06-18 08:34:51",

"id": 438,

"seq": 0,

"defaultCategory": "1",

"fnltDate": "0000-00-00",

"useAllCanAssign": false,

"name": "Alignment workshop",

"customerId": 3,

"customerName": "Damus Inc.",

"costCenterId": 0,

REST API

Project Tasks 206

"predecessors": "437",

"isUsingProjectAssignment": false,

"classification": "T",

"startDate": "",

"predecessorsLag": "",

"useManualTaskBudget": false,

"externalId": "",

"calculatedStarts": "2021-10-09",

"isNonBillable": false,

"cfHoursPercentageToCloseTask": "",

"taskBudgetRevenue": 15680,

"projectTaskTypeId": 1,

"taskBudgetCost": 2741.44,

"calculatedFinishes": "2021-10-15",

"currency": "USD",

"isAPhase": false,

"defaultCategory4": "0",

"projectId": 27,

"assignmentCc": "",

"hoursRemainingEstimates": [],

"percentComplete": 100,

"isClosed": false,

"defaultCategory5": "0",

"created": "2020-04-21 13:14:14",

"userAssignments": [

18,

"parentId": 431,

"notes": "",

"idNumber": 5,

"defaultCategory3": "0"

}

"message": "success"

}

Add an Attachment to a Project Task

POST /project-tasks/{id}/attachments — Use this method to add an attachment to the project task with

the specified internal ID. This method can be used for any of the following cases:

■

Create a new attachment and associate it with the project task.

■

Associate a workspace document with the project task. Workspace documents are Attachment objects

associated with a custom workspace.

Note: If the Attachment Thumbnail and Attachment Viewer feature is enabled for your OpenAir

account, a thumbnail is generated automatically when you add an attachment of a supported

format. The file_name must be included in the request and must include a supported file

extension. For more information about the Attachment Thumbnail feature, including supported file

format and filename extensions, see Optional Features.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project task. integer

REST API

Project Tasks 207

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment returned. For the Attachment object properties, see

Attachment object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

attachment created. Otherwise, the response will include only the

internal ID of the attachment created.

Boolean

Request body

This method accepts either one of the content types described in the following table:

Content-Type header Body Use case

multipart/form-data Form data with the following key-value pair:

■

file — The file to be uploaded. The file

and file metadata will be used to create

the new Attachment object.

■

Create a new attachment and

associate it with the project task.

application/json JSON object with the following key-value pair:

■

id — The internal ID of the workspace

document to be associated with the

project task.

■

Associate a workspace document

with the project task.

Response definitions

A successful request returns a JSON object with the following properties:

REST API

Project Tasks 208

Property Description

data An array containing one of the following:

■

The Attachment object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the attachment created.

See Returned Data. For the Attachment object properties, see Attachment object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/project-tasks/237/attachments/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: multipart/form-data boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Authorization: Bearer <OAuth2_access_token>

----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"

@C:\Users\mcollins\Desktop\2020-12-08_18-47-31.png

----WebKitFormBoundary7MA4YWxkTrZu0gW

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

Get the List of Attachments Associated with a Project Task

GET /project-tasks/{id}/attachments — Use this method to retrieve the list of attachments associated

with the project task with the specified internal ID.

REST API

Project Tasks 209

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project task. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for each

attachment returned. Response Data Modifiers. For information

about Attachment object properties, see Attachment object

properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the list of attachments associated with the project task with the specified internal

ID. See Returned Data. For information about Attachment object properties, see Attachment object

properties.

REST API

Project Tasks 210

Property Description

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “ProjectTask #237 not

found”.

Sample request

GET /rest/v1/project-tasks/237/attachments/?fields=fileName,isLocked,uploadedBy,size,id,fileType HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"fileName": "2020-11-20_13-25-06.png",

"isLocked": false,

"id": 4982,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 114659

{

"fileName": "2020-12-08_14-46-24.png",

"isLocked": false,

"id": 56,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 123754

"message": "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

REST API

Project Tasks 211

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

"rowsPerPage": 100,

"totalPages": 1,

"totalRows": 2,

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/project-tasks/237/attachments"

}

]

}

Get an Attachment Associated with a Project Task

GET /project-tasks/{id}/attachments/{attachment_id} — Use this method to retrieve the attachment

record with the specified attachment ID associated with the project task with the specified internal ID. The

response contains the attachment metadata only and not the file.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project task. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment metadata returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

REST API

Project Tasks 212

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the attachment metadata requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Attachment #598 not

found”.

Sample request

GET project-tasks/237/attachments/4982?fields=fileName,isLocked,uploadedBy,size,id,fileType HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"fileName": "2020-11-20_13-25-06.png",

"isLocked": false,

"id": 4982,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 114659

}

"message": "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

]

}

REST API

Project Tasks 213

}

Get an Attachment File Associated with a Project Task

GET /project-tasks/{id}/attachments/{attachment_id}/download — Use this method to retrieve the file

associated with the attachment record with the specified attachment ID associated with the project task

with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project task. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#598 not found”.

A successful request also returns the attachment file.

Sample request

GET project-tasks/237/attachments/4982/download HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

REST API

Project Tasks 214

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The attachment file.

Get the Thumbnail for an Attachment Associated with a

Project Task

GET /project-tasks/{id}/attachments/{attachment_id}/thumbnail — Use this method to retrieve the

thumbnail file associated with the attachment record with the specified attachment ID associated with the

project task with the specified internal ID. Available only if the Attachment Thumbnail feature is enabled

for your OpenAir account.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#598 not found” or “Attachment #213 thumbnail not found”.

REST API

Project Tasks 215

A successful request also returns the attachment thumbnail file.

Sample request

GET project-tasks/237/attachments/4982/thumbnail HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The attachment thumbnail file.

Replace an Attachment to a Project Task

PUT /project-tasks/{id}/attachments/{attachment_id} — Use this method to replace an attachment to

the project task with the specified internal ID.

Important: This method can only be used to replace an attachment directly associated with the

project task. It cannot be used for workspace document associated with the project task either to

replace the workspace document or to associate a different workspace document in its place.

Note: If the Attachment Thumbnail and Attachment Viewer feature is enabled for your OpenAir

account, a thumbnail is generated automatically when you add an attachment of a supported

format. The file_name must be included in the request and must include a supported file

extension. For more information about the Attachment Thumbnail feature, including supported file

format and filename extensions, see Optional Features.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project task. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

REST API

Project Tasks 216

Path parameter Required /

Optional

Description Type

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment returned. For the Attachment object properties, see

Attachment object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

attachment created. Otherwise, the response will include only the

internal ID of the attachment created.

Boolean

Request body

This method accepts the following content type:

Content-Type header Body

multipart/form-data Form data with the following key-value pair:

■

file — The file to be uploaded. The file and file metadata will be used to replace

the existing Attachment object with a new Attachment object.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Attachment object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the attachment created.

REST API

Project Tasks 217

Property Description

See Returned Data. For the Attachment object properties, see Attachment object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

PUT /rest/v1/project-tasks/237/attachments/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: multipart/form-data boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Authorization: Bearer <OAuth2_access_token>

----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"

@C:\Users\mcollins\Desktop\2020-12-08_18-47-31.png

----WebKitFormBoundary7MA4YWxkTrZu0gW

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

Delete an Attachment Associated with a Project Task

DELETE /project-tasks/{id}/attachments/{attachment_id} — Use this method to delete the attachment

with the specified attachment ID associated with the project task with the specified internal ID, or clear

the association between the workspace document with the specified attachment ID and the project task

with the specified internal ID.

REST API

Project Tasks 218

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the project task. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#4985 not found”.

Sample request

DELETE /rest/v1/project-tasks/237/attachments/4982 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

REST API

Project Tasks 219

Delete Attachments Associated with a Project Task

DELETE /project-tasks/{id}/attachments/{attachment_ids} — Use this method to delete attachments

with the specified attachment IDs associated with the project task with the specified internal ID, or clear

the association between the workspace document with the specified attachment ID and the project task

with the specified internal ID.

Parameters

Path parameters

Path parameter Required /

Optional

Description Type

{id} Required The internal ID of the project task. integer

{attachment_ids} Required A comma-separated list of internal IDs for the

attachments. The list must not include more than

1000 attachment IDs.

integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message If your request includes multiple attachment IDs, both valid and invalid, the request will complete

successfully for valid attachment IDs and return an error message for invalid attachment IDs — e.g.

"Access to Attachment #693 denied". The response status will be 207 Multiple statuses returned.

If your request more than 1,000 attachment IDs, an error is returned — e.g. "Bulk action limit

reached, sent 1001 entities of 1000 allowed".

Sample request

DELETE /rest/v1/project-tasks/237/attachments/4982,4983 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

REST API

Project Tasks 220

Sample response

{

"data": [

{

"4982" : {

"data": [{

"id": "4982"

}],

"message": "success"

"4983" : {

"data": [{

"id": "4983"

}],

"message": "success"

}

"message": "success"

}

Receipts

Receipts are expense items that contain information about costs incurred by employees and collected in

expense reports.

Available methods

■

POST /receipts/ — Insert a Receipt

■

GET /receipts/ — Get the List of Receipts

■

GET /receipts/{id} — Get a Receipt

■

PUT /receipts/{id} — Update a Receipt

■

DELETE /receipts/{id} — Delete a Receipt

■

POST /receipts/{id}/attachments — Add an Attachment to a Receipt

■

GET /receipts/{id}/attachments — Get the List of Attachments Associated with a Receipt

■

GET /receipts/{id}/attachments/{attachment_id} — Get an Attachment Associated with a Receipt

■

GET /receipts/{id}/attachments/{attachment_id}/download — Get an Attachment File Associated

with a Receipt

■

GET /receipts/{id}/attachments/{attachment_id}/thumbnail — Get the Thumbnail for an

Attachment Associated with a Receipt

■

PUT /receipts/{id}/attachments/{attachment_id} — Replace an Attachment to a Receipt

■

DELETE /receipts/{id}/attachments/{attachment_id} — Delete an Attachment Associated with a

Receipt

■

DELETE /receipts/{id}/attachments/{attachment_ids} — Delete Attachments Associated with a

Receipt

■

OPTIONS /receipts/ — Discover Available Methods and Fetch the Endpoint Reference for Receipts

Receipt object properties

A receipt is an expense items that contains information about cost incurred by an employee and collected

in an expense report.

REST API

Receipts 221

The Receipt object has the following properties:

Property Description Type Read-only Query allowed Sorting allowed

accountingDate The accounting period date of the receipt. string($date) — Yes Yes

attachments The attachments associated with

the receipt. Array of internal IDs for

attachment objects.

Array of {”id”: <

integerValue>}

objects.

Yes — —

costCenterId The internal ID of the cost center

associated with the receipt.

integer($int64) Yes Yes Yes

costPerUnit The cost per unit of measure. number($float) — Yes —

created The date the receipt was created. string($date-time) Yes Yes —

currency The currency for monetary values in the

receipt record. Three-letter currency code.

string — Yes —

customerId The internal ID of the customer associated

with the receipt.

integer($int64) — Yes Yes

date [REQUIRED] The date of the receipt. string ($date) — Yes Yes

description The description of the receipt. string — Yes —

expenseReportId [REQUIRED] The internal ID of the expense

report associated with the receipt.

integer($int64) — Yes Yes

externalId The unique external ID of the receipt, if

the record was imported from an external

system.

string — Yes Yes

federalTax The total federal tax for the receipt. number($float) — — —

federalTaxRate The federal tax rate for the receipt. number($float) — — —

foreignCurrencyCost The cost per unit of measure in the

selected foreign currency, if this is a

foreign currency receipt.

number($float) — Yes —

foreignCurrencyRate The foreign currency conversion rate, if this

is a foreign currency receipt.

number($float) Yes Yes —

foreignCurrencySymbol The foreign currency, if this is a foreign

currency receipt. Three-letter currency

code.

string — Yes —

foreignCurrencyTotalTax

Paid

The tax paid in the foreign currency, if this

is a foreign currency receipt.

number($float) — Yes —

gst The total GST tax for the receipt. number($float) — — —

gstRate The GST tax rate for the receipt. number($float) — — —

hst The total HST tax for the receipt. number($float) — — —

hstRate The HST tax rate for the receipt. number($float) — — —

id The unique internal identifier of the receipt. integer($int64) Yes Yes Yes

isForeignCurrency

ExchangeIntolerance

A 1/0 field indicating if the record is within

the specified foreign currency tolerance.

Boolean — Yes —

isMissingPaperReceipt A 1/0 field indicating if the paper receipt is

missing for this receipt.

Boolean — Yes —

isNonBillable A 1/0 field indicating if the receipt is not

billable.

Boolean — Yes —

isReimbursable A 1/0 field indicating if the receipt is

reimbursable.

Boolean — Yes —

isTaxIncludedInCost A 1/0 field indicating if the cost includes the

tax.

Boolean — Yes —

REST API

Receipts 222

Property Description Type Read-only Query allowed Sorting allowed

itemId The internal ID of the item associated with

the receipt. The type of item can be used to

determine the receipt subtype.

integer($int64) — Yes Yes

notes Notes about the receipt. string — Yes —

paymentTypeId The internal ID of the payment type

associated with the receipt. The payment

type indicates how the payment was

made and may determine if the receipt is

reimbursable.

integer($int64) — Yes Yes

projectId The internal ID of the project associated

with the receipt.

integer($int64) — Yes Yes

projectTaskId The internal ID of the project task

associated with the receipt. Requires

an option to be enabled in OpenAir

(Administration > Application Settings >

Expenses > Other settings).

integer($int64) — Yes Yes

pst The total PST tax for the receipt. number($float) — — —

pstRate The PST tax rate for the receipt. number($float) — — —

quantity [REQUIRED] The quantity (number of units

of measure).

integer($int64) — Yes —

receiptLocation The city or location where the cost was

incurred.

string — Yes —

slipId The internal ID of the slip associated with

the receipt, if the expense was billed.

integer($int64) Yes Yes Yes

stateTax The total state tax for the receipt. number($float) — — —

stateTaxRate The state tax rate for the receipt. number($float) — — —

taxLocationId The internal ID of the tax location

associated with the receipt.

integer($int64) — — —

total The total value of the receipt. number($float) — Yes —

totalNoTax The total value of the receipt excluding tax. number($float) — — —

totalTaxPaid The total tax paid. number($float) — Yes —

trackingNumber [REQUIRED] The unique reference number

of the receipt within the associated

expense report. This attribute is used to

cross-reference digital receipts with paper

receipts.

string — Yes Yes

updated The date the receipt was last updated or

modified.

string ($date-

time)

Yes Yes —

userId [REQUIRED] The internal ID of the

employee associated with the receipt.

integer($int64) Yes Yes Yes

userLocationId The internal ID of the employee location

associated with the receipt.

integer($int64) — Yes Yes

vehicleId The internal ID of the vehicle associated

with the receipt.

integer($int64) — Yes Yes

vendorId The internal ID of the vendor associated

with the receipt.

integer($int64) — Yes Yes

REST API

Receipts 223

Note: Access to certain object types and object attributes depend on the business logic

configured for the OpenAir account. It may vary depending on the role and access privileges

associated with the access token and with the user who authorized the application.

Required and read-only attributes also depend on the business logic configured for each specific

OpenAir account. Some fields such as id, created, and updated are system-generated and always

read-only.

Insert a Receipt

POST /receipts/ — Use this method to create a new receipt.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the receipt

returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return

the receipt created. Otherwise, the response will include only the

internal ID of the receipt created.

Boolean

REST API

Receipts 224

Request body

The Receipt object to be created. The object must include valid key-value pairs for all required attributes

and cannot include key-value pairs for read-only attributes. For information about the Receipt object

model, see Receipt object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Receipt object created, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the internal ID of the receipt created.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/receipts/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"foreignCurrencySymbol": "",

"expenseReportId": 237,

"date": "2019-10-01",

"costPerUnit": 580,

"total": 580,

"description": "Miscellaneous",

"itemId": 7,

"customerId": 50,

"isForeignCurrencyExchangeIntolerance": false,

"isNonBillable": true,

"currency": "USD",

"projectId": 54,

"isTaxIncludedInCost": false,

"quantity": 1,

"isReimbursable": true,

"totalNoTax": 580

REST API

Receipts 225

"trackingNumber": 2

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 2674

}

"message": "success"

}

Get the List of Receipts

GET /receipts/ — Use this method to retrieve a list of receipts.

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for each receipt

returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

string

REST API

Receipts 226

Path parameter Required /

Optional

Description Type

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the receipts requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/receipts/q=expenseReportId EQUAL 237 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"foreignCurrencySymbol": "",

"expenseReportId": 237,

"date": "2019-10-01",

"costPerUnit": 680,

"taxLocationId": 0,

"foreignCurrencyRate": 0,

"projectTaskId": 0,

"updated": "2019-10-21 03:04:58",

"id": 2659,

"slipId": 0,

"paymentTypeId": 0,

"total": 680,

"description": "Miscellaneous",

REST API

Receipts 227

"itemId": 7,

"customerId": 50,

"totalTaxPaid": 0,

"costCenterId": 0,

"trackingNumber": "1",

"isForeignCurrencyExchangeIntolerance": false,

"externalId": "",

"userLocationId": 0,

"isNonBillable": false,

"accountingDate": "0000-00-00",

"foreignCurrencyCost": 0,

"currency": "USD",

"foreignCurrencyTotalTaxPaid": 0,

"projectId": 54,

"isTaxIncludedInCost": false,

"attachments": [3719],

"userId": 49,

"quantity": 1,

"created": "2019-10-01 14:12:50",

"isReimbursable": true,

"totalNoTax": 680,

"notes": ""

{

"foreignCurrencySymbol": "",

"expenseReportId": 237,

"date": "2019-10-01",

"costPerUnit": 580,

"taxLocationId": 0,

"foreignCurrencyRate": 0,

"projectTaskId": 0,

"updated": "2019-10-21 03:04:58",

"id": 2674,

"slipId": 0,

"paymentTypeId": 0,

"total": 580,

"description": "Miscellaneous",

"itemId": 7,

"customerId": 50,

"totalTaxPaid": 0,

"costCenterId": 0,

"trackingNumber": "2",

"isForeignCurrencyExchangeIntolerance": false,

"externalId": "",

"userLocationId": 0,

"isNonBillable": true,

"accountingDate": "0000-00-00",

"foreignCurrencyCost": 0,

"currency": "USD",

"foreignCurrencyTotalTaxPaid": 0,

"projectId": 54,

"isTaxIncludedInCost": false,

"attachments": [3745],

"userId": 49,

"quantity": 1,

"created": "2019-10-01 14:13:03",

"isReimbursable": true,

"totalNoTax": 580,

"notes": ""

}

"message": "success",

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

3719

"type": "attachment"

}

REST API

Receipts 228

"userId": {

"data": {

"id": 49,

"type": "userDisplayName"

}

{

"attachments": {

"data": {

"id": [

3745

"type": "attachment"

}

"userId": {

"data": {

"id": 49,

"type": "userDisplayName"

}

"rowsPerPage": 100,

"totalPages": 1,

"totalRows": 2,

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/receipts/q=expenseReportId%20EQUAL%20237"

}

]

}

Get a Receipt

GET /receipts/{id} — Use this method to retrieve a receipt with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the receipt

returned. Response Data Modifiers.

string

REST API

Receipts 229

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the receipt requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “ExpenseReport #237 not

found”.

Sample request

GET /rest/v1/receipts/2674 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"foreignCurrencySymbol": "",

"expenseReportId": 237,

"date": "2019-10-01",

"costPerUnit": 580,

"taxLocationId": 0,

REST API

Receipts 230

"foreignCurrencyRate": 0,

"projectTaskId": 0,

"updated": "2019-10-21 03:04:58",

"id": 2674,

"slipId": 0,

"paymentTypeId": 0,

"total": 580,

"description": "Miscellaneous",

"itemId": 7,

"customerId": 50,

"totalTaxPaid": 0,

"costCenterId": 0,

"trackingNumber": "2",

"isForeignCurrencyExchangeIntolerance": false,

"externalId": "",

"userLocationId": 0,

"isNonBillable": true,

"accountingDate": "0000-00-00",

"foreignCurrencyCost": 0,

"currency": "USD",

"foreignCurrencyTotalTaxPaid": 0,

"projectId": 54,

"isTaxIncludedInCost": false,

"attachments": [3719],

"userId": 49,

"quantity": 1,

"created": "2019-10-01 14:13:03",

"isReimbursable": true,

"totalNoTax": 580,

"notes": ""

}

"message": "success"

"meta": {

"relationships": [

{

"attachments": {

"data": {

"id": [

3719

"type": "attachment"

}

"userId": {

"data": {

"id": 49,

"type": "userDisplayName"

}

]

}

Update a Receipt

PUT /receipts/{id} — Use this method to update the receipt with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

REST API

Receipts 231

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the receipt

returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will include

the receipt updated. Otherwise, the response will include only the

internal ID of the receipt updated.

Boolean

Request body

An object including valid key-value pairs for the fields to be updated. The object cannot include key-

value pairs for read-only attributes. For information about the Receipt object model, see Receipt object

properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Receipt object updated, if the return_object parameter was set to any value other than 0 (zero)

in the request. The object includes all the attributes specified using the fields if included in the

request.

■

An object with only the ID of the receipt updated.

See Returned Data.

REST API

Receipts 232

Property Description

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Receipt #2675 not

found”.

Sample request

PUT /rest/v1/receipts/2674 HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"externalId": "4823",

"accountingDate": "2019-10-30",

"currency": "CAD",

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 2674

}

"message": "success"

}

Delete a Receipt

DELETE /receipts/{id} — Use this method to delete the receipt record with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

REST API

Receipts 233

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Receipt

#2675 not found”.

Sample request

DELETE /rest/v1/receipts/2674 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 2674

}

"message": "success"

}

Add an Attachment to a Receipt

POST /receipts/{id}/attachments — Use this method to add an attachment to the receipt with the

specified internal ID. This method can be used for any of the following cases:

■

Create a new attachment and associate it with the receipt.

■

Associate a workspace document with the receipt. Workspace documents are Attachment objects

associated with a custom workspace.

REST API

Receipts 234

Note: If the Attachment Thumbnail and Attachment Viewer feature is enabled for your OpenAir

account, a thumbnail is generated automatically when you add an attachment of a supported

format. The file_name must be included in the request and must include a supported file

extension. For more information about the Attachment Thumbnail feature, including supported file

format and filename extensions, see Optional Features.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment returned. For the Attachment object properties, see

Attachment object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

attachment created. Otherwise, the response will include only the

internal ID of the attachment created.

Boolean

Request body

This method accepts either one of the content types described in the following table:

REST API

Receipts 235

Content-Type header Body Use case

multipart/form-data Form data with the following key-value pair:

■

file — The file to be uploaded. The file

and file metadata will be used to create

the new Attachment object.

■

Create a new attachment and

associate it with the receipt.

application/json JSON object with the following key-value pair:

■

id — The internal ID of the workspace

document to be associated with the

receipt.

■

Associate a workspace document

with the receipt.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The Attachment object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the attachment created.

See Returned Data. For the Attachment object properties, see Attachment object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/receipts/2674/attachments/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: multipart/form-data boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Authorization: Bearer <OAuth2_access_token>

----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"

@C:\Users\mcollins\Desktop\2020-12-08_18-47-31.png

----WebKitFormBoundary7MA4YWxkTrZu0gW

REST API

Receipts 236

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4985

}

"message": "success"

}

Get the List of Attachments Associated with a Receipt

GET /receipts/{id}/attachments — Use this method to retrieve the list of attachments associated with

the receipt with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for each

attachment returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus

sign (-) before the attribute name to specify an ascending (+) or

string

REST API

Receipts 237

Path parameter Required /

Optional

Description Type

descending (-) sort order. An ascending sort order is used if the

sort order is not specified. See Sorting.

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the list of attachments associated with the receipt with the specified internal ID.

See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Receipt #237 not found”.

Sample request

GET /rest/v1/receipts/2674/attachments/?fields=fileName,isLocked,uploadedBy,size,id,fileType HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"fileName": "2020-11-20_13-25-06.png",

"isLocked": false,

"id": 4985,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

REST API

Receipts 238

"size": 114659

{

"fileName": "2020-12-08_14-46-24.png",

"isLocked": false,

"id": 5016,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 123754

"message": "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

"rowsPerPage": 100,

"totalPages": 1,

"totalRows": 2,

"links": [

{

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/receipts/2674/attachments"

}

]

}

Get an Attachment Associated with a Receipt

GET /receipts/{id}/attachments/{attachment_id} — Use this method to retrieve the attachment record

with the specified attachment ID associated with the receipt with the specified internal ID. The response

contains the attachment metadata only and not the file.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

string

REST API

Receipts 239

Path parameter Required /

Optional

Description Type

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment metadata returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the attachment metadata requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Attachment #598 not

found”.

Sample request

GET receipts/2674/attachments/4985?fields=fileName,isLocked,uploadedBy,size,id,fileType HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

REST API

Receipts 240

"data": [

{

"fileName": "2020-11-20_13-25-06.png",

"isLocked": false,

"id": 4985,

"uploadedBy": 49,

"fileType": "PNG image data, 1250 x 800, 8-bit/color RGBA, non-interlaced",

"size": 114659

}

"message": "success",

"meta": {

"relationships": [

{

"uploadedBy": {

"data": { "type": "userDisplayName", "id": 49 }

}

]

}

Get an Attachment File Associated with a Receipt

GET /expense-reports/{id}/attachments/{attachment_id}/download — Use this method to retrieve the

file associated with the attachment record with the specified attachment ID associated with the receipt

with the specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

REST API

Receipts 241

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#598 not found”.

A successful request also returns the attachment file.

Sample request

GET receipts/2674/attachments/4985/download HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The attachment file.

Get the Thumbnail for an Attachment Associated with a

Receipt

GET /expense-reports/{id}/attachments/{attachment_id}/thumbnail — Use this method to retrieve the

thumbnail file associated with the attachment record with the specified attachment ID associated with the

receipt with the specified internal ID. Available only if the Attachment Thumbnail feature is enabled for

your OpenAir account.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

REST API

Receipts 242

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#598 not found” or “Attachment #213 thumbnail not found”.

A successful request also returns the attachment thumbnail file.

Sample request

GET receipts/2674/attachments/4985/thumbnail HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The attachment thumbnail file.

Replace an Attachment to a Receipt

PUT /receipts/{id}/attachments/{attachment_id} — Use this method to replace an attachment to the

receipt with the specified internal ID.

Important: This method can only be used to replace an attachment directly associated with the

receipt. It cannot be used for workspace document associated with the receipt either to replace

the workspace document or to associate a different workspace document in its place.

Note: If the Attachment Thumbnail and Attachment Viewer feature is enabled for your OpenAir

account, a thumbnail is generated automatically when you add an attachment of a supported

format. The file_name must be included in the request and must include a supported file

extension. For more information about the Attachment Thumbnail feature, including supported file

format and filename extensions, see Optional Features.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

{attachment_id} Required The internal ID of the attachment. integer

REST API

Receipts 243

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the

attachment returned. For the Attachment object properties, see

Attachment object properties.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to any value other than 0 (zero), the response will return the

attachment created. Otherwise, the response will include only the

internal ID of the attachment created.

Boolean

Request body

This method accepts the following content type:

Content-Type header Body

multipart/form-data Form data with the following key-value pair:

■

file — The file to be uploaded. The file and file metadata will be used to replace

the existing Attachment object with a new Attachment object.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

REST API

Receipts 244

Property Description

■

The Attachment object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the attachment created.

See Returned Data. For the Attachment object properties, see Attachment object properties.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

PUT /rest/v1/receipts/237/attachments/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: multipart/form-data boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Authorization: Bearer <OAuth2_access_token>

----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"

@C:\Users\mcollins\Desktop\2020-12-08_18-47-31.png

----WebKitFormBoundary7MA4YWxkTrZu0gW

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 4982

}

"message": "success"

}

Delete an Attachment Associated with a Receipt

DELETE receipts/{id}/attachments/{attachment_id} — Use this method to delete the attachment

with the specified attachment ID associated with the receipt with the specified internal ID, or clear the

REST API

Receipts 245

association between the workspace document with the specified attachment ID and the receipt with the

specified internal ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the receipt. integer

{attachment_id} Required The internal ID of the attachment. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “Attachment

#4985 not found”.

Sample request

DELETE receipts/2674/attachments/4985 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

REST API

Receipts 246

"data": [

{

"id": 4985

}

"message": "success"

}

Delete Attachments Associated with a Receipt

DELETE /receipts/{id}/attachments/{attachment_ids} — Use this method to delete attachments

with the specified attachment IDs associated with the receipt with the specified internal ID, or clear the

association between the workspace document with the specified attachment ID and the receipt with the

specified internal ID.

Parameters

Path parameters

Path parameter Required /

Optional

Description Type

{id} Required The internal ID of the receipt. integer

{attachment_ids} Required A comma-separated list of internal IDs for the

attachments. The list must not include more than

1000 attachment IDs.

integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message If your request includes multiple attachment IDs, both valid and invalid, the request will complete

successfully for valid attachment IDs and return an error message for invalid attachment IDs — e.g.

"Access to Attachment #693 denied". The response status will be 207 Multiple statuses returned.

REST API

Receipts 247

Property Description

If your request more than 1,000 attachment IDs, an error is returned — e.g. "Bulk action limit

reached, sent 1001 entities of 1000 allowed".

Sample request

DELETE receipts/2674/attachments/4985,4987 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"4985" : {

"data": [{

"id": "4985"

}],

"message": "success"

"4987" : {

"data": [{

"id": "4987"

}],

"message": "success"

}

"message": "success"

}

Discover Available Methods and Fetch the Endpoint

Reference for Receipts

OPTIONS /receipts/ — Use this method to discover the methods available and fetch the OpenAPI 3.0

JSON endpoint reference for receipts.

Parameters

None

Response definitions

A successful request returns the OpenAPI 3.0 JSON endpoint reference in the response body. The

JSON object returned contains metadata information about the resource endpoint. It is similar to the

Generated API Documentation JSON, only it is restricted to the resource endpoint path specified in the

request.

The response also includes the following header:

REST API

Receipts 248

Header Description

Access-Control-Allow-Methods A comma-separated list of HTTP methods available for the requested

resource collection endpoint.

Sample request

OPTIONS /rest/v1/receipts/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The response includes the OpenAPI 3.0 endpoint reference for the resource endpoint as a JSON object in

the response body, as well as the following headers:

Content-Type: application/json; charset=utf-8

Content-Length: 6955

Connection: keep-alive

Cache-control: no-cache, no-store, pre-check=0, post-check=0, must-revalidate, max-age=0, s-max-age=0

Pragma: no-cache

Expires: 0

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, PUT, POST, DELETE, OPTIONS

Access-Control-Allow-Headers: Content-Type

Access-Control-Max-Age: 86400

Vary: Accept-Encoding,User-Agent

Content-Encoding: gzip

Time Entries

Time entry records contain information about time worked by an employee on a work package.

Available methods

■

POST /time-entries/ — Insert a Time Entry

■

GET /time-entries/ — Get the List of Time Entries

■

GET /time-entries/{id} — Get a Time Entry

■

DELETE /time-entries/{id} — Delete a Time Entry

■

OPTIONS /time-entries/ — Discover Available Methods and Fetch the Endpoint Reference for Time

Entries

Time entry object properties

A time entry is a time slot worked by an employee on a work package.

REST API

Time Entries 249

The TimeEntry object has the following properties:

Property Description Type Read-

only

Query

allowed

Sorting

allowed

accountingDate The accounting period date of the time

entry.

string($date-time) — Yes Yes

categoryId The internal ID of the associated service

(category).

integer($int64) — Yes Yes

category<N>Id

where <N> is an

integer from 1 to 5

The internal ID of the associated service

line <N> (category_<N>).

integer($int64) Yes Yes Yes

costCenterId The internal ID of the associated cost

center.

integer($int64) Yes Yes Yes

created Time the record was created. string($date-time) Yes Yes —

customerId The internal ID of the associated

customer.

integer($int64) — Yes Yes

date The date of the time entry. string($date-time) — Yes Yes

decimalHours The number of decimal hours for the

time entry. Decimal time entry for the

number of hours is supported if the

feature Use Days Instead of Hours for All

Time Entries is disabled for your account.

You should not use the features Enable

Start and End Tme Entry on Timesheets

and Use Days Instead of Hours for

All Time Entries in conjunction. When

Enable Start and End Tme Entry on

Timesheets is enabled and a user enters

a start time and end time in OpenAir, the

duration is calculated in hours and not

converted to days. When using the API

and both features are enabled, passing

decimal_hours and minutes but not

hours in the API call will result in an error

(error code 1407).

number($float) — Yes —

description The description of the time entry. string — Yes —

endTime The time entry end time. string($date-time) — Yes —

exported Date and time the time entry was

marked as "exported".

string($date-time) — Yes —

hour The number of hours for the time entry. number($float) — Yes —

hoursRemaining The number of hours remaining of the

associated project task.

number($float) — — —

id The unique internal identifier of the time

entry. Assigned by OpenAir.

integer($int64) Yes Yes Yes

jobCodeId The internal ID of the associated job

code.

integer($int64) — Yes Yes

minute The number of minutes for the time

entry. Must be an integer.

integer($int64) — Yes —

REST API

Time Entries 250

Property Description Type Read-

only

Query

allowed

Sorting

allowed

notes Notes about this time entry. string — Yes —

payrollTypeId The internal ID of the associated payroll

type.

integer($int64) — Yes Yes

projectId The internal ID of the associated project. integer($int64) — Yes Yes

projectTaskId The internal ID of the task within the

associated project.

integer($int64) — Yes Yes

projectTaskTypeId The internal ID of the project task type of

the associated project task.

integer($int64) — Yes Yes

scheduleRequest

ItemId

The internal ID of the schedule change

item from a schedule request

integer($int64) Yes Yes Yes

slipId The internal ID of the associated slip if

this time entry was billed.

integer($int64) Yes Yes Yes

startTime The time entry start time. string($date-time) — Yes —

thinClientId Used by thin clients to reconcile

imported records.

string Yes Yes Yes

timesheetId [REQUIRED] The internal ID of the

associated timesheet.

integer($int64) — Yes Yes

timeTypeId The internal ID of the associated time

type.

integer($int64) — Yes Yes

updated The date the time entry was last updated

or modified.

string($date-time) Yes Yes Yes

userId The internal ID of the associated

employee.

integer($int64) Yes Yes Yes

Note: Access to certain object types and object attributes depend on the business logic

configured for the OpenAir account. It may vary depending on the role and access privileges

associated with the access token and with the user who authorized the application.

Required and read-only attributes also depend on the business logic configured for each specific

OpenAir account. Some fields such as id, created, and updated are system-generated and always

read-only.

Insert a Time Entry

POST /time-entries/ — Use this method to create a new time entry record.

Parameters

Path parameters

None

REST API

Time Entries 251

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion.

The comma-separated list may include spaces (or %20 in the URL

encoded string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object

is set to any value other than 0 (zero), and the comma-

separated list includes at least one attribute that is not

available for expansion, the request fails — an error is

returned and the object is not added or updated. For

more information about attributes available for expansion

and supported object types, see Available Expansions and

Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response.

If not specified, the response includes all attributes for the time

entry returned.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

associated with the user who authorized the application as per

the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

integer

return_object Optional If set to 1, the response will return the time entry created.

Otherwise, the response will include only the internal ID of the

time entry created.

Boolean

Request body

The TimeEntry object to be created. The object must include valid key-value pairs for all required

attributes and cannot include key-value pairs for read-only attributes. For information about the

TimeEntry object model, see Contact object properties.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing one of the following:

■

The TimeEntry object created, if the return_object parameter was set to any value other than 0

(zero) in the request. The object includes all the attributes specified using the fields if included in

the request.

■

An object with only the internal ID of the time entry created.

See Returned Data.

REST API

Time Entries 252

Property Description

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID). Only returned if the return_object parameter was set to any value other than 0 (zero)

in the request.

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

POST /rest/v1/time-entries/ HTTP/1.1

Host: company-id.app.openair.com

Content-Type: application/json

Authorization: Bearer <OAuth2_access_token>

{

"hour": 8,

"categoryId": 2,

"timeTypeId": 1,

"date": "2023-03-05",

"projectTaskId": 502,

"jobCodeId": 1,

"timesheetId": 497,

"customerId": 13,

"costCenterId": 1,

"projectId": 312,

"userId": 68

}

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 45681

}

"message": "success"

}

Get the List of Time Entries

GET /time-entries/ — Use this method to retrieve the list of time entries.

REST API

Time Entries 253

Parameters

Path parameters

None

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion. The

comma-separated list may include spaces (or %20 in the URL encoded

string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object is set

to any value other than 0 (zero), and the comma-separated

list includes at least one attribute that is not available for

expansion, the request fails — an error is returned and the

object is not added or updated. For more information about

attributes available for expansion and supported object

types, see Available Expansions and Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for each time entry

returned. See Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is available

when the specified filter set is active in OpenAir. The filter set with

the specified internal ID must exist and must be associated with

the user who authorized the application as per the access token.

■

Otherwise and by default, the primary filter set associated with the

user who authorized the application is applied.

integer

limit Optional A limit on the length of the page. See Pagination. integer

offset Optional A cursor for use in pagination. See Pagination. integer

orderBy Optional The attribute to sort the list by. Use a plus sign (+) or minus sign (-)

before the attribute name to specify an ascending (+) or descending

(-) sort order. An ascending sort order is used if the sort order is not

specified. See Sorting.

string

q Optional A URL-encoded query expression used to filter the resource

collection and return the objects matching the specified search

criteria. See Filtering.

string

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the time entries requested. See Returned Data.

REST API

Time Entries 254

Property Description

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing response metadata. The meta object may include information about:

■

The page returned, the number of objects per page, the total number of pages and objects in the

list, and links to other pages. See Pagination.

■

Objects referenced by internal ID in the data array (object type and internal ID). See Referenced

Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request.

Sample request

GET /rest/v1/time-entries/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

...

{

...

"message": "success",

"meta": {

"rowsPerPage": 100,

"totalPages": 14,

"relationships": [

{

...

{

...

"totalRows": 1386,

"links": [

{

"rel": "first",

"href": "https://company-id.app.openair.com/rest/v1/time-entries"

{

REST API

Time Entries 255

"rel": "self",

"href": "https://company-id.app.openair.com/rest/v1/time-entries"

{

"rel": "next",

"href": "https://company-id.app.openair.com/rest/v1/time-entries?limit=100&offset=100"

{

"rel": "last",

"href": "https://company-id.app.openair.com/rest/v1/time-entries?limit=100&offset=1300"

}

]

}

Get a Time Entry

GET /time-entries/{id} — Use this method to retrieve the time entry record with the specified internal

ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the time entry. integer

Query string parameter

Path parameter Required /

Optional

Description Type

expand Optional A comma-separated list of attributes available for expansion. The

comma-separated list may include spaces (or %20 in the URL encoded

string).

Note: The expand value must contain only attributes

referencing a supported object type. If return_object is set

to any value other than 0 (zero), and the comma-separated

list includes at least one attribute that is not available for

expansion, the request fails — an error is returned and the

object is not added or updated. For more information about

attributes available for expansion and supported object

types, see Available Expansions and Supported Object Types.

string

fields Optional A comma-separated list of attributes to include in the response. If

not specified, the response includes all attributes for the time entry

returned. Response Data Modifiers.

string

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the response includes only data that is available

when the specified filter set is active in OpenAir. The filter set with

the specified internal ID must exist and must be associated with

the user who authorized the application as per the access token.

integer

REST API

Time Entries 256

Path parameter Required /

Optional

Description Type

■

Otherwise and by default, the primary filter set associated with the

user who authorized the application is applied.

Response definitions

A successful request returns a JSON object with the following properties:

Property Description

data An array containing the time entry object requested. See Returned Data.

included An array of expanded objects, if the expand parameter was set in the request.

See Referenced Objects and Expansion.

meta An object containing information about objects referenced by internal ID in the data array (object type

and internal ID).

See Referenced Objects and Expansion.

message A string containing a brief message about the status of your request — e.g. “Success”.

A failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Time Entry #24 not

found”.

Sample request

GET /rest/v1/time-entries/24 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"hour": 8,

"categoryId": 2,

"timeTypeId": 1,

"date": "2012-03-05",

"endTime": "00:00:00",

"timesheetRowId": 0,

"category4Id": 0,

"decimalHours": 0,

"projectTaskId": 502,

"updated": "2013-11-16 08:49:03",

"startTime": "00:00:00",

"id": 1,

"slipId": 0,

REST API

Time Entries 257

"accountDate": "0000-00-00",

"autoBillCode": "",

"jobCodeId": 1,

"timesheetId": 1,

"description": "",

"minute": 0,

"customerId": 13,

"costCenterId": 1,

"scheduleRequestItemId": 0,

"projectTaskTypeId": 1,

"thinClientId": 0,

"projectId": 31,

"category3Id": 0,

"category5Id": 0,

"payrollTypeId": 0,

"userId": 2,

"category2Id": 0,

"created": "2013-11-01 14:46:07",

"category1Id": 0,

"notes": "",

"exported": "0000-00-00 00:00:00"

}

"meta": {

"relationships": [

{

"userId": {

"data": {

"id": 2,

"type": "userDisplayName"

}

]

"message": "success"

}

Delete a Time Entry

DELETE /time-entries/{id} — Use this method to delete the time entry record with the specified internal

ID.

Parameters

Path parameters

Path parameter Required / Optional Description Type

{id} Required The internal ID of the time entry. integer

Query string parameter

Path parameter Required /

Optional

Description Type

filterSetId Optional The internal ID of the filter set to be applied.

■

When specified, the request is successful only if the action is

available when the specified filter set is active in OpenAir. The

filter set with the specified internal ID must exist and must be

integer

REST API

Time Entries 258

Path parameter Required /

Optional

Description Type

associated with the user who authorized the application as

per the access token.

■

Otherwise and by default, the primary filter set associated with

the user who authorized the application is applied.

Response definitions

A successful or failed request returns a JSON object with the following properties:

Property Description

message A string containing a brief message about the status of your request — e.g. “Success” or “TimeEntry

#24 not found”.

Sample request

DELETE /rest/v1/rest/v1/time-entries/24 HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

{

"data": [

{

"id": 24

}

"message": "success"

}

Discover Available Methods and Fetch the Endpoint

Reference for Time Entries

OPTIONS /time-entries/ — Use this method to discover the methods available and fetch the OpenAPI

3.0 JSON endpoint reference for time entries.

Parameters

None

Response definitions

A successful request returns the OpenAPI 3.0 JSON endpoint reference in the response body. The

JSON object returned contains metadata information about the resource endpoint. It is similar to the

REST API

Time Entries 259

Generated API Documentation JSON, only it is restricted to the resource endpoint path specified in the

request.

The response also includes the following header:

Header Description

Access-Control-Allow-Methods A comma-separated list of HTTP methods available for the requested

resource collection endpoint.

Sample request

OPTIONS /rest/v1/time-entries/ HTTP/1.1

Host: company-id.app.openair.com

Authorization: Bearer <OAuth2_access_token>

In the example, <OAuth2_access_token> is the OAuth 2.0 access token obtained for the client application

connecting to OpenAir. See Authentication.

Sample response

The response includes the OpenAPI 3.0 endpoint reference for the resource endpoint as a JSON object in

the response body, as well as the following headers:

Content-Type: application/json; charset=utf-8

Content-Length: 6955

Connection: keep-alive

Cache-control: no-cache, no-store, pre-check=0, post-check=0, must-revalidate, max-age=0, s-max-age=0

Pragma: no-cache

Expires: 0

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS

Access-Control-Allow-Headers: Content-Type

Access-Control-Max-Age: 86400

Vary: Accept-Encoding,User-Agent

Content-Encoding: gzip

REST API

Release History 260

Release History

October 7, 2023

■

Added the following resources:

□

TimeEntry — See Time Entries and Time entry object properties.

■

Added the following endpoints and methods:

□

PUT /expense-reports/{id}/attachments/{attachment_id} — See Replace an Attachment to an

Expense Report

□

PUT /projects/{id}/attachments/{attachment_id} — See Replace an Attachment to a Project

□

GET /project-tasks/{id}/attachments/{attachment_id}/thumbnail — See Get the Thumbnail for

an Attachment Associated with a Project Task

□

PUT /project-tasks/{id}/attachments/{attachment_id} — See Replace an Attachment to a

Project Task

□

PUT /receipts/{id}/attachments/{attachment_id} — See Replace an Attachment to a Receipt

□

POST /time-entries/ — See Insert a Time Entry

□

GET /time-entries/ — See Get the List of Time Entries

□

GET /time-entries/{id} — See Get a Time Entry

□

DELETE /time-entries/{id} — See Delete a Time Entry

□

OPTIONS /time-entries/ — See Discover Available Methods and Fetch the Endpoint Reference for

Time Entries

■

The following methods also support the Sorting feature:

□

GET /expense-reports/{id}/attachments/ — See Get the List of Attachments Associated with an

Expense Report.

□

GET /projects/{id}/attachments — See Get the List of Attachments Associated with a Project

□

GET /project-tasks/{id}/attachments — See Get the List of Attachments Associated with a Project

Task

□

GET /receipts/{id}/attachments/ — See Get the List of Attachments Associated with a Receipt.

April 15, 2023

■

Support for automatically generated thumbnail image when adding an attachment (Attachment

Thumbnail feature). See Add an Attachment to an Expense Report, Add an Attachment to a Project,

Add an Attachment to a Project Task, Add an Attachment to a Receipt.

■

Added the following endpoints and methods:

□

GET /expense-reports/{id}/attachments/{attachment_id}/thumbnail — See Get the Thumbnail

for an Attachment Associated with an Expense Report

□

GET /projects/{id}/attachments/{attachment_id}/thumbnail — See Get the Thumbnail for an

Attachment Associated with a Project

□

GET /receipts/{id}/attachments/{attachment_id}/thumbnail — See Get the Thumbnail for an

Attachment Associated with a Receipt

■

Added support for sorting returned list of resources in ascending or descending sort order (single

sorting level). The Sorting feature supports the following methods:

REST API

October 8, 2022 261

□

GET /contacts/ — See Get the List of Contacts

□

GET /expense-reports/ — See Get the List of Expense Reports

□

GET /expense-reports/{id}/receipts — See Get the List of Receipts in an Expense Report

□

GET /job-codes/ — See Get the List of Job Codes

□

GET /projects/ — See Get the List of Projects

□

GET /project-milestones/ — See Get the List of Project Milestones

□

GET /project-phases/ — See Get the List of Project Phases

□

GET /project-tasks/ — See Get the List of Project Tasks

□

GET /receipts/ — See Get the List of Receipts

■

Added Attachment object property isViewable indicating if the attachment is viewable in the

Attachment Viewer feature — See Attachments.

October 8, 2022

■

Added the following resources:

□

ProjectMilestone — See ProjectMilestone Object Properties.

□

ProjectPhase — See ProjectPhase Object Properties.

□

ProjectTask — See ProjectTask Object Properties.

■

Added the following endpoints and methods:

□

POST /projects/from-template/ — See Create a Project from Template

□

POST /projects/{id}/attachments — See Add an Attachment to a Project

□

GET /projects/{id}/attachments — See Get the List of Attachments Associated with a Project

□

GET /projects/{id}/attachments/{attachment_id} — See Get an Attachment Associated with a

Project

□

GET /projects/{id}/attachments/{attachment_id}/download — See Get an Attachment File

Associated with a Project

□

DELETE /projects/{id}/attachments/{attachment_id} — See Delete an Attachment Associated

with a Project

□

DELETE /projects/{id}/attachments/{attachment_ids} — See Delete Attachments Associated with

a Project

□

GET /project-milestones/ — See Get the List of Project Milestones

□

GET /project-milestones/{id} — See Get a Project Milestone

□

GET /project-phases/ — See Get the List of Project Phases

□

GET /project-phases/{id} — See Get a Project Phase

□

POST /project-tasks/ — See Insert a Project Task

□

GET /project-tasks/ — See Get the List of Project Tasks

□

GET /project-tasks/{id} — See Get a Project Task

□

POST /project-tasks/{id}/attachments — See Add an Attachment to a Project Task

□

GET /project-tasks/{id}/attachments — See Get the List of Attachments Associated with a Project

Task

□

GET /project-tasks/{id}/attachments/{attachment_id} — See Get an Attachment Associated with

a Project Task

REST API

April 9, 2022 262

□

GET /project-tasks/{id}/attachments/{attachment_id}/download — See Get an Attachment File

Associated with a Project Task

□

DELETE /project-tasks/{id}/attachments/{attachment_id} — See Delete an Attachment

Associated with a Project Task

□

DELETE /project-tasks/{id}/attachments/{attachment_ids} — See Delete Attachments

Associated with a Project Task

■

The filterSetId query string parameter can be used to specify the internal ID of the filter set to be

applied when inserting or updating objects using a POST or PUT method or deleting an object using

the DELETE method. All available REST API resources and CRUD methods now support the parameter.

See Active Filter Set, Errors and all POST, PUT, and DELETE methods in REST API Endpoint Reference.

■

The Filtering and Pagination features are supported when working with Contacts and Job Codes using

the REST API. See Supported Resources, Methods and API Features.

April 9, 2022

■

Added the following endpoints and methods:

□

POST /projects/ — See Insert a Project

□

POST /projects/bulk/ — See Insert Multiple Projects

□

PUT /projects/{id} — See Update a Project

□

PUT /projects/bulk/{ids} — See Update Multiple Projects

□

DELETE /projects/{id} — See Delete a Project

□

DELETE /projects/bulk/{ids} — See Delete Multiple Projects

■

Added request query string parameter filterSetId to specify the internal ID of the filter set to be

applied when retrieving data using a GET method. See Active Filter Set, Errors and all GET methods in

REST API Endpoint Reference.

■

Changes to Project object properties:

□

Added properties filterSetIds (filter sets the project is included in) and hierarchyNodes (project

hierarchy nodes, available when reading, updating or creating projects).

□

Removed properties costTypeFilter, customerExcludeFilter, projectExcludeFilter — These fields

are part of a feature that is not supported by the REST API.

■

Changes to Referenced Objects and Expansion:

□

The number of expanded objects that can be returned in the included array is limited to 1,000

objects by default.

□

If expanded objects are referenced by metavalues (negative integers) instead of internal IDs in the

main response element (data array), the response substitutes the object internal IDs for metavalue

references in the relationships array.

October 9, 2021

■

Added the following endpoints and methods:

□

GET /projects/ — See Get the List of Projects

□

GET /projects/{id} — See Get a Project

□

OPTIONS /projects/ — See Discover Available Methods and Fetch the Endpoint Reference for

Projects

REST API

April 10, 2021 263

□

DELETE /receipts/{id} — See Delete a Receipt

■

Added support for deleting multiple expense attachments. Updated the following methods:

□

DELETE /expense-reports/{id}/attachments/{attachment_ids} — See Delete Attachments

Associated with an Expense Report.

□

DELETE /receipts/{id}/attachments/{attachment_ids} — See Delete Attachments Associated with

a Receipt.

■

The /attachments/{id} and /attachments/{id}/download endpoints were removed from the REST API.

To work with attachments, use the endpoints and methods specific to the object the attachments are

associated with. See Attachments.

■

OAuth 2.0 access token validity period cannot be greater than session timeout — See Application

Configuration.

■

OAuth 2.0 refresh token validity period can be between 1 and 31 days in one–day increments — sSee

Application Configuration.

April 10, 2021

■

The service path for the REST API is /rest/v1/ instead of /webapi/v2/ — See Request URL.

■

Added the following methods:

□

OPTIONS /contacts/ — See Discover Available Methods and Fetch the Endpoint Reference for

Contacts.

□

POST /expense-reports/{id}/attachments/ — See Add an Attachment to an Expense Report.

□

GET /expense-reports/{id}/attachments/ — See Get the List of Attachments Associated with an

Expense Report.

□

GET /expense-reports/{id}/attachments/{attachment_id} — See Get an Attachment Associated

with an Expense Report.

□

GET /expense-reports/{id}/attachments/{attachment_id}/download — See Get an Attachment File

Associated with an Expense Report.

□

DELETE /expense-reports/{id}/attachments/{attachment_id} — See Delete Attachments

Associated with an Expense Report.

□

OPTIONS /expense-reports/ — See Discover Available Methods and Fetch the Endpoint Reference

for Expense Reports.

□

OPTIONS /job-codes/ — See Discover Available Methods and Fetch the Endpoint Reference for

Job Codes.

□

POST /receipts/{id}/attachments/ — See Add an Attachment to a Receipt.

□

GET /receipts/{id}/attachments/ — See Get the List of Attachments Associated with a Receipt.

□

GET /receipts/{id}/attachments/{attachment_id} — See Get an Attachment Associated with a

Receipt.

□

GET /receipts/{id}/attachments/{attachment_id}/download — See Get an Attachment File

Associated with a Receipt.

□

DELETE /receipts/{id}/attachments/{attachment_id} — See Delete Attachments Associated with

a Receipt.

□

OPTIONS /receipts/ — See Discover Available Methods and Fetch the Endpoint Reference for

Receipts.

■

Added the following resource object attributes:

REST API

October 10, 2020 264

□

Attachment — Added the workspaceId attribute, the internal ID of the workspace associated with

the attachment. The value is 0 (zero) if the attachment is not associated with a workspace. See

Attachment object properties.

■

Added support for expanding objects referenced by internal ID in the main response elements (data

array) — If there are any attributes available for expansion, the response automatically includes a

relationships property in the response metadata (meta object) with information about the attributes

available for expansion and the referenced objects. The expand query parameter can be used to return

expanded objects of type attachment, userDisplayName, and workspace in the included response

property without the need for separate requests. Some of this additional data is only available when

using expansion. See Referenced Objects and Expansion.

■

Added Auditing and Managing OAuth 2.0 Authorizations under OAuth 2.0 Authorization — Account

administrators can use web services reports to audit and revoke authorizations granted by OpenAir

users to integration applications.

October 10, 2020

■

Initial version of REST API released.

REST API