> For the complete documentation index, see [llms.txt](https://docs.hos.accessacloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hos.accessacloud.com/atreemo-api/get-started/introduction.md).

# Introduction

Scope, terminology and first synthetic Atreemo API request

{% hint style="warning" %}
**Beta, runtime validation pending.** This guide describes the existing Atreemo API and Phase 1 access through Access API Management (APIM). Endpoint availability, routing behaviour and compatibility with the target instance require staged release validation. Run examples only in Staging with approved synthetic fixtures.
{% endhint %}

## What this documentation covers

The Atreemo API exposes customer, preference, loyalty, transaction, reservation, event, survey, messaging and extraction operations. Use the operation-specific contract: identifiers, permission checks, response envelopes and side effects are not uniform.

The public Postman collection **1.34.0.0** defines the scope: **254 request entries**, of which **219 included entries consolidate into 217 operations on 212 paths**. The 35 exclusions remain excluded, including deprecated operations and the separately documented `/token` endpoint. This is the direct legacy API reference, not the transformed `loyalty-v1` wrapper.

## Terminology

| Term                     | Meaning                                                                                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Atreemo instance         | A customer- or environment-specific Atreemo deployment with its own host, users, configuration, brands and data. The instance URL and credentials are supplied through the approved Atreemo support and onboarding process.           |
| `UserID`                 | The internal Atreemo user resolved from the authenticated caller. It is used by permission and extraction paths; it is not a customer identifier.                                                                                     |
| `CtcID`                  | An Atreemo contact/customer identifier used by customer and loyalty operations. Preserve the native spelling and do not substitute `UserID`. Contacts can be merged, so cached identity handling needs an agreed policy.              |
| Brand                    | An instance-defined business partition/hierarchy. A valid token does not imply access to every brand, and `BrandID` requirements differ by operation.                                                                                 |
| Native response envelope | The operation's original response shape. Atreemo uses several conventions, including `ResponseStatus`/`Errors`, `Response`/`Error`, lowercase `response`/`errors`, payload-only bodies and bodyless successes. Casing is significant. |

## Evidence labels

| Label              | Meaning                                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Published          | Described by the public guide or collection; not automatically checked against implementation.                                                            |
| Source-verified    | Directly inspected declarations or execution paths at source commit `ea9cb106e13aa4b9b92c01d090118742b44dd470`. Specific citations accompany corrections. |
| Synthetic example  | Illustrates a schema or cited branch with non-production values; it is not an approved fixture or captured response.                                      |
| Runtime-unverified | Not tested against a running instance. All 217 operations retain this status.                                                                             |

Source inclusion is not proof of the assembled or deployed code. The contract derives from public API version 1.34.0.0 / Release1.34. Read-only environment evidence says the current non-production Atreemo environment runs Release1.35; runtime compatibility with that environment remains to be validated.

## Hosts and encryption

Use HTTPS with TLS 1.2 or later **recommended**. This is client security guidance, not a verified statement about the deployed TLS configuration.

| Purpose                   | Address                                                | Status                                                                                                                                         |
| ------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Native token acquisition  | `https://<atreemo-instance>/token`                     | Direct from the caller's Atreemo instance, not APIM. The instance URL is supplied through the approved Atreemo support and onboarding process. |
| Staging resource calls    | `https://api-staging.hos.accessacloud.com/atreemo-api` | Use for integration validation with approved synthetic fixtures. Runtime behaviour remains subject to release validation.                      |
| Production resource calls | `https://api.hos.accessacloud.com/atreemo-api`         | Use after Staging validation and separately approved release steps. Availability and runtime behaviour remain subject to release validation.   |

## Obtain a native access token

Send credentials directly to the approved Atreemo instance as a form-encoded OAuth 2.0 resource-owner password grant. The instance URL and credentials are supplied through the approved Atreemo support and onboarding process.

```shell
curl -X POST "https://<atreemo-instance>/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=<synthetic-username>" \
  --data-urlencode "password=<synthetic-password>"
```

Read `access_token` and `expires_in` from the actual response. Do not assume one universal lifetime. See [Authentication](file:///8924120/authentication/README.md).

## Make a resource request

The following synthetic request uses the Staging resource base. It supplies both `CtcID` and `BrandID` because the published optionality of `BrandID` conflicts with the source action signature and requires runtime validation.

```shell
curl "https://api-staging.hos.accessacloud.com/atreemo-api/api/LoyaltyPoint/Get?CtcID=1&BrandID=1" \
  -H "Authorization: Bearer <synthetic-access-token>" \
  -H "Accept: application/json"
```

A synthetic successful native response is:

```json
{
  "ResponseData": {
    "LoyaltyPointsBalance": 1.5,
    "CurrentTiersName": "Synthetic tier"
  },
  "ResponseStatus": true,
  "Errors": []
}
```

Check both the HTTP status and operation-specific business-success/error members. A points response with `ResponseStatus: false` is not a zero balance.

## Important integration differences

* Preserve native field and parameter names, including casing and spelling.
* Method permission and brand access are separate and operation-specific; no one OAuth scope or role is assigned per endpoint.
* Do not assume GET means read-only. `GET /Workspace/InviteUser` sends an invitation, social approval can update/send, and extraction GETs can advance state.
* Four operations truthfully have bodyless source successes; do not fabricate response objects.
* Selection `DataTable` rows remain open because columns depend on export format and database logic.
* Do not apply generic retries until idempotency, continuation and duplicate handling are agreed for the operation.

Continue with [Errors](broken://pages/39a2078b7d2d75ec17a08218d306d0d51ed89775), [Dates and times](broken://pages/ab870f6e721dee384ba5cc1d2281653e36512eb7), [Paging](broken://pages/fcb8b4932103ca3d407e794073b04fe81184636c), [Request format](file:///8924120/request-format.md), [Response format](file:///8924120/response-format.md) and [Testing and support](file:///8924120/testing-and-support.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hos.accessacloud.com/atreemo-api/get-started/introduction.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.