OAID

A valid access token is required for all processes. This can be obtained via the access credentials; the necessary steps are outlined here. With a valid access token, you can begin the creation of an OAID. If multiple OAIDs are needed, pull codes repeatedly within the token’s validity period, using the same access token.

Requirement: Tenant Contact Data

In order to begin creating OAIDs, your tenant contact data must first be stored at the "Set Tenant Contact" endpoint. To learn more details about the required data, please see the First Steps page.

Create OAID

Pulling a code creates a new OAID in the register and returns it in the response. This 8-digit OAID is linked to the user's account and cannot be changed. From a technical point of view, it is a POST request that instructs the API to add a new OAID to the user’s list. Once an OAID is pulled, this action can no longer be reversed.

$ curl --request POST "https://api.oaid.at/v2/pip/codes/" \
$  --header "Authorization: Bearer &lt;access_token&gt;" \
$  --header "Accept: application/json" \
$  --header "Content-Type: application/json" \
$  --data '{"customer_reference": "loc01212-2442346"}'
---> 100%

{
    "oaid": "AB1C23E4",
    "version": "v8",
    "customer_reference": "loc01212-2442346",
    "status": "active",
    "token": "requested",
    "created_at": "2019-05-29T17:11:14.206+00:00"
}

Confirm OAID

The OAID generated in the previous step has not been confirmed yet. Complete the activation process by confirming it, which provides proof of receipt. Only then will the OAID be activated for further use.

Requirement: Confirmation of OAID

Confirmation is carried out by setting the so-called Milestone Token to "confirmed" on the token attribute of the specified OAID. Confirmation takes place implicitly through calling any of the following endpoints on the OAID:

"Assign/Create Site" endpoint (recommended if storing site data)
"Set OAID Attributes" endpoint

The temporal proximity of the actions, as depicted in the process diagram, is not necessary. CREATE and CONFIRM can be performed in separate sessions and at different times.

Read Specific OAID

Look up a particular OAID via the "Read OAID" endpoint.

Place the OAID as a path parameter in the endpoint call. Below, the example OAID "AB1C23E4" is used.

$ curl --request GET "https://api.oaid.at/v2/pip/codes/AB1C23E4/" \
$  --header "Authorization: Bearer &lt;access_token&gt;" \
$  --header "Accept: application/json"
---> 100%
{
  "oaid": "AB1C23E4",
  "version": "v8",
  "token": "requested",
  "status": "active",
  "customer_reference": "loc01212-2442346",
  "created_at": "2022-03-01T10:35:03.392+01:00",
  "modified_at": "2022-03-01T10:37:01.012+01:00"
}

Read List Of OAIDs

To read a list of OAIDs, use the "List OAIDs" endpoint.

The endpoint allows you to search for the customer_reference, which is useful when connecting the OAID with internal systems. Use this query parameter to verify if an OAID with the given customer_reference already exists. Even though at most one OAID may be returned, the response will always be a list object!

The API limits the number of records returned per request. To read all OAIDs, you have to use multiple requests to get all pages of records.

Pagination

This endpoint uses No Offset Pagination (or Cursor Pagination). To control pagination, two further query parameters are available:

_page_cursor - a unique ID marking the starting point for the next page (defined in the next URL)
_page_size - optional, the number of records to receive per page (default: 500, max: 2000)

Below are step-by-step instructions for retrieving all records, followed by a script in Python to automate pagination.

Request the First Page

In the first page request simply use the base url (plus an optional _page_size query parameter if required).

$ curl --request GET "https://api.oaid.at/v2/pip/codes/?_page_size=500" \
$  --header "Authorization: Bearer &lt;access_token&gt;" \
$  --header "Accept: application/json"
---> 100%

HTTP/1.1 200 OK
date: Thu, 27 Mar 2025 19:25:35 GMT
...
x-page-size: 500
x-page-count: 163
link: &lt;https://api.oaid.at/v2/pip/codes/?_page_size=500&gt;; rel=self, &lt;https://api.oaid.at/v2/pip/codes/?_page_cursor=01953216-aaaa-788e-986e-822e157e5114&_page_size=500&gt;; rel=next

[
  {"oaid": "AB1C23E4", ...
  {"oaid": "AC4723E7", ...
  ...
]

Retrieve the next URL

The next URL for pagination is provided in the API response header in the link field. The method for extracting the next URL varies depending on the programming language used. The Link header is common implementation for pagination.

For instance, in the Python script below, we use the httpx package, which parses the links from the response header and stores them in the response.links object. If another page is available to retrieve, it will include a "next" object with the relevant "url" value for accessing the next page:
```
next_url = response.links.get("next", {}).get("url")
```

Request Next Page

Use the next_url obtained in Step 2 in your next request:

request GET "https://api.oaid.at/v2/pip/codes/?_page_cursor=01953216-aaaa-788e-986e-822e157e5114&_page_size=500"

Repeat Until Completion

Repeat Steps 2 and 3 until no next URL is provided or the last page returns an empty page of data ([]), indicating all records have been retrieved.

Example Script for Python

The following script automates pagination to fetch all pages of data. Please replace the <client_id> and <client_secret> placeholders with your credentials.

# /// Pagination Script
# requires-python = ">=3.11"
# dependencies = [
#     "httpx",
#     "httpx-auth"
# ]
# ///

import httpx
from httpx_auth import OAuth2ClientCredentials

BASE_URL = "https://api.oaid.at/v2/pip/codes/"

oauth2_cred = OAuth2ClientCredentials(
    token_url="<token_url>",            # use provided token_url
    client_id="<client_id>",            # fill in your client id
    client_secret="<client_secret>",    # fill in your client secret
    scope="read"                      
)

results_list = []
next_url = BASE_URL

with httpx.Client(headers={"Content-Type": "application/json"}, auth=oauth2_cred) as client:
    while next_url:
        response = client.get(url=next_url)
        results_list.extend(response.json())
        next_url = response.links.get("next", {}).get("url")

print(f"Total records: {len(results_list)}")

Set OAID Attributes

OAID attributes may be set or updated for a specific OAID through this PATCH method.

The OAID must be provided in the URL as a path parameter. Two attributes may be updated by this endpoint: "token" and "customer_reference".

"token" - token is set to "confirmed" by default
"customer_reference" - unique reference ID for the tenant

This endpoint will confirm a requested OAID. Since confirmation occurs implicitly through any request at this endpoint, {"token": "confirmed"} or {} will confirm the token.

$ curl --request PATCH "https://api.oaid.at/v2/pip/codes/AB1C23E4/"  \
$  --header "Authorization: Bearer &lt;access_token&gt;" \
$  --header "Accept: application/json" \
$  --header "Content-Type: application/json" \
$  --data '{"customer_reference": "loc01212-1234567"}'
---> 100%

{
    "oaid": "AB1C23E4",
    ...
    "customer_reference": "loc01212-1234567",
    ...
    "modified_at": "2021-04-12T13:03:07.566+00:00"
}

Cancel OAID

This DELETE request allows for the cancelation of an OAID.

The OAID to be deleted must be given as a path parameter in the request.

$ curl --request DELETE "https://api.oaid.at/v2/pip/codes/AB1C23E4/"  \
$  --header "Authorization: Bearer &lt;access_token&gt;" \
$  --header "Accept: application/json" 
---> 100%

HTTP/1.1 204 No Content
Content-Type: application/json
Date: Sun, 12 Apr 2021 17:32:16 GMT

&lt;Response body is empty&gt; 

Response code: 204 (No Content); Time: 122ms (122 ms); Content length: 0 bytes (0 B)