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.

The request URL includes:

1. 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.

2. 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.

3. 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.

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:

• 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.