Introduction to API V2

Welcome to API V2, our REST-based API designed for scalability, consistency, and long-term evolution. API V2 replaces the legacy GraphQL-based V1 and is the future-ready platform for all integrations. 

Key principles: 

• RESTful, resource-oriented design
• Predictable request/response structure
• Built-in pagination, filtering, and sorting
• Designed for performance and maintainability 

⚠️ All new features and enhancements will be released exclusively on V2.

Access & Authentication

To start using API V2, you need: 

• An active expereoOne user account with ‘Developer Portal (API)’ permission
• API client credentials
• Valid authentication token

Get an expereoOne user account 

Refer to this page: https://knowledge.expereo.com/en_US/manage-account 

Generate API Client Credentials

• Authentication Flow Type: OAuth 2.0 (Client Credentials Flow)
• Credential Provisioning Process:
  • Navigate to the API page in expereoOne
  • Create a new set of API keys
  • Retrieve:
    • CLIENT_ID (public key)
    • CLIENT_SECRET (private key)
  • Store credentials securely (do not expose client secret) 

Authentication Setup

API V2 uses Bearer Token Authentication based on OAuth 2.0.

How to obtain an Access Token?

To authenticate, you must request a token from the authentication server using your API credentials. 

Required Parameters 

• CLIENT_ID
• CLIENT_SECRET
• Scope

Example Request (Token Retrieval)

Example Request with Authentication 

curl -X GET "<BASE_URL>/v2/accounts" \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/json"

⚠️ Important Notes on Scopes

• Scopes define access boundaries for your application
• Scopes cannot be modified after API keys are created
• To change scopes: You must generate a new set of API credentials 

Core Resources

The API is organized around the following domains. These resources follow consistent REST patterns for listing and retrieving data.

Relationships & Navigations

Common patterns:

• Parent - Child via path parameters
• IDs are required for navigation 

You can traverse related data via nested endpoints: 

• Account → Sites: /v2/accounts/{accountId}/sites
• Account → Services: /v2/accounts/{accountId}/services
• Sites → Services: /v2/sites/{siteId}/services
• Case → Messages: /v2/cases/{caseId}/case-messages
• Invoices → Invoice Line Details: /v2/invoices/{invoiceId}/invoice-line-details 

Key Operations: Case Management

• Create Case: POST /v2/cases
• Update Case: PATCH /v2/cases/{caseId}
• Add Message: POST /v2/cases/{caseId}/case-messages

OpenAPI Specifications

You can obtain the OpenAPI specification straight from the portal. Go to the API tab and select the ‘OpenAPI Specification’ button to start the download.

HTTP Methods

• GET: Retrieve data
• POST: Create new resource
• PATCH: Update resource
• DELETE: Remove resource

First API Call (Step-by-Step)

This example retrieves a list of accounts.

Step 1 — Prepare Request

curl -X GET "<BASE_URL>/v2/accounts?page%5Boffset%5D=0&page%5Blimit%5D=25&sort=AccountId%2C-Name" \
-H "Authorization: Bearer <access_token>" \
-H "Accept: application/json"

Step 2 — Sample Response

{
  "data": [
    {
      "accountId": "string",
      "name": "string ",
      "legalName": “string ”
    }
  ],
  "metadata": {
    "offset": 0,
    "limit": 25,
    "hasMore": false,
    "total": null,
    "sort": ["AccountId", "-Name"]
  },
  "links": {
    "self": "...",
    "next": null,
    "previous": null
  }
}

Step 3 — Response Example

{
  "data": [
    {
      "accountId": "ACC-98000001",
      "name": " ACME Corporation HQ",
      "legalName": “ ACME Corporation HQ”
    }
  ],
  "metadata": {
    "offset": 0,
    "limit": 25,
    "hasMore": false,
    "total": 1,
    "sort": [
      "AccountId",
      “-Name”
    ]
  },
  "links": {
    "self": "<BASE_URL>/v2/accounts?page%5Boffset%5D=0&page%5Blimit%5D=25&sort=AccountId%2C-Name",
    "next": null,
    "previous": null
  }
}

Step 4 — Understand the Response

• data: Actual resources
• metadata: Pagination and sorting info
• links: Navigation (next/previous pages)

Step 5 — Supports query parameters

• Pagination: page[offset], page[limit]
• Sorting: sort=AccountId,-Name
• Filtering: filter[Name]=Example

Rate Limits

To ensure performance, stability, and fair usage, API V2 enforces rate limits per authenticated client/user.

Rate Limit Overview

What Happens If You Exceed Limits?

If rate limits are exceeded, the API will return: 429 Too Many Requests. This indicates a temporary limit breach.

Important Notes

• Limits apply per authenticated client/user
• Limits are part of a fair-use policy
• Rate limits may be adjusted at any time to maintain platform stability

Status Codes

Best Practices

Use Pagination for Large Datasets

1. Default limit: 25
2. Maximum limit: 200
3. Use: ?page[offset]=0&page[limit]=25

Use Filtering to Reduce Payload Size

1. Example: /v2/accounts?filter[Name]=ACME Corporation

Use Sorting for Predictable Results

1. Example: /v2/accounts?sort=AccountId,-Name

Handle Pagination via Links

1. Use the links.next field instead of manually constructing URLs.

Prepare for Future Evolution

1. Avoid hardcoding assumptions about response structure
2. Always use documented fields
3. Plan for new fields to be added