API/Endpoint Documentation

Endpoint Documentation

This page describes the available **Verofy API endpoints**, grouped by category.

Categories

• Miscellaneous Endpoints
• Reference Endpoints

---

Miscellaneous Endpoints

Health Check (MISC)

Check whether the API is accessible, or if a particular version of the API is available.

There are two variants of this endpoint:

• **Global Health Check** — verifies the API service as a whole.
• **Version Health Check** — verifies a specific API version.

Returns:

• **200: OK** — the service or version is available.
• **404: Not Found** — the requested service is unavailable.

Ex. 1: Service Health Check

import requests

response = requests.get("https://www.example.com/health-check")
print(response.status_code)   # 200 expected
print(response.text)          # {"api_service": "OK"} expected

Ex. 2: Version Health Check

import requests

response = requests.get("https://www.example.com/v1/health-check")
print(response.status_code)   # 200 expected
print(response.text)          # {"api_v1": "OK"} expected

---

Access Check (MISC)

Check whether authentication has been successful. Accepts either an **access-token** or an **API key**.

Returns:

• **200: OK** — authentication successful
• **401: Unauthorized** — authentication failed

Ex. 3: Failed Access Check

import requests

response = requests.get("https://www.example.com/v1/access-check")
print(response.status_code)   # 401 expected

Ex. 4: Successful Access Check

import requests

headers = {
    "Authorization": "Bearer n20usc92gb2_not_a_real_access_token_1v51r8jmrtfc"
}
response = requests.get(
    "https://www.example.com/v1/references/MapSegmentType",
    headers=headers
)

print(response.status_code)   # 200 expected
print(response.text)          # {"api_v1_access": "OK"} expected

---

Login (MISC)

Provide **user credentials** to retrieve a new **refresh-token**. Intended for user-facing clients.

⚠️ **Never store raw user credentials in a client app** — always prompt the user on each login.

Returns:

• A **refresh-token** if credentials are valid
• **401: Unauthorized** otherwise

Do not send credentials without HTTPS!

Ex. 5: Get Refresh-Token with Login

import requests
import getpass

# Don't hard-code or store user credentials! Always ask the user.
ident = {
    "email": getpass.getuser(),
    "password": getpass.getpass()
}

response = requests.post("https://www.example.com/v1/login", json=ident)

print(response.status_code)   # 200 expected
print(response.text)
# {
#   "username": "example@example.com",
#   "first-name": "John",
#   "last-name": "Doe",
#   "refresh-token": "tq290v0190n1oe290_not_a_real_refresh_token_2901bg02g81"
# } expected

---

Refresh Token (MISC)

Exchange a **refresh-token** for a **new refresh-token** and a **fresh access-token**.

Intended for user-facing clients. Clients should store both tokens for later use.

Notes:

• Refresh-tokens can be used only **once**
• Once used, they are **invalidated**
• Always store the **new** refresh-token from the response

Returns:

• **200: OK** — new tokens issued
• **401: Unauthorized** — invalid or expired refresh-token

Ex. 6: Get Access-Token with Refresh-Token

import requests

# Use the "login" endpoint first to obtain a refresh-token
headers = {
    "Authorization": "Bearer tq290v0190n1oe290_not_a_real_refresh_token_2901bg02g81"
}

response = requests.get("https://www.example.com/v1/refresh-access", headers=headers)
print(response.status_code)   # 200 expected
print(response.text)
# {
#   "username": "example@example.com",
#   "access-token": "n20usc92gb2_not_a_real_access_token_1v51r8jmrtfc",
#   "refresh-token": "8b1w1sx5gfwgwg_new_refresh_token_qn2n7ed2f22bn5ed"
# } expected

---

Reference Endpoints

References (VIEW)

Retrieve the specified **complete collection of reference models** as a single resource.

Optional parameter:

• `hash` — if supplied, the server compares it to its own hash for the collection.

 * If hashes differ → returns the collection.
 * If hashes match → returns an empty response.

• If the `hash` parameter is omitted → the full collection is returned.

If a ref-type is invalid or removed on the server:

• **410: Gone** — client should remove local copies and stop requesting that ref-type.

Returns:

• The collection as a resource (if available)
• **410: Gone** if the ref-type no longer exists
• **401: Unauthorized** if access is denied

---

Next: → API/Endpoints: Models