Getting Started Guide

Latest Update Time: 2025-11-17 15:49:00

Welcome to the QIMA Developer Portal documentation!

Introduction

This guide will help you get started with the QIMA Public API. Follow the steps below to begin integrating with our services.

When you're ready to explore endpoints, browse the full API list in the API Reference.

Recommended: use QIMA API MCP. If you work with an AI assistant such as Cursor or Claude Desktop, QIMA API MCP lets you explore endpoints, understand fields, generate request scripts, and even authenticate and call the APIs directly — all from a chat prompt. It's the fastest way to get from "reading the docs" to a working request.

Prerequisites

Before you begin, make sure you have:

An active customer account at qima.com
An Ai-Api-Access-Token from QIMA sales or IT support team
Basic knowledge of REST APIs

Authentication

Step 1: Get Your Token

To authenticate with the QIMA Public API, you need to:

Send your password in MD5 format
Set userType to "client"
Include the Ai-Api-Access-Token in the request header

Step 2: Use the Token

Always include your token in the authorization header for all API requests.

Code Examples

Here's a simple example using cURL:

curl -X POST https://ppapi.qima.com/auth/v2/token \
  -H "Ai-Api-Access-Token: {your api access token}" \
  -H "Referer: https://preprodmy.qima.com/" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "your-username",
    "password": "md5-hashed-password",
    "userType": "client"
  }'

Note: the request body field is account (your login/username), not username.

Request Body Fields

Field	Notes
`account`	Your QIMA login/username.
`password`	Your own account password, MD5-hashed. The hashed value is a 32-character lowercase hexadecimal string (e.g. `87dbe61e438efed74296fea38049f6fa`). Never send your plain-text password.
`userType`	`client` or `employee`.

Successful Response

HTTP 200 OK returns your access token plus your full customer/employee profile. The profile object is large (company details, booking preferences, feature flags, pricing) — trimmed to the key fields here:

{
    "message": null,
    "content": {
        "token": {
            "id": "C0EAB3901FBF4AEF8580195C73B585FA",
            "userId": "4C6E94072DFC4918B60752F701DE544A",
            "userType": "client",
            "token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldUIn0..<truncated-jwt>",
            "validBefore": "1783051410",
            "refreshKey": "736b64e675fc477bb804c324271649e0",
            "loginType": "Login"
        },
        "user": {
            "id": "4C6E94072DFC4918B60752F701DE544A",
            "login": "louispp001",
            "firstName": "Louis",
            "lastName": "Test",
            "email": "louis.yi@qima.com",
            "status": "ACTIVE",
            "businessUnit": "CIS",
            "company": {
                "id": "23EC09AB0F3C46BBA4F79718DCED16D0",
                "name": "PP-Testing-77729",
                "country": "China",
                "companyType": "client"
            }
        }
    }
}

The full content.user object also includes contacts, preferences (booking/report defaults), dashboard, payment, rate (pricing per service/continent), and features.enabledFeatures (a large map of account-level feature flags) — omitted above for brevity. See the interactive API reference for the complete field list.

Common Errors

Status	Meaning	Recommended Action
`401 Unauthorized`	The username and password don't match.	Verify the `account` and MD5-hashed `password`.
`403 Forbidden`	The `Ai-Api-Access-Token` header is missing, invalid, or the user type is wrong.	Confirm the token was issued for the correct environment and user type.

Next Steps

Set up QIMA API MCP to explore, script, and call the APIs from your AI assistant
Browse the full API list to view all available endpoints
Review the Module Overview to understand available API modules

Support

If you need help, please contact QIMA support or your account manager.

Documents