OData¶

Introduction¶

With the OData API, you can send requests to a published app to get an app's metadata (its domain model), or to create, get, update, or delete records. Request options let you expand lookup fields, filter results, and sort results. You can make requests one at time, or group them into a batch request. You authorize requests with OAuth2 or basic authentication.

Important

Requests must refer to modules and fields using their internal database identifiers. To see these in the app developer's UI, activate Display DB Identifiers in This App on the app's Overview page.

You can send the following OData API requests to a published app:

Request	Method	URL Format
Get an OAuth2 Authorization Token	POST	`https://apps.<REGION>.lcap.jitterbit.com/auth/connect/token`
Get an App's Metadata	GET	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/$metadata`
Create a Record	POST	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>`
Get All Records	GET	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>`
Get a Record by ID	GET	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>(<N>)`
Update a Record by ID	PUT	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>`
Delete a Record by ID	DELETE	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>(<N>)`
Get Records with the `expand` Option	GET	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$expand=<EXPR>`
Get Records with the `filter` Option	GET	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$filter=<EXPR>`
Get Records with the `orderby` Option	GET	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$orderby=<EXPR>`
Batch Requests	GET	`https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/$batch`

The requests on this page use the following keywords to denote values that you must provide:

Keyword	Replace with
`<ACCESS-TOKEN>`	The value for access_token in the response to Get an OAuth2 Authorization Token.
`<CLIENT-ID>`	The value for Client ID, copied from the app's Overview page.
`<CLIENT-SECRET>`	The value for Client Secret, copied from the app's Overview page.
`<EXPR>`	An OData system query option expression for `expand`, `filter`, or `orderby`, depending on the request.
`<MODULE-ID>`	The internal database identifier for a module.
`<N>`	A record ID.
`<REGION>`	The region where your app is published, one of `na-east`, `emea-west`, or `apac-southeast`.
`<TENANT-ID>`	The app's tenant ID. To find it, go to your published app, open your browser's developer tools, then open the console and enter `tenantId`. The number returned is the tenant ID.
`<USERNAME>`	The email address for your app's administrator account.
`<PASSWORD>`	The password for your app's administrator account.

Authorize¶

All requests must be authorized, using either OAuth2 or Basic Auth.

OAuth2¶

To use OAuth2 authentication, send the following request and save the response's access_token value for use in subsequent requests:

Request: POST https://apps.<REGION>.lcap.jitterbit.com/auth/connect/token
- Body (x-www-form-urlencoded):
  
  Key Value
  
  client_id <CLIENT-ID>
  
  client_secret <CLIENT-SECRET>
  
  grant_type password
  
  username <USERNAME>
  
  password <PASSWORD>

Response (application/json):

Key	Value
access_token	The access token. Copy it for use in subsequent calls (replacing the keyword `<ACCESS-TOKEN>`).
expires_in	The token's expiry time, in seconds. (Not used.)
token_type	Bearer (Not used.)
scope	api1 email openid profile (Not used.)

Example

{
    "access_token": "EyJhbGciOiJSUzI1NiIsImtpZCI6IkY5QjA2M0IwRENENTk5OTJDNjdEMzIzOTlFNUY1MjZERTg4RUQzRENSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6Ii1iQmpzTnpWbVpMR2ZUSTVubDlTYmVpTzA5dyJ9.EyJuYmYiOjE2NzQ0ODgyMzYsImV4cCI6MTY3NTM1MjIzNiwiaXNzIjoiaHR0cHM6Ly9hcHBzLnFhLWdyZWVuLmxjYXAuaml0dGVyYml0LmNvbS9hdXRoIiwiYXVkIjoiYXBpMSIsImNsaWVudF9pZCI6Im9kYXRhdGVzdCIsInN1YiI6IjQyMjNhODdjLTk5M2UtNDlmNC04ZWQzLTEwNDBlZTQwYWJiMiIsImF1dGhfdGltZSI6MTY3NDQ4ODIzNSwiaWRwIjoibG9jYWwiLCJuYW1lIjoiUGF1bCBKYWNvYnMiLCJnaXZlbl9uYW1lIjoiUGF1bCIsImZhbWlsEV9uYW1lIjoiSmFjb2JzIiwiZW1haWwiOiJwYXVsLmphY29icytncmVlbnFhQGppdHRlcmJpdC5jb20iLCJlbWFpbF92ZXJpZmllZCI6ImZhbHNlIiwiZW1haWxfY29uZmlybWVkIjoiRmFsc2UiLCJlEHRlcm5hbF9sb2dpbiI6ImZhbHNlIiwiYXBwX2lkIjoiOTcxIiwidGVuYW50X2lkIjoiNjI5IiwianRpIjoiNjlGNTU2NDgwNUU4NjE1RTQyRUQ0Q0JGRjc5MDgyNTIiLCJpYXQiOjE2NzQ0ODgyMzYsInNjb3BlIjpbImFwaTEiLCJlbWFpbCIsIm9wZW5pZCIsInByb2ZpbGUiXSwiYW1yIjpbInB3ZCJdfQ.NtcMT5t7CK1Ibv4bQD8nix7_oEovNFZWjkIE3UNDpJFRGfXxsDMIYEPRgCOMBf2axSYOdc_w4aCpHjbvsNyo63oLRY5Wf6vGvqcI224XB4_UXcOCbFUKvUKWV6qZCmTa6X5Q1K04V75PhcJqr-5Kg5q99Oyn3H4L1E38kXpGxy7BCoPljv_L_8cBZ5tEkj0RmGuX88x49wLZTLjSCa83N4fDtF0sDRujXmywPkolOjTO4_bldovU-0Cg4BgQBC8oU_CcavlRWmEqZtu0xdlI4HM3UtEHB3CbinNhLKGcBE6XaoHQ0i0-cOs9M3rgqVL3RiwJHTCL9rw6DoTctZ5qCw",
    "expires_in": 864000,
    "token_type": "Bearer",
    "scope": "api1 email openid profile"
}

Subsequent requests must contain a header as follows:

Key	Value
Authorization	`Bearer <ACCESS-TOKEN>`
x-client-id	`<CLIENT-ID>`
x-tenant-id	`<TENANT-ID>`

Note

The OData API uses role-based access control (RBAC) and App Builder profiles for security and authentication. The user specified in the request body must have a profile that gives the necessary permissions for subsequent requests.

Basic Auth¶

To use the OData API with basic authentication, an app administrator must activate the Enable Personal Access Token setting in the user's Employees record. The user can then generate a personal access token (PAT) by logging in to the app and opening the Personal Access Token section of the user menu. Basic auth OData API requests use the user's login name as the username, and the PAT as the password.

Requests¶

Get an App's Metadata¶

Request: GET https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/$metadata

Response (application/xml): Details of the fields and keys for each module in the app's domain model.

Example

Response for request to get metadata for a newly-created app:

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
    <edmx:DataServices>
        <Schema Namespace="Jitterbit.AppBuilder.Entities" xmlns="http://docs.oasis-open.org/odata/ns/edm">
            <EntityType Name="audit_trail">
                <Key>
                    <PropertyRef Name="id" />
                </Key>
                <Property Name="log_id" Type="Edm.String" Nullable="false" />
                <Property Name="is_sample" Type="Edm.Boolean" />
                <Property Name="updated_at" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="updated_by" Type="Edm.Int64" Nullable="false" />
                <Property Name="created_at" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="created_by" Type="Edm.Int64" Nullable="false" />
                <Property Name="owner" Type="Edm.Int64" />
                <Property Name="detail" Type="Edm.String" />
                <Property Name="status" Type="Edm.String" />
                <Property Name="operation" Type="Edm.String" />
                <Property Name="related_record" Type="Edm.String" />
                <Property Name="module" Type="Edm.String" />
                <Property Name="duration" Type="Edm.Decimal" />
                <Property Name="end_date" Type="Edm.DateTimeOffset" />
                <Property Name="start_date" Type="Edm.DateTimeOffset" />
                <Property Name="source" Type="Edm.String" />
                <Property Name="id" Type="Edm.Int64" Nullable="false" />
                <Property Name="p_external_id" Type="Edm.String" />
                <Property Name="p_is_draft" Type="Edm.Boolean" />
                <NavigationProperty Name="p_assigned_to" Type="Jitterbit.AppBuilder.Entities.p_employees" Nullable="false" />
            </EntityType>
            <EntityType Name="p_employees">
                <Key>
                    <PropertyRef Name="id" />
                </Key>
                <Property Name="employee_id" Type="Edm.Int64" />
                <Property Name="name" Type="Edm.String" Nullable="false" />
                <Property Name="is_sample" Type="Edm.Boolean" />
                <Property Name="updated_at" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="updated_by" Type="Edm.Int64" Nullable="false" />
                <Property Name="created_at" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="created_by" Type="Edm.Int64" Nullable="false" />
                <Property Name="owner" Type="Edm.Int64" />
                <Property Name="manager_id" Type="Edm.String" />
                <Property Name="organization" Type="Edm.String" />
                <Property Name="email" Type="Edm.String" Nullable="false" />
                <Property Name="surname" Type="Edm.String" Nullable="false" />
                <Property Name="management_chain" Type="Edm.String" />
                <Property Name="direct_reports" Type="Edm.String" />
                <Property Name="peers" Type="Edm.String" />
                <Property Name="active" Type="Edm.Boolean" />
                <Property Name="full_name" Type="Edm.String" Nullable="false" />
                <Property Name="username" Type="Edm.String" />
                <Property Name="language" Type="Edm.String" />
                <Property Name="p_photo" Type="Edm.String" />
                <Property Name="id" Type="Edm.Int64" Nullable="false" />
                <Property Name="p_theme" Type="Edm.String" />
                <Property Name="p_last_login_date" Type="Edm.DateTimeOffset" />
                <Property Name="p_external_id" Type="Edm.String" />
                <Property Name="p_is_draft" Type="Edm.Boolean" />
                <NavigationProperty Name="profile" Type="Jitterbit.AppBuilder.Entities.p_profiles" Nullable="false" />
                <NavigationProperty Name="manager" Type="Jitterbit.AppBuilder.Entities.p_employees" Nullable="false" />
                <NavigationProperty Name="p_assigned_to" Type="Jitterbit.AppBuilder.Entities.p_employees" Nullable="false" />
                <NavigationProperty Name="p_peers" Type="Collection(Jitterbit.AppBuilder.Entities.p_employees)" />
                <NavigationProperty Name="p_direct_reports" Type="Collection(Jitterbit.AppBuilder.Entities.p_employees)" />
                <NavigationProperty Name="p_organization" Type="Collection(Jitterbit.AppBuilder.Entities.p_employees)" />
                <NavigationProperty Name="p_management_chain" Type="Collection(Jitterbit.AppBuilder.Entities.p_employees)" />
            </EntityType>
            <EntityType Name="p_profiles">
                <Key>
                    <PropertyRef Name="id" />
                </Key>
                <Property Name="name" Type="Edm.String" Nullable="false" />
                <Property Name="profile_id" Type="Edm.String" Nullable="false" />
                <Property Name="owner" Type="Edm.Int64" />
                <Property Name="created_by" Type="Edm.Int64" Nullable="false" />
                <Property Name="created_at" Type="Edm.DateTimeOffset" Nullable="false" />
                <Property Name="updated_by" Type="Edm.Int64" Nullable="false" />
                <Property Name="updated_at" Type="Edm.DateTimeOffset" />
                <Property Name="is_sample" Type="Edm.Boolean" />
                <Property Name="configs" Type="Edm.String" />
                <Property Name="id" Type="Edm.Int64" Nullable="false" />
                <Property Name="p_external_id" Type="Edm.String" />
                <Property Name="p_is_draft" Type="Edm.Boolean" />
                <NavigationProperty Name="p_assigned_to" Type="Jitterbit.AppBuilder.Entities.p_employees" Nullable="false" />
            </EntityType>
            <EntityContainer Name="container">
                <EntitySet Name="audit_trail" EntityType="Jitterbit.AppBuilder.Entities.audit_trail">
                    <NavigationPropertyBinding Path="p_assigned_to" Target="p_employees" />
                </EntitySet>
                <EntitySet Name="p_employees" EntityType="Jitterbit.AppBuilder.Entities.p_employees">
                    <NavigationPropertyBinding Path="manager" Target="p_employees" />
                    <NavigationPropertyBinding Path="p_assigned_to" Target="p_employees" />
                    <NavigationPropertyBinding Path="p_direct_reports" Target="p_employees" />
                    <NavigationPropertyBinding Path="p_management_chain" Target="p_employees" />
                    <NavigationPropertyBinding Path="p_organization" Target="p_employees" />
                    <NavigationPropertyBinding Path="p_peers" Target="p_employees" />
                    <NavigationPropertyBinding Path="profile" Target="p_profiles" />
                </EntitySet>
                <EntitySet Name="p_profiles" EntityType="Jitterbit.AppBuilder.Entities.p_profiles">
                    <NavigationPropertyBinding Path="p_assigned_to" Target="p_employees" />
                </EntitySet>
            </EntityContainer>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Create a Record¶

Request: POST https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>
- Body (raw, application/json): The new record's field IDs and values.
  Example
  
  Request: POST https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1//entities/p_employees
  
  Body:
```
{
    "name": "Firstname",
    "surname": "Surname",
    "manager_id": null,
    "organization": null,
    "email": "firstname.surname@example.com",
    "active": false,
    "full_name": "Firstname Surname"
}
```

Response (application/json): A copy of the new record.

Example

{
    "name": "Firstname",
    "surname": "Surname",
    "manager_id": null,
    "organization": null,
    "email": "firstname.surname@example.com",
    "active": false,
    "full_name": "Firstname Surname",
    "owner": 44,
    "p_assigned_to": 1,
    "language": "en",
    "id": 68,
    "created_by": 44,
    "updated_by": 44,
    "created_at": "2023-01-23T12:00:00.00000Z",
    "updated_at": "2023-01-23T12:00:00.00000Z",
    "deleted": false
}

Get All Records¶

Request: GET https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>
Response (application/json): Requested records (maximum 1000). To retrieve more records, use the OData system query options top and skip.

Get a Record by ID¶

Request: GET https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>(<N>)
Response (application/json): The requested record.

Update a Record by ID¶

Request: PUT https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>(<N>)
- Body (raw): The updated record's field IDs and values in JSON format.
Response (application/json): A copy of the updated record.

Delete a Record by ID¶

Request: DELETE https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>(<N>)
Response: An empty body with an HTTP 200 status code.

Request Options¶

Use the following options to expand, filter, and sort responses.

Get Records with the `expand` Option¶

Request: GET https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$expand=<EXPR>
Response (application/json): Records with expanded fields.

Examples

Values for lookup and multi-lookup fields appear as null in request responses. To expand their values, use the $expand option as follows:
```
https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$expand=<FIELD-ID>
```
- <FIELD-ID>: Lookup or multi-lookup field ID.
To expand more than one field, append comma-separated field IDs to the option, as follows:
```
https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$expand=<FIELD-ID_1>,<FIELD-ID_2>,...
```
- <FIELD-ID_1>, <FIELD-ID_2>: Lookup or multi-lookup field IDs.

To recursively expand retrieved results, use the option as a function, as follows:

https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$expand=<FIELD-ID_1>($expand=<FIELD-ID_2>($expand=<FIELD-ID_2>($expand=<FIELD-ID_2>($filter=id eq 1))))

Get Records with the `filter` Option¶

Request: GET https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$filter=<EXPR>
Response (application/json): Records that satisfy the filter expression.

Get Records with the `orderby` Option¶

Request: GET https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$orderby=<EXPR>
Example

GET https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/<MODULE-ID>?$orderby=<FIELD_NAME_1>,length(<FIELD_NAME_2>) <SORT-ORDER>
- <FIELD_NAME_1>: The name of the first field to order your results by.
- length(<FIELD_NAME_2>): The length of the name of the second field to order the results by. (length is an OData canonical function. Additional functions can be appended to further refine the response.) To sort on only the first field, omit ,length(<FIELD_NAME_2>) from the URL.
- <SORT-ORDER>:
  - asc: Sort the results in ascending order on <FIELD_NAME_1>.
  - desc: Sort the results in descending order on <FIELD_NAME_1>.
Response (application/json): Records sorted according to <EXPR>.

Batch Requests¶

Request: GET https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/$batch

Body (raw, application/json): A single requests array with request elements, each having these keys and values:

Key	Value
id	A unique integer identifier for the request.
method	The request's method.
url	The request's URL.

Example

Body to request all records from the Employees and Profiles modules:

{
    "requests": [
        {
            "id": "1",
            "method": "GET",
            "url": "https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/p_employees"
        },
        {
            "id": "2",
            "method": "GET",
            "url": "https://<CLIENT-ID>.apps.<REGION>.lcap.jitterbit.com/odata/v1/entities/p_profiles"
        }
    ]
}

Response (application/json): A single responses array with response elements, one per request.

Key	Value
client_id	`<CLIENT-ID>`
client_secret	`<CLIENT-SECRET>`
grant_type	password
username	`<USERNAME>`
password	`<PASSWORD>`

OData¶

Introduction¶

Authorize¶

OAuth2¶

Basic Auth¶

Requests¶

Get an App's Metadata¶

Create a Record¶

Get All Records¶

Get a Record by ID¶

Update a Record by ID¶

Delete a Record by ID¶

Request Options¶

Get Records with the expand Option¶

Get Records with the filter Option¶

Get Records with the orderby Option¶

Batch Requests¶

Get Records with the `expand` Option¶

Get Records with the `filter` Option¶

Get Records with the `orderby` Option¶