Link ExhibitDay Events to Your CRM or ERP Records
Link each record in your CRM or ERP (for example Salesforce, HubSpot or NetSuite) to the matching ExhibitDay Event, even after names change.
Example use case
You connect ExhibitDay to a CRM or ERP and want the same records to stay linked even after their names change.
What you'll end up with
A confirmed pair of IDs to save in your integration and a safe way to find an existing match.
Before you start
Have your workspace API key, your system's Event ID and a place to store the pair.
This guide assumes your system's ID for each Event is already stored in integration_metadata_field_1, one of five API-only text fields on each Event. If another integration already uses field 1, choose a free field (1 to 5) and use it consistently.
Good to know
Match on IDs. Two Events can have the same name, and names can change.
At a glance
Time to try
About 5 minutes
Effect on your data
Read-only
Endpoints
2
The example reads Events and prints the confirmed pair.
How it works
- Your system keeps its own ID for each show. The example assumes that ID is already stored in the Event's integration_metadata_field_1.
- If you already saved the ExhibitDay Event ID, the program checks it directly. Otherwise, it searches by your system's ID and requires exactly one match.
- After it confirms both IDs, save the pair in your system. Use the ExhibitDay Event ID for later requests.
The examples show how to find and confirm a match. If you already saved the ExhibitDay Event ID, skip Step 1 and confirm it in Step 2.
Step 1: Search by your system's ID
If you do not have a saved Event ID, search Events by integration_metadata_field_1, the field where your system's ID is stored, and read every page.
curl -X GET "https://api.exhibitday.com/v1/events?filter_by_integration_metadata_field_1=crm%3Aevent%3Aspring-expo-2030&%24limit=100&%24offset=0" -H "Authorization: Bearer YOUR_API_KEY"
Example response (shortened)
{
"has_more": false,
"list_data": [
{
"id": 12345,
"integration_metadata_field_1": "crm:event:spring-expo-2030"
}
]
}
Use list_data[].id to identify a candidate. When has_more is true, continue to the next page.
Check: Look for one distinct Event with the full external ID. If none match, create the Event or link an existing one with Create or Update Events from Your CRM. If several match, stop and review.
Step 2: Confirm the match and save the pair
Read the chosen Event by ID to confirm the link before saving it.
curl -X GET "https://api.exhibitday.com/v1/events/info?id=12345" -H "Authorization: Bearer YOUR_API_KEY"
Example response (shortened)
{
"id": 12345,
"integration_metadata_field_1": "crm:event:spring-expo-2030"
}
Save this id in your integration after checking the stored key.
Check: Confirm that integration_metadata_field_1 equals your external ID. Save the Event id with your external ID.
Try it
Before running the example
| Variable | What to put in it | Required? |
|---|---|---|
EXHIBITDAY_API_KEY | Your workspace API key. | Yes |
EXHIBITDAY_EXTERNAL_EVENT_KEY | Your system's Event ID, exactly as stored in ExhibitDay, up to 3,000 characters. | Yes |
EXHIBITDAY_PAGE_SIZE | A positive number of Events per page. Defaults to 100. | No |
EXHIBITDAY_EVENT_ID | A previously saved ExhibitDay Event ID. When set, the example goes straight to confirmation. | No |
Bash
export EXHIBITDAY_API_KEY='YOUR_API_KEY'
export EXHIBITDAY_EXTERNAL_EVENT_KEY='crm:event:spring-expo-2030'
PowerShell
$env:EXHIBITDAY_API_KEY = 'YOUR_API_KEY'
$env:EXHIBITDAY_EXTERNAL_EVENT_KEY = 'crm:event:spring-expo-2030'
Then copy the complete example program below in your language and run it.
Complete example program
#!/usr/bin/env bash
# Requires Bash, curl and Python3. No API key is written into the program.
python3 - <<'EXHIBITDAY_PY'
# Python 3; standard library only. Set EXHIBITDAY_API_KEY before running.
import http.client
import json
import os
import re
import time
import urllib.error
import urllib.parse
import urllib.request
BASE = "https://api.exhibitday.com/v1"
SPEC = json.loads("{\"preserveNumbers\":true,\"requests\":{\"find_match\":{\"method\":\"GET\",\"path\":\"/events\"},\"confirm_match\":{\"method\":\"GET\",\"path\":\"/events/info\"}}}")
API_KEY = os.environ["EXHIBITDAY_API_KEY"]
if any(ord(char) < 32 or ord(char) > 126 for char in API_KEY):
raise RuntimeError("Use the API key as one ASCII header value without control characters")
if not API_KEY.strip():
raise RuntimeError("Set EXHIBITDAY_API_KEY")
def decode_json(text):
if SPEC["preserveNumbers"]:
# Quote JSON NUMBER tokens, never text inside a JSON string, to keep CSV decimals exact.
text = re.sub(r'"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?',
lambda m: m[0] if m[0].startswith('"') else json.dumps(m[0]), text)
return json.loads(text)
from pathlib import Path
# This terminal version uses curl for HTTP and Python's standard library for JSON/CSV.
import subprocess
import tempfile
def transport(method, url, headers, data):
with tempfile.TemporaryDirectory(prefix="exhibitday-guide-") as directory:
folder = Path(directory)
# curl may leave no output file for a valid bodyless304 response.
(folder / "body").write_bytes(b"")
command = ["curl", "--disable", "--silent", "--show-error", "--request", method, "--url", url,
"--max-time", "30", "--dump-header", str(folder / "headers"),
"--output", str(folder / "body"), "--write-out", "%{http_code}"]
for name, value in headers.items():
command += ["--header", name + ": " + value]
if data is not None:
(folder / "request").write_bytes(data)
command += ["--data-binary", "@" + str(folder / "request")]
result = subprocess.run(command, capture_output=True, text=True)
if result.returncode:
raise urllib.error.URLError(result.stderr.strip())
response_headers = {}
blocks = (folder / "headers").read_text(encoding="iso-8859-1").replace("\r\n", "\n").strip().split("\n\n")
for line in blocks[-1].splitlines()[1:]:
name, separator, value = line.partition(":")
if separator:
response_headers[name] = value.strip()
return int(result.stdout), (folder / "body").read_bytes(), response_headers
class ApiError(RuntimeError):
"""An API error response. Branch on error_code (and status), never on the message text.
uncertain is True when a PATCH or DELETE got no response or a server error: it may or may not have been applied."""
def __init__(self, status, body, uncertain=False):
self.status = status
self.uncertain = uncertain
self.error_code = body.get("error_code") if isinstance(body, dict) else None
super().__init__(f"{body.get('error_code')} {body.get('error_params')}: {body.get('errors')} (request {body.get('request_id')})"
if isinstance(body, dict) else "HTTP " + str(status) if status else "No response")
def call(name, params=None, body=None, key=None):
route = SPEC["requests"][name]
headers = {"Authorization": "Bearer " + API_KEY, "Accept": "application/json"}
if route["method"] == "POST":
if not key: raise RuntimeError("Persist a logical create key before sending POST")
headers["Idempotency-Key"] = key
data = None if body is None else json.dumps(body).encode("utf-8")
if data is not None:
headers["Content-Type"] = "application/json"
query = urllib.parse.urlencode(params or {})
url = BASE + route["path"] + ("?" + query if query else "")
# Only GET has automatic retries in this workflow. A PATCH or DELETE that got no response or a
# server error is never resent blindly: it may already have been applied, so the caller reads the record first.
resend = route["method"] == "GET"
for attempt in range(5):
try:
status, raw, response_headers = transport(route["method"], url, headers, data)
except (urllib.error.URLError, TimeoutError, ConnectionError, http.client.HTTPException):
if not resend:
raise ApiError(0, None, uncertain=True)
if attempt == 4:
raise
time.sleep(2 ** attempt)
continue
response_headers = {k.lower(): v for k, v in response_headers.items()}
result = None
if status != 304 and raw:
try:
result = decode_json(raw.decode("utf-8"))
except (ValueError, UnicodeError):
if status < 400:
raise RuntimeError("Expected a JSON success response")
if status >= 500 and not resend:
raise ApiError(status, result, uncertain=True)
retry = resend and (status == 429 or status >= 500)
if retry:
if attempt == 4:
raise RuntimeError("Retry limit reached; check the request outcome before starting a new create")
delay = response_headers.get("retry-after", str(2 ** attempt))
time.sleep(max(0, float(delay)))
continue
if status >= 400:
raise ApiError(status, result)
return {"status": status, "body": result, "headers": response_headers, "raw": raw}
raise RuntimeError("Retry limit reached")
def add_offset(offset, received):
result = int(offset) + received
if received <= 0 or result > 2147483647: raise RuntimeError("Cannot advance this int32 offset; reconcile the query")
return str(result)
def items(value):
if not isinstance(value, list): raise RuntimeError("Expected a JSON array")
return value
def count(value):
return len(items(value))
def either(left, right):
if not isinstance(left, bool) or not isinstance(right, bool): raise RuntimeError("Expected Boolean criteria")
return left or right
def equal(left, right):
return type(left) is type(right) and left == right
def field(value, name):
if not isinstance(value, dict) or name not in value: raise RuntimeError("Missing response field: " + name)
return value[name]
def is_empty(value):
return count(value) == 0
def is_present(value):
return value is not None and value != ""
def not_value(value):
if not isinstance(value, bool): raise RuntimeError("Expected a Boolean")
return not value
def optional(name, fallback):
value = os.environ.get(name)
return fallback if value is None or value == "" else value
def page_size(value):
if not re.fullmatch(r"[1-9][0-9]*", value) or int(value) > 2147483647: raise RuntimeError("Page size must be a positive int32")
return value
def positive_id(value):
if not re.fullmatch(r"[1-9][0-9]*", value) or int(value) > 9223372036854775807: raise RuntimeError("Use a positive record ID")
return value
def print_value(value):
print(value if isinstance(value, str) else json.dumps(value, ensure_ascii=False))
def require_condition(value, message):
if value is not True: raise RuntimeError(message)
def required(name):
value = os.environ.get(name)
if value is None or not value.strip(): raise RuntimeError("Set " + name)
return value
def text(value):
if value is None: return ""
if isinstance(value, str): return value
if isinstance(value, bool): return "true" if value else "false"
if isinstance(value, int): return str(value)
raise RuntimeError("Expected a scalar response value")
def main():
external_event_key = required("EXHIBITDAY_EXTERNAL_EVENT_KEY")
matched_event_id = optional("EXHIBITDAY_EVENT_ID", "")
if is_present(matched_event_id):
matched_event_id = positive_id(matched_event_id)
else:
matching_page_size = page_size(optional("EXHIBITDAY_PAGE_SIZE", "100"))
matching_offset = "0"
matching_query = {"filter_by_integration_metadata_field_1": external_event_key, "$limit": matching_page_size}
while True:
matching_query["$offset"] = matching_offset
matching_response = call("find_match", matching_query, None, None)
matching_page = matching_response["body"]
matching_rows = items(field(matching_page, "list_data"))
require_condition(equal(text(field(matching_page, "records_found")), text(count(matching_rows))), "records_found does not match this page's rows.")
require_condition(is_present(text(field(matching_page, "total_records"))), "The collection wrapper needs total_records.")
require_condition(either(equal(field(matching_page, "has_more"), True), equal(field(matching_page, "has_more"), False)), "Expected a Boolean has_more value.")
for matching_event in items(matching_rows):
if equal(text(field(matching_event, "integration_metadata_field_1")), external_event_key):
candidate_event_id = positive_id(text(field(matching_event, "id")))
if is_present(matched_event_id):
require_condition(equal(matched_event_id, candidate_event_id), "Multiple Events have this exact external key; resolve the ambiguity before linking.")
matched_event_id = candidate_event_id
if equal(field(matching_page, "has_more"), False):
break
require_condition(not_value(is_empty(matching_rows)), "An empty page has has_more=true; stop and reconcile the search.")
matching_offset = add_offset(matching_offset, count(matching_rows))
require_condition(is_present(matched_event_id), "No exact match was found. Decide explicitly whether to create or link a record.")
confirmation_query = {"id": matched_event_id}
confirmed_response = call("confirm_match", confirmation_query, None, None)
confirmed_event = confirmed_response["body"]
require_condition(equal(text(field(confirmed_event, "id")), matched_event_id), "The confirmed Event ID differs from the selected Event.")
require_condition(equal(text(field(confirmed_event, "integration_metadata_field_1")), external_event_key), "The Event's current metadata differs from the intended external key. Stop for review.")
print_value({"external_event_key": external_event_key, "event_id": matched_event_id})
if __name__ == "__main__":
main()
EXHIBITDAY_PY
// Server-side Node.js with fetch; built-in modules only. Set EXHIBITDAY_API_KEY.
const BASE = "https://api.exhibitday.com/v1";
const SPEC = JSON.parse("{\"preserveNumbers\":true,\"requests\":{\"find_match\":{\"method\":\"GET\",\"path\":\"/events\"},\"confirm_match\":{\"method\":\"GET\",\"path\":\"/events/info\"}}}");
const API_KEY = process.env.EXHIBITDAY_API_KEY;
if (!API_KEY || !API_KEY.trim()) throw new Error("Set EXHIBITDAY_API_KEY");
if (/[^\x20-\x7e]/.test(API_KEY)) throw new Error("Use the API key as one ASCII header value without control characters");
const sleep = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds));
function decodeJson(text) {
if (SPEC.preserveNumbers) {
// Keep raw JSON number tokens exact for CSV; quoted JSON strings remain unchanged.
text = text.replace(/"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g,
token => token.startsWith('"') ? token : JSON.stringify(token));
}
return JSON.parse(text);
}
// An API error response. Branch on errorCode (and status), never on the message text.
// uncertain is true when a PATCH or DELETE got no response or a server error: it may or may not have been applied.
class ApiError extends Error {
constructor(status, result, uncertain = false) {
super(result ? JSON.stringify({ error_code: result.error_code, errors: result.errors,
error_params: result.error_params, request_id: result.request_id }) : status ? "HTTP " + status : "No response");
this.status = status;
this.errorCode = result ? result.error_code : undefined;
this.uncertain = uncertain;
}
}
async function call(name, params = {}, body = null, key = null) {
const route = SPEC.requests[name];
const headers = { Authorization: "Bearer " + API_KEY, Accept: "application/json" };
if (route.method === "POST") {
if (!key) throw new Error("Persist a logical create key before sending POST");
headers["Idempotency-Key"] = key;
}
const data = body === null ? undefined : JSON.stringify(body);
if (data !== undefined) headers["Content-Type"] = "application/json";
const query = new URLSearchParams(params).toString();
const url = BASE + route.path + (query ? "?" + query : "");
// Only GET has automatic retries in this workflow. A PATCH or DELETE that got no response or a
// server error is never resent blindly: it may already have been applied, so the caller reads the record first.
const resend = route.method === "GET";
for (let attempt = 0; attempt < 5; attempt++) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 30000);
let response, raw;
try {
response = await fetch(url, { method: route.method, headers, body: data, signal: controller.signal, redirect: "error" });
raw = await response.text();
} catch (error) {
if (!resend) throw new ApiError(0, null, true);
if (attempt === 4) throw error;
await sleep(1000 * 2 ** attempt);
continue;
} finally { clearTimeout(timer); }
const resultHeaders = {};
response.headers.forEach((value, name) => { resultHeaders[name.toLowerCase()] = value; });
let result = null;
if (response.status !== 304 && raw) {
try { result = decodeJson(raw); }
catch (error) { if (response.status < 400) throw new Error("Expected a JSON success response"); }
}
if (response.status >= 500 && !resend) throw new ApiError(response.status, result, true);
const retry = resend && (response.status === 429 || response.status >= 500);
if (retry) {
if (attempt === 4) throw new Error("Retry limit reached; check the outcome before starting a new create");
const requested = Number(resultHeaders["retry-after"]);
await sleep(1000 * (Number.isFinite(requested) && requested >= 0 ? requested : 2 ** attempt));
continue;
}
if (response.status >= 400) throw new ApiError(response.status, result);
return { status: response.status, body: result, headers: resultHeaders, raw };
}
throw new Error("Retry limit reached");
}
function add_offset(offset, received) { const result = BigInt(offset) + received; if (received <= 0n || result > 2147483647n) throw new Error("Cannot advance this int32 offset; reconcile the query"); return result.toString(); }
function items(value) { if (!Array.isArray(value)) throw new Error("Expected a JSON array"); return value; }
function count(value) { return BigInt(items(value).length); }
function either(left, right) { if (typeof left !== "boolean" || typeof right !== "boolean") throw new Error("Expected Boolean criteria"); return left || right; }
function equal(left, right) { return typeof left === typeof right && left === right; }
function field(value, name) { if (!value || Array.isArray(value) || typeof value !== "object" || !Object.hasOwn(value, name)) throw new Error("Missing response field: " + name); return value[name]; }
function is_empty(value) { return count(value) === 0n; }
function is_present(value) { return value !== null && value !== undefined && value !== ""; }
function not_value(value) { if (typeof value !== "boolean") throw new Error("Expected a Boolean"); return !value; }
function optional(name, fallback) { const value = process.env[name]; return value === undefined || value === "" ? fallback : value; }
function page_size(value) { if (!/^[1-9][0-9]*$/.test(value) || BigInt(value) > 2147483647n) throw new Error("Page size must be a positive int32"); return value; }
function positive_id(value) { if (!/^[1-9][0-9]*$/.test(value) || BigInt(value) > 9223372036854775807n) throw new Error("Use a positive record ID"); return value; }
function print_value(value) { console.log(typeof value === "string" ? value : JSON.stringify(value)); }
function require_condition(value, message) { if (value !== true) throw new Error(message); }
function required(name) { const value = process.env[name]; if (value === undefined || !value.trim()) throw new Error("Set " + name); return value; }
function text(value) { if (value === null || value === undefined) return ""; if (["string", "boolean", "bigint"].includes(typeof value)) return String(value); throw new Error("Expected a scalar response value"); }
async function main() {
let external_event_key = required("EXHIBITDAY_EXTERNAL_EVENT_KEY");
let matched_event_id = optional("EXHIBITDAY_EVENT_ID", "");
if (is_present(matched_event_id)) {
matched_event_id = positive_id(matched_event_id);
} else {
let matching_page_size = page_size(optional("EXHIBITDAY_PAGE_SIZE", "100"));
let matching_offset = "0";
let matching_query = {"filter_by_integration_metadata_field_1": external_event_key, "$limit": matching_page_size};
while (true) {
matching_query["$offset"] = matching_offset;
let matching_response = await call("find_match", matching_query, null, null);
let matching_page = matching_response.body;
let matching_rows = items(field(matching_page, "list_data"));
require_condition(equal(text(field(matching_page, "records_found")), text(count(matching_rows))), "records_found does not match this page's rows.");
require_condition(is_present(text(field(matching_page, "total_records"))), "The collection wrapper needs total_records.");
require_condition(either(equal(field(matching_page, "has_more"), true), equal(field(matching_page, "has_more"), false)), "Expected a Boolean has_more value.");
for (const matching_event of items(matching_rows)) {
if (equal(text(field(matching_event, "integration_metadata_field_1")), external_event_key)) {
let candidate_event_id = positive_id(text(field(matching_event, "id")));
if (is_present(matched_event_id)) {
require_condition(equal(matched_event_id, candidate_event_id), "Multiple Events have this exact external key; resolve the ambiguity before linking.");
}
matched_event_id = candidate_event_id;
}
}
if (equal(field(matching_page, "has_more"), false)) {
break;
}
require_condition(not_value(is_empty(matching_rows)), "An empty page has has_more=true; stop and reconcile the search.");
matching_offset = add_offset(matching_offset, count(matching_rows));
}
require_condition(is_present(matched_event_id), "No exact match was found. Decide explicitly whether to create or link a record.");
}
let confirmation_query = {"id": matched_event_id};
let confirmed_response = await call("confirm_match", confirmation_query, null, null);
let confirmed_event = confirmed_response.body;
require_condition(equal(text(field(confirmed_event, "id")), matched_event_id), "The confirmed Event ID differs from the selected Event.");
require_condition(equal(text(field(confirmed_event, "integration_metadata_field_1")), external_event_key), "The Event's current metadata differs from the intended external key. Stop for review.");
print_value({"external_event_key": external_event_key, "event_id": matched_event_id});
}
if (require.main === module) main().catch(error => { console.error(error.message); process.exitCode = 1; });
module.exports = { main };
# Python 3; standard library only. Set EXHIBITDAY_API_KEY before running.
import http.client
import json
import os
import re
import time
import urllib.error
import urllib.parse
import urllib.request
BASE = "https://api.exhibitday.com/v1"
SPEC = json.loads("{\"preserveNumbers\":true,\"requests\":{\"find_match\":{\"method\":\"GET\",\"path\":\"/events\"},\"confirm_match\":{\"method\":\"GET\",\"path\":\"/events/info\"}}}")
API_KEY = os.environ["EXHIBITDAY_API_KEY"]
if any(ord(char) < 32 or ord(char) > 126 for char in API_KEY):
raise RuntimeError("Use the API key as one ASCII header value without control characters")
if not API_KEY.strip():
raise RuntimeError("Set EXHIBITDAY_API_KEY")
def decode_json(text):
if SPEC["preserveNumbers"]:
# Quote JSON NUMBER tokens, never text inside a JSON string, to keep CSV decimals exact.
text = re.sub(r'"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?',
lambda m: m[0] if m[0].startswith('"') else json.dumps(m[0]), text)
return json.loads(text)
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, request, file, code, message, headers, new_url):
return None
OPENER = urllib.request.build_opener(NoRedirect())
def transport(method, url, headers, data):
request = urllib.request.Request(url, data=data, headers=headers, method=method)
try:
with OPENER.open(request, timeout=30) as response:
return response.status, response.read(), dict(response.headers)
except urllib.error.HTTPError as response:
try:
return response.code, response.read(), dict(response.headers)
finally:
response.close()
class ApiError(RuntimeError):
"""An API error response. Branch on error_code (and status), never on the message text.
uncertain is True when a PATCH or DELETE got no response or a server error: it may or may not have been applied."""
def __init__(self, status, body, uncertain=False):
self.status = status
self.uncertain = uncertain
self.error_code = body.get("error_code") if isinstance(body, dict) else None
super().__init__(f"{body.get('error_code')} {body.get('error_params')}: {body.get('errors')} (request {body.get('request_id')})"
if isinstance(body, dict) else "HTTP " + str(status) if status else "No response")
def call(name, params=None, body=None, key=None):
route = SPEC["requests"][name]
headers = {"Authorization": "Bearer " + API_KEY, "Accept": "application/json"}
if route["method"] == "POST":
if not key: raise RuntimeError("Persist a logical create key before sending POST")
headers["Idempotency-Key"] = key
data = None if body is None else json.dumps(body).encode("utf-8")
if data is not None:
headers["Content-Type"] = "application/json"
query = urllib.parse.urlencode(params or {})
url = BASE + route["path"] + ("?" + query if query else "")
# Only GET has automatic retries in this workflow. A PATCH or DELETE that got no response or a
# server error is never resent blindly: it may already have been applied, so the caller reads the record first.
resend = route["method"] == "GET"
for attempt in range(5):
try:
status, raw, response_headers = transport(route["method"], url, headers, data)
except (urllib.error.URLError, TimeoutError, ConnectionError, http.client.HTTPException):
if not resend:
raise ApiError(0, None, uncertain=True)
if attempt == 4:
raise
time.sleep(2 ** attempt)
continue
response_headers = {k.lower(): v for k, v in response_headers.items()}
result = None
if status != 304 and raw:
try:
result = decode_json(raw.decode("utf-8"))
except (ValueError, UnicodeError):
if status < 400:
raise RuntimeError("Expected a JSON success response")
if status >= 500 and not resend:
raise ApiError(status, result, uncertain=True)
retry = resend and (status == 429 or status >= 500)
if retry:
if attempt == 4:
raise RuntimeError("Retry limit reached; check the request outcome before starting a new create")
delay = response_headers.get("retry-after", str(2 ** attempt))
time.sleep(max(0, float(delay)))
continue
if status >= 400:
raise ApiError(status, result)
return {"status": status, "body": result, "headers": response_headers, "raw": raw}
raise RuntimeError("Retry limit reached")
def add_offset(offset, received):
result = int(offset) + received
if received <= 0 or result > 2147483647: raise RuntimeError("Cannot advance this int32 offset; reconcile the query")
return str(result)
def items(value):
if not isinstance(value, list): raise RuntimeError("Expected a JSON array")
return value
def count(value):
return len(items(value))
def either(left, right):
if not isinstance(left, bool) or not isinstance(right, bool): raise RuntimeError("Expected Boolean criteria")
return left or right
def equal(left, right):
return type(left) is type(right) and left == right
def field(value, name):
if not isinstance(value, dict) or name not in value: raise RuntimeError("Missing response field: " + name)
return value[name]
def is_empty(value):
return count(value) == 0
def is_present(value):
return value is not None and value != ""
def not_value(value):
if not isinstance(value, bool): raise RuntimeError("Expected a Boolean")
return not value
def optional(name, fallback):
value = os.environ.get(name)
return fallback if value is None or value == "" else value
def page_size(value):
if not re.fullmatch(r"[1-9][0-9]*", value) or int(value) > 2147483647: raise RuntimeError("Page size must be a positive int32")
return value
def positive_id(value):
if not re.fullmatch(r"[1-9][0-9]*", value) or int(value) > 9223372036854775807: raise RuntimeError("Use a positive record ID")
return value
def print_value(value):
print(value if isinstance(value, str) else json.dumps(value, ensure_ascii=False))
def require_condition(value, message):
if value is not True: raise RuntimeError(message)
def required(name):
value = os.environ.get(name)
if value is None or not value.strip(): raise RuntimeError("Set " + name)
return value
def text(value):
if value is None: return ""
if isinstance(value, str): return value
if isinstance(value, bool): return "true" if value else "false"
if isinstance(value, int): return str(value)
raise RuntimeError("Expected a scalar response value")
def main():
external_event_key = required("EXHIBITDAY_EXTERNAL_EVENT_KEY")
matched_event_id = optional("EXHIBITDAY_EVENT_ID", "")
if is_present(matched_event_id):
matched_event_id = positive_id(matched_event_id)
else:
matching_page_size = page_size(optional("EXHIBITDAY_PAGE_SIZE", "100"))
matching_offset = "0"
matching_query = {"filter_by_integration_metadata_field_1": external_event_key, "$limit": matching_page_size}
while True:
matching_query["$offset"] = matching_offset
matching_response = call("find_match", matching_query, None, None)
matching_page = matching_response["body"]
matching_rows = items(field(matching_page, "list_data"))
require_condition(equal(text(field(matching_page, "records_found")), text(count(matching_rows))), "records_found does not match this page's rows.")
require_condition(is_present(text(field(matching_page, "total_records"))), "The collection wrapper needs total_records.")
require_condition(either(equal(field(matching_page, "has_more"), True), equal(field(matching_page, "has_more"), False)), "Expected a Boolean has_more value.")
for matching_event in items(matching_rows):
if equal(text(field(matching_event, "integration_metadata_field_1")), external_event_key):
candidate_event_id = positive_id(text(field(matching_event, "id")))
if is_present(matched_event_id):
require_condition(equal(matched_event_id, candidate_event_id), "Multiple Events have this exact external key; resolve the ambiguity before linking.")
matched_event_id = candidate_event_id
if equal(field(matching_page, "has_more"), False):
break
require_condition(not_value(is_empty(matching_rows)), "An empty page has has_more=true; stop and reconcile the search.")
matching_offset = add_offset(matching_offset, count(matching_rows))
require_condition(is_present(matched_event_id), "No exact match was found. Decide explicitly whether to create or link a record.")
confirmation_query = {"id": matched_event_id}
confirmed_response = call("confirm_match", confirmation_query, None, None)
confirmed_event = confirmed_response["body"]
require_condition(equal(text(field(confirmed_event, "id")), matched_event_id), "The confirmed Event ID differs from the selected Event.")
require_condition(equal(text(field(confirmed_event, "integration_metadata_field_1")), external_event_key), "The Event's current metadata differs from the intended external key. Stop for review.")
print_value({"external_event_key": external_event_key, "event_id": matched_event_id})
if __name__ == "__main__":
main()
// .NET 8 console program; standard library only. Set EXHIBITDAY_API_KEY.
#nullable disable
using System;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Threading.Tasks;
class Program
{
static readonly string BaseUrl = "https://api.exhibitday.com/v1";
static readonly JsonNode Spec = JsonNode.Parse("{\"preserveNumbers\":true,\"requests\":{\"find_match\":{\"method\":\"GET\",\"path\":\"/events\"},\"confirm_match\":{\"method\":\"GET\",\"path\":\"/events/info\"}}}");
static readonly string ApiKey = HeaderKey(Required("EXHIBITDAY_API_KEY"));
static string HeaderKey(string value) { if(value.Any(c=>c<32||c>126))throw new Exception("Use the API key as one ASCII header value without control characters");return value; }
static readonly HttpClient Client = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false }) { Timeout = TimeSpan.FromSeconds(30) };
internal static Func<HttpRequestMessage, Task<HttpResponseMessage>> Send = request => Client.SendAsync(request);
sealed class Result { public int Status; public JsonNode Body; public Dictionary<string, string> Headers; public string Raw; }
// An API error response. Branch on ErrorCode (and Status), never on the message text.
// Uncertain is true when a PATCH or DELETE got no response or a server error: it may or may not have been applied.
sealed class ApiException : Exception
{
public int Status { get; }
public string ErrorCode { get; }
public bool Uncertain { get; }
public ApiException(int status, string errorCode, string message, bool uncertain = false) : base(message) { Status = status; ErrorCode = errorCode; Uncertain = uncertain; }
}
static string Required(string name)
{ var value = Environment.GetEnvironmentVariable(name); return string.IsNullOrWhiteSpace(value) ? throw new Exception("Set " + name) : value; }
static string Text(JsonNode value) => value == null ? "" :
value is JsonValue scalar && scalar.TryGetValue<string>(out var text) ? text : value.ToJsonString();
static JsonObject Query(params (string Key, string Value)[] values)
{ var result = new JsonObject(); foreach (var value in values) result[value.Key] = value.Value; return result; }
static async Task<Result> Call(string name, JsonObject query = null, JsonNode body = null,
string key = null)
{
var route = Spec["requests"][name];
var method = Text(route["method"]);
var headers = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
{ ["Authorization"] = "Bearer " + ApiKey, ["Accept"] = "application/json" };
if (method == "POST") { if (string.IsNullOrEmpty(key)) throw new Exception("Persist a logical create key before sending POST"); headers["Idempotency-Key"] = key; }
var data = body?.ToJsonString();
var suffix = query == null ? "" : string.Join("&", query.Select(p => Uri.EscapeDataString(p.Key) + "=" + Uri.EscapeDataString(Text(p.Value))));
var url = BaseUrl + Text(route["path"]) + (suffix.Length == 0 ? "" : "?" + suffix);
// Only GET has automatic retries in this workflow. A PATCH or DELETE that got no response or a
// server error is never resent blindly: it may already have been applied, so the caller reads the record first.
var resend = method == "GET";
for (var attempt = 0; attempt < 5; attempt++)
{
using var request = new HttpRequestMessage(new HttpMethod(method), url);
foreach (var header in headers) request.Headers.TryAddWithoutValidation(header.Key, header.Value);
if (data != null) request.Content = new StringContent(data, Encoding.UTF8, "application/json");
HttpResponseMessage response;
string raw;
try { response = await Send(request); }
catch (Exception error) when (error is HttpRequestException || error is TaskCanceledException)
{ if (!resend) throw new ApiException(0, null, "No response", true); if (attempt == 4) throw; await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt))); continue; }
using (response)
{
try { raw = await response.Content.ReadAsStringAsync(); }
catch (Exception error) when (error is HttpRequestException || error is TaskCanceledException)
{ if (!resend) throw new ApiException(0, null, "No response", true); if (attempt == 4) throw; await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt))); continue; }
var status = (int)response.StatusCode;
var resultHeaders = response.Headers.Concat(response.Content.Headers)
.ToDictionary(h => h.Key.ToLowerInvariant(), h => string.Join(", ", h.Value));
JsonNode result = null;
if (status != 304 && raw.Length > 0)
{
try { result = JsonNode.Parse(raw); }
catch (JsonException) { if (status < 400) throw new Exception("Expected a JSON success response"); }
}
var errorBody = result as JsonObject;
if (status >= 500 && !resend) throw new ApiException(status, errorBody == null ? null : Text(errorBody["error_code"]), "HTTP " + status, true);
var retry = resend && (status == 429 || status >= 500);
if (retry)
{
if (attempt == 4) throw new Exception("Retry limit reached; check the outcome before starting a new create");
var seconds = Math.Pow(2, attempt);
if (resultHeaders.TryGetValue("retry-after", out var requested) &&
double.TryParse(requested, NumberStyles.Float, CultureInfo.InvariantCulture, out var delay) &&
double.IsFinite(delay) && delay >= 0) seconds = delay;
await Task.Delay(TimeSpan.FromSeconds(seconds)); continue;
}
if (status >= 400) throw new ApiException(status, errorBody == null ? null : Text(errorBody["error_code"]), errorBody == null ? "HTTP " + status :
$"{Text(errorBody["error_code"])} {errorBody["error_params"]}: {errorBody["errors"]} (request {Text(errorBody["request_id"])})");
return new Result { Status = status, Body = result, Headers = resultHeaders, Raw = raw };
}
}
throw new Exception("Retry limit reached");
}
static string AddOffset(string offset,long received) { var result=checked(long.Parse(offset,CultureInfo.InvariantCulture)+received);if(received<=0||result>int.MaxValue)throw new Exception("Cannot advance this int32 offset; reconcile the query");return result.ToString(CultureInfo.InvariantCulture); }
static JsonArray Items(JsonNode value) => value as JsonArray ?? throw new Exception("Expected a JSON array");
static long Count(JsonNode value) => Items(value).Count;
static bool Either(bool left,bool right) => left || right;
static object Scalar(object value) { if(value is JsonValue json){if(json.TryGetValue<bool>(out var boolean))return boolean;if(json.TryGetValue<string>(out var text))return text;return json.ToJsonString();}return value; }
static bool Equal(object left,object right) => object.Equals(Scalar(left),Scalar(right));
static JsonNode Field(JsonNode value,string name) { if(value is not JsonObject obj || !obj.TryGetPropertyValue(name,out var item))throw new Exception("Missing response field: "+name);return item; }
static bool IsEmpty(JsonNode value) => Count(value)==0;
static bool IsPresent(string value) => value!=null && value!="";
static bool NotValue(bool value) => !value;
static string Optional(string name,string fallback) { var value=Environment.GetEnvironmentVariable(name);return value==null||value==""?fallback:value; }
static string PageSize(string value) { if(string.IsNullOrEmpty(value)||value[0]=='0'||!value.All(c=>c>='0'&&c<='9')||!int.TryParse(value,NumberStyles.None,CultureInfo.InvariantCulture,out var limit)||limit<=0)throw new Exception("Page size must be a positive int32");return value; }
static string PositiveId(string value) { if(string.IsNullOrEmpty(value)||value[0]=='0'||!value.All(c=>c>='0'&&c<='9')||!long.TryParse(value,NumberStyles.None,CultureInfo.InvariantCulture,out var id)||id<=0)throw new Exception("Use a positive record ID");return value; }
static void PrintValue(object value) => Console.WriteLine(value is string text ? text : JsonSerializer.Serialize(value));
static void RequireCondition(bool value,string message) { if(!value)throw new Exception(message); }
static string Text(object value) => value==null?"":value is JsonNode node?Text(node):Convert.ToString(value,CultureInfo.InvariantCulture);
internal static async Task Run()
{
var external_event_key = Required("EXHIBITDAY_EXTERNAL_EVENT_KEY");
var matched_event_id = Optional("EXHIBITDAY_EVENT_ID", "");
if (IsPresent(matched_event_id)) {
matched_event_id = PositiveId(matched_event_id);
} else {
var matching_page_size = PageSize(Optional("EXHIBITDAY_PAGE_SIZE", "100"));
var matching_offset = "0";
var matching_query = new JsonObject { ["filter_by_integration_metadata_field_1"] = external_event_key, ["$limit"] = matching_page_size };
while (true) {
matching_query["$offset"] = matching_offset;
var matching_response = await Call("find_match", matching_query, null, null);
var matching_page = matching_response.Body;
var matching_rows = Items(Field(matching_page, "list_data"));
RequireCondition(Equal(Text(Field(matching_page, "records_found")), Text(Count(matching_rows))), "records_found does not match this page's rows.");
RequireCondition(IsPresent(Text(Field(matching_page, "total_records"))), "The collection wrapper needs total_records.");
RequireCondition(Either(Equal(Field(matching_page, "has_more"), true), Equal(Field(matching_page, "has_more"), false)), "Expected a Boolean has_more value.");
foreach (var matching_event in Items(matching_rows)) {
if (Equal(Text(Field(matching_event, "integration_metadata_field_1")), external_event_key)) {
var candidate_event_id = PositiveId(Text(Field(matching_event, "id")));
if (IsPresent(matched_event_id)) {
RequireCondition(Equal(matched_event_id, candidate_event_id), "Multiple Events have this exact external key; resolve the ambiguity before linking.");
}
matched_event_id = candidate_event_id;
}
}
if (Equal(Field(matching_page, "has_more"), false)) {
break;
}
RequireCondition(NotValue(IsEmpty(matching_rows)), "An empty page has has_more=true; stop and reconcile the search.");
matching_offset = AddOffset(matching_offset, Count(matching_rows));
}
RequireCondition(IsPresent(matched_event_id), "No exact match was found. Decide explicitly whether to create or link a record.");
}
var confirmation_query = new JsonObject { ["id"] = matched_event_id };
var confirmed_response = await Call("confirm_match", confirmation_query, null, null);
var confirmed_event = confirmed_response.Body;
RequireCondition(Equal(Text(Field(confirmed_event, "id")), matched_event_id), "The confirmed Event ID differs from the selected Event.");
RequireCondition(Equal(Text(Field(confirmed_event, "integration_metadata_field_1")), external_event_key), "The Event's current metadata differs from the intended external key. Stop for review.");
PrintValue(new JsonObject { ["external_event_key"] = external_event_key, ["event_id"] = matched_event_id });
}
static Task Main() => Run();
}
// Java 11+ with Gson on the classpath. Set EXHIBITDAY_API_KEY; save as Main.java.
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.ToNumberPolicy;
import java.io.*;
import java.net.*;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.time.*;
import java.util.*;
public class Main {
static final Gson JSON = new GsonBuilder().setObjectToNumberStrategy(ToNumberPolicy.LAZILY_PARSED_NUMBER).create();
static final String BASE = "https://api.exhibitday.com/v1";
static final Map<String,Object> SPEC = JSON.fromJson("{\"preserveNumbers\":true,\"requests\":{\"find_match\":{\"method\":\"GET\",\"path\":\"/events\"},\"confirm_match\":{\"method\":\"GET\",\"path\":\"/events/info\"}}}", Map.class);
static final String API_KEY = headerKey(required("EXHIBITDAY_API_KEY"));
static String headerKey(String value){if(value.chars().anyMatch(c->c<32||c>126))throw new IllegalArgumentException("Use the API key as one ASCII header value without control characters");return value;}
static final HttpClient CLIENT = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).followRedirects(HttpClient.Redirect.NEVER).build();
interface RequestSender { HttpResponse<String> send(HttpRequest request)throws IOException,InterruptedException; }
static RequestSender SEND=request->CLIENT.send(request,HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
static class Result { int status; Object body; Map<String,String> headers; String raw;
Result(int s, Object b, Map<String,String> h,String r) {status=s;body=b;headers=h;raw=r;} }
// An API error response. Branch on errorCode (and status), never on the message text.
// uncertain is true when a PATCH or DELETE got no response or a server error: it may or may not have been applied.
static class ApiException extends IllegalStateException { final int status; final String errorCode; final boolean uncertain;
ApiException(int status,Object errorCode,String message) {this(status,errorCode,message,false);}
ApiException(int status,Object errorCode,String message,boolean uncertain) {super(message);this.status=status;this.errorCode=errorCode==null?null:String.valueOf(errorCode);this.uncertain=uncertain;} }
static String required(String name) {String value=System.getenv(name);if(value==null||value.trim().isEmpty())throw new IllegalArgumentException("Set "+name);return value;}
static String env(String name,String fallback) {String value=System.getenv(name);return value==null||value.isEmpty()?fallback:value;}
static String text(Object value) {return value==null?"":value.toString();}
@SuppressWarnings("unchecked") static Map<String,Object> obj(Object value) {return value==null?new LinkedHashMap<>(): (Map<String,Object>)value;}
@SuppressWarnings("unchecked") static List<Object> list(Object value) {return value==null?Collections.emptyList():(List<Object>)value;}
static Map<String,Object> map(Object... pairs) {Map<String,Object> result=new LinkedHashMap<>();for(int i=0;i<pairs.length;i+=2)result.put((String)pairs[i],pairs[i+1]);return result;}
static void pause(double seconds) {try {Thread.sleep((long)(Math.max(0,seconds)*1000));}catch(InterruptedException error){Thread.currentThread().interrupt();throw new RuntimeException(error);}}
static Result call(String name,Map<String,Object> query,Object body,String key) {
Map<String,Object> route=obj(obj(SPEC.get("requests")).get(name));String method=text(route.get("method"));
Map<String,Object> headers=map("Authorization","Bearer " + API_KEY,"Accept","application/json");
if(method.equals("POST")){if(key==null||key.isEmpty())throw new IllegalArgumentException("Persist a logical create key before sending POST");headers.put("Idempotency-Key",key);}
String data=body==null?null:JSON.toJson(body);if(data!=null)headers.put("Content-Type","application/json");
StringJoiner queryString=new StringJoiner("&");
if(query!=null)query.forEach((k,v)->queryString.add(URLEncoder.encode(k,StandardCharsets.UTF_8)+"="+URLEncoder.encode(text(v),StandardCharsets.UTF_8)));
String url=BASE+text(route.get("path"))+(queryString.length()==0?"":"?"+queryString);
// Only GET has automatic retries in this workflow. A PATCH or DELETE that got no response or a
// server error is never resent blindly: it may already have been applied, so the caller reads the record first.
boolean resend=method.equals("GET");
for(int attempt=0;attempt<5;attempt++) {
HttpRequest.Builder request=HttpRequest.newBuilder(URI.create(url)).timeout(Duration.ofSeconds(30));
headers.forEach((k,v)->request.header(k,text(v)));
request.method(method,data==null?HttpRequest.BodyPublishers.noBody():HttpRequest.BodyPublishers.ofString(data,StandardCharsets.UTF_8));
HttpResponse<String> response;
try {response=SEND.send(request.build());}
catch(InterruptedException error){Thread.currentThread().interrupt();throw new RuntimeException(error);}
catch(IOException error){if(!resend)throw new ApiException(0,null,"No response",true);if(attempt==4)throw new RuntimeException(error);pause(Math.pow(2,attempt));continue;}
int status=response.statusCode();Object parsed=null;
if(status!=304&&!response.body().isEmpty()) {
try {parsed=JSON.fromJson(response.body(),Object.class);}
catch(RuntimeException error){if(status<400)throw new IllegalStateException("Expected a JSON success response",error);}
}
Map<String,String> responseHeaders=new HashMap<>();response.headers().map().forEach((k,v)->responseHeaders.put(k.toLowerCase(Locale.ROOT),String.join(", ",v)));
if(status>=500&&!resend)throw new ApiException(status,obj(parsed).get("error_code"),"HTTP "+status,true);
boolean retry=resend&&(status==429||status>=500);
if(retry) {
if(attempt==4)throw new IllegalStateException("Retry limit reached; check the outcome before starting a new create");
double seconds=Math.pow(2,attempt);
try {double value=Double.parseDouble(responseHeaders.get("retry-after"));if(Double.isFinite(value)&&value>=0)seconds=value;}catch(Exception ignored){}
pause(seconds);continue;
}
if(status>=400)throw new ApiException(status,obj(parsed).get("error_code"),"HTTP "+status+": "+obj(parsed).get("error_code")+" (request "+obj(parsed).get("request_id")+")");
return new Result(status,parsed,responseHeaders,response.body());
}
throw new IllegalStateException("Retry limit reached");
}
static String add_offset(String offset,long received){long result=Math.addExact(Long.parseLong(offset),received);if(received<=0||result>Integer.MAX_VALUE)throw new IllegalStateException("Cannot advance this int32 offset; reconcile the query");return Long.toString(result);}
static List<Object> items(Object value){if(!(value instanceof List))throw new IllegalStateException("Expected a JSON array");return list(value);}
static long count(Object value){return items(value).size();}
static boolean either(boolean left,boolean right){return left||right;}
static boolean equal(Object left,Object right){return Objects.equals(left,right);}
static Object field(Object value,String name){if(!(value instanceof Map)||!obj(value).containsKey(name))throw new IllegalStateException("Missing response field: "+name);return obj(value).get(name);}
static boolean is_empty(Object value){return count(value)==0;}
static boolean is_present(String value){return value!=null&&!value.isEmpty();}
static boolean not_value(boolean value){return !value;}
static String optional(String name,String fallback){String value=System.getenv(name);return value==null||value.isEmpty()?fallback:value;}
static String page_size(String value){try{if(value==null||!value.matches("[1-9][0-9]*")||Integer.parseInt(value)<=0)throw new IllegalArgumentException();return value;}catch(RuntimeException error){throw new IllegalArgumentException("Page size must be a positive int32");}}
static String positive_id(String value){try{if(value==null||!value.matches("[1-9][0-9]*")||Long.parseLong(value)<=0)throw new IllegalArgumentException();return value;}catch(RuntimeException error){throw new IllegalArgumentException("Use a positive record ID");}}
static void print_value(Object value){try{String text=value instanceof String?(String)value:JSON.toJson(value);System.out.write((text+"\n").getBytes(StandardCharsets.UTF_8));}catch(IOException error){throw new UncheckedIOException(error);}}
static void require_condition(boolean value,String message){if(!value)throw new IllegalStateException(message);}
static void run()throws Exception {
String external_event_key = required("EXHIBITDAY_EXTERNAL_EVENT_KEY");
String matched_event_id = optional("EXHIBITDAY_EVENT_ID", "");
if (is_present(matched_event_id)) {
matched_event_id = positive_id(matched_event_id);
} else {
String matching_page_size = page_size(optional("EXHIBITDAY_PAGE_SIZE", "100"));
String matching_offset = "0";
Map<String,Object> matching_query = map("filter_by_integration_metadata_field_1", external_event_key, "$limit", matching_page_size);
while (true) {
matching_query.put("$offset", matching_offset);
Result matching_response = call("find_match", matching_query, null, null);
Object matching_page = matching_response.body;
List<Object> matching_rows = items(field(matching_page, "list_data"));
require_condition(equal(text(field(matching_page, "records_found")), text(count(matching_rows))), "records_found does not match this page's rows.");
require_condition(is_present(text(field(matching_page, "total_records"))), "The collection wrapper needs total_records.");
require_condition(either(equal(field(matching_page, "has_more"), true), equal(field(matching_page, "has_more"), false)), "Expected a Boolean has_more value.");
for (Object matching_event : items(matching_rows)) {
if (equal(text(field(matching_event, "integration_metadata_field_1")), external_event_key)) {
String candidate_event_id = positive_id(text(field(matching_event, "id")));
if (is_present(matched_event_id)) {
require_condition(equal(matched_event_id, candidate_event_id), "Multiple Events have this exact external key; resolve the ambiguity before linking.");
}
matched_event_id = candidate_event_id;
}
}
if (equal(field(matching_page, "has_more"), false)) {
break;
}
require_condition(not_value(is_empty(matching_rows)), "An empty page has has_more=true; stop and reconcile the search.");
matching_offset = add_offset(matching_offset, count(matching_rows));
}
require_condition(is_present(matched_event_id), "No exact match was found. Decide explicitly whether to create or link a record.");
}
Map<String,Object> confirmation_query = map("id", matched_event_id);
Result confirmed_response = call("confirm_match", confirmation_query, null, null);
Object confirmed_event = confirmed_response.body;
require_condition(equal(text(field(confirmed_event, "id")), matched_event_id), "The confirmed Event ID differs from the selected Event.");
require_condition(equal(text(field(confirmed_event, "integration_metadata_field_1")), external_event_key), "The Event's current metadata differs from the intended external key. Stop for review.");
print_value(map("external_event_key", external_event_key, "event_id", matched_event_id));
}
public static void main(String[] args)throws Exception {run();}
}
<?php
// PHP 8.1+ with the cURL extension. Set EXHIBITDAY_API_KEY before running.
declare(strict_types=1);
const BASE = 'https://api.exhibitday.com/v1';
const SPEC = '{"preserveNumbers":true,"requests":{"find_match":{"method":"GET","path":"/events"},"confirm_match":{"method":"GET","path":"/events/info"}}}';
$spec = json_decode(SPEC, true, 512, JSON_THROW_ON_ERROR);
$apiKey = required('EXHIBITDAY_API_KEY');
if(preg_match('/[^\x20-\x7e]/',$apiKey))throw new RuntimeException('Use the API key as one ASCII header value without control characters');
if (trim($apiKey) === '') throw new RuntimeException('Set EXHIBITDAY_API_KEY');
function required(string $name, bool $allowEmpty = false): string {
$value = getenv($name);
if ($value === false || (!$allowEmpty && $value === '')) {
throw new RuntimeException('Set ' . $name);
}
return $value;
}
function optional(string $name, string $fallback): string {
$value = getenv($name);
return $value === false ? $fallback : $value;
}
function decodeJson(string $text): mixed {
global $spec;
if ($spec['preserveNumbers']) {
// Quote NUMBER tokens without changing digits inside JSON strings; CSV decimals stay exact.
$pattern = <<<'JSON_NUMBER'
~"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?~
JSON_NUMBER;
$text = preg_replace_callback($pattern, static function (array $match): string {
return str_starts_with($match[0], '"') ? $match[0] : json_encode($match[0], JSON_THROW_ON_ERROR);
}, $text);
if ($text === null) throw new RuntimeException('Unable to preserve decimal tokens');
}
return json_decode($text, true, 512, JSON_THROW_ON_ERROR);
}
function nativeTransport(string $method, string $url, array $headers, ?string $data): array {
$responseHeaders = [];
$handle = curl_init($url);
if ($handle === false) throw new RuntimeException('Unable to initialize cURL');
$headerLines = [];
foreach ($headers as $name => $value) $headerLines[] = $name . ': ' . $value;
$options = [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false,
CURLOPT_CONNECTTIMEOUT => 30, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => $headerLines,
CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
if (str_starts_with($line, 'HTTP/')) $responseHeaders = [];
$separator = strpos($line, ':');
if ($separator !== false) {
$responseHeaders[strtolower(trim(substr($line, 0, $separator)))] = trim(substr($line, $separator + 1));
}
return strlen($line);
}];
if ($data !== null) $options[CURLOPT_POSTFIELDS] = $data;
try {
curl_setopt_array($handle, $options);
$raw = curl_exec($handle);
if ($raw === false) throw new RuntimeException('Network request failed: ' . curl_error($handle));
return [(int)curl_getinfo($handle, CURLINFO_RESPONSE_CODE), $raw, $responseHeaders];
} finally {
curl_close($handle);
}
}
function retryDelay(array $headers, int $attempt): float {
$value = $headers['retry-after'] ?? '';
if (is_numeric($value)) return max(0.0, (float)$value);
$date = $value === '' ? false : strtotime($value);
return $date === false ? (float)(2 ** $attempt) : max(0.0, (float)($date - time()));
}
// An API error response. Branch on errorCode (and status), never on the message text.
// $uncertain is true when a PATCH or DELETE got no response or a server error: it may or may not have been applied.
final class ApiException extends RuntimeException {
public function __construct(public readonly int $status, public readonly ?string $errorCode, string $message, public readonly bool $uncertain = false) {
parent::__construct($message);
}
}
function call(string $name, array $params = [], mixed $body = null, ?string $key = null): array {
global $spec, $apiKey, $transport;
$route = $spec['requests'][$name];
$headers = ['Authorization' => 'Bearer ' . $apiKey, 'Accept' => 'application/json'];
if ($route['method'] === 'POST') {
if ($key === null || $key === '') throw new RuntimeException('Persist a logical create key before sending POST');
$headers['Idempotency-Key'] = $key; // ONCE, before retries.
}
$data = $body === null ? null : json_encode($body, JSON_THROW_ON_ERROR);
if ($data !== null) $headers['Content-Type'] = 'application/json';
$query = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
$url = BASE . $route['path'] . ($query === '' ? '' : '?' . $query);
// Only GET has automatic retries in this workflow. A PATCH or DELETE that got no response or a
// server error is never resent blindly: it may already have been applied, so the caller reads the record first.
$resend = $route['method'] === 'GET';
for ($attempt = 0; $attempt < 5; $attempt++) {
try {
[$status, $raw, $responseHeaders] = $transport($route['method'], $url, $headers, $data);
} catch (RuntimeException $error) {
if (!$resend) throw new ApiException(0, null, 'No response', true);
if ($attempt === 4) throw $error;
usleep((int)((2 ** $attempt) * 1000000));
continue;
}
$responseHeaders = array_change_key_case($responseHeaders, CASE_LOWER);
$result = null;
if ($status !== 304 && $raw !== '') {
try { $result = decodeJson($raw); }
catch (JsonException $error) {
if ($status < 400) throw new RuntimeException('Expected a JSON success response', 0, $error);
}
}
if ($status >= 500 && !$resend) {
throw new ApiException($status, is_array($result) && isset($result['error_code']) ? (string)$result['error_code'] : null, 'HTTP ' . $status, true);
}
$retry = $resend && ($status === 429 || $status >= 500);
if ($retry) {
if ($attempt === 4) throw new RuntimeException('Retry limit reached; check the outcome before starting a new create');
usleep((int)(retryDelay($responseHeaders, $attempt) * 1000000));
continue;
}
if ($status >= 400) {
if (!is_array($result)) throw new ApiException($status, null, 'HTTP ' . $status);
throw new ApiException($status, isset($result['error_code']) ? (string)$result['error_code'] : null, json_encode(['error_code' => $result['error_code'] ?? null,
'error_params' => $result['error_params'] ?? null, 'errors' => $result['errors'] ?? null,
'request_id' => $result['request_id'] ?? null], JSON_THROW_ON_ERROR));
}
return ['status' => $status, 'body' => $result, 'headers' => $responseHeaders, 'raw' => $raw];
}
throw new RuntimeException('Retry limit reached');
}
$transport = Closure::fromCallable('nativeTransport');
function add_offset(string $offset,int $received):string{$result=(int)$offset+$received;if($received<=0||$result>2147483647)throw new RuntimeException("Cannot advance this int32 offset; reconcile the query");return (string)$result;}
function either(bool $left,bool $right):bool{return $left||$right;}
function equal(mixed $left,mixed $right):bool{return $left===$right;}
function field(mixed $value,string $name):mixed{if(!is_array($value)||!array_key_exists($name,$value))throw new RuntimeException("Missing response field: ".$name);return $value[$name];}
function items(mixed $value):array{if(!is_array($value)||!array_is_list($value))throw new RuntimeException("Expected a JSON array");return $value;}
function is_empty(mixed $value):bool{return count(items($value))===0;}
function is_present(?string $value):bool{return $value!==null&&$value!=="";}
function not_value(bool $value):bool{return !$value;}
function page_size(string $value):string{if(!preg_match("/^[1-9][0-9]*$/D",$value)||strlen($value)>10||(strlen($value)===10&&strcmp($value,"2147483647")>0))throw new RuntimeException("Page size must be a positive int32");return $value;}
function positive_id(string $value):string{if(!preg_match("/^[1-9][0-9]*$/D",$value)||strlen($value)>19||(strlen($value)===19&&strcmp($value,"9223372036854775807")>0))throw new RuntimeException("Use a positive record ID");return $value;}
function print_value(mixed $value):void{echo (is_string($value)?$value:json_encode($value,JSON_THROW_ON_ERROR))."\n";}
function require_condition(bool $value,string $message):void{if(!$value)throw new RuntimeException($message);}
function text(mixed $value):string{if($value===null)return "";if(is_string($value))return $value;if(is_bool($value))return $value?"true":"false";if(is_int($value))return (string)$value;throw new RuntimeException("Expected a scalar response value");}
function main():void {
$external_event_key = required('EXHIBITDAY_EXTERNAL_EVENT_KEY');
$matched_event_id = optional('EXHIBITDAY_EVENT_ID', '');
if (is_present($matched_event_id)) {
$matched_event_id = positive_id($matched_event_id);
} else {
$matching_page_size = page_size(optional('EXHIBITDAY_PAGE_SIZE', '100'));
$matching_offset = '0';
$matching_query = ['filter_by_integration_metadata_field_1' => $external_event_key, '$limit' => $matching_page_size];
while (true) {
$matching_query['$offset'] = $matching_offset;
$matching_response = call('find_match', $matching_query, null, null);
$matching_page = $matching_response["body"];
$matching_rows = items(field($matching_page, 'list_data'));
require_condition(equal(text(field($matching_page, 'records_found')), text(count($matching_rows))), 'records_found does not match this page\'s rows.');
require_condition(is_present(text(field($matching_page, 'total_records'))), 'The collection wrapper needs total_records.');
require_condition(either(equal(field($matching_page, 'has_more'), true), equal(field($matching_page, 'has_more'), false)), 'Expected a Boolean has_more value.');
foreach (items($matching_rows) as $matching_event) {
if (equal(text(field($matching_event, 'integration_metadata_field_1')), $external_event_key)) {
$candidate_event_id = positive_id(text(field($matching_event, 'id')));
if (is_present($matched_event_id)) {
require_condition(equal($matched_event_id, $candidate_event_id), 'Multiple Events have this exact external key; resolve the ambiguity before linking.');
}
$matched_event_id = $candidate_event_id;
}
}
if (equal(field($matching_page, 'has_more'), false)) {
break;
}
require_condition(not_value(is_empty($matching_rows)), 'An empty page has has_more=true; stop and reconcile the search.');
$matching_offset = add_offset($matching_offset, count($matching_rows));
}
require_condition(is_present($matched_event_id), 'No exact match was found. Decide explicitly whether to create or link a record.');
}
$confirmation_query = ['id' => $matched_event_id];
$confirmed_response = call('confirm_match', $confirmation_query, null, null);
$confirmed_event = $confirmed_response["body"];
require_condition(equal(text(field($confirmed_event, 'id')), $matched_event_id), 'The confirmed Event ID differs from the selected Event.');
require_condition(equal(text(field($confirmed_event, 'integration_metadata_field_1')), $external_event_key), 'The Event\'s current metadata differs from the intended external key. Stop for review.');
print_value((object)['external_event_key' => $external_event_key, 'event_id' => $matched_event_id]);
}
if (realpath($_SERVER['SCRIPT_FILENAME'] ?? '') === __FILE__) main();
# Ruby 3.1+; standard library only. Set EXHIBITDAY_API_KEY before running.
require 'net/http'
require 'json'
require 'uri'
require 'csv'
require 'fileutils'
require 'securerandom'
require 'date'
require 'time'
require 'timeout'
BASE = 'https://api.exhibitday.com/v1'
SPEC = JSON.parse('{"preserveNumbers":true,"requests":{"find_match":{"method":"GET","path":"/events"},"confirm_match":{"method":"GET","path":"/events/info"}}}')
API_KEY = ENV.fetch('EXHIBITDAY_API_KEY')
raise 'Use the API key as one ASCII header value without control characters' if API_KEY.each_codepoint.any?{|point|point<32||point>126}
def decode_json(text)
if SPEC.fetch('preserveNumbers')
# Preserve JSON NUMBER lexemes for CSV, without replacing digits inside JSON strings.
text = text.gsub(/"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/) do |token|
token.start_with?('"') ? token : JSON.generate(token)
end
end
JSON.parse(text)
end
def transport(method, url, headers, data)
uri = URI(url)
request_type = { 'GET' => Net::HTTP::Get, 'POST' => Net::HTTP::Post,
'PATCH' => Net::HTTP::Patch, 'DELETE' => Net::HTTP::Delete }.fetch(method)
request = request_type.new(uri.request_uri, headers)
request.body = data unless data.nil?
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
http.open_timeout = http.read_timeout = http.write_timeout = 30
http.max_retries = 0 # The outer loop owns the bounded retry policy.
response = http.start { |client| client.request(request) }
[response.code.to_i, response.body.to_s, response.each_header.to_h]
end
def retry_delay(headers, attempt)
value = headers['retry-after']
return 2**attempt if value.nil? || value.empty?
begin
[Float(value), 0].max
rescue ArgumentError, TypeError
begin
[Time.httpdate(value) - Time.now, 0].max
rescue ArgumentError
2**attempt
end
end
end
# An API error response. Branch on error_code (and status), never on the message text.
# uncertain is true when a PATCH or DELETE got no response or a server error: it may or may not have been applied.
class ApiError < RuntimeError
attr_reader :status, :error_code, :uncertain
def initialize(status, error_code, message, uncertain = false)
super(message)
@status = status
@error_code = error_code
@uncertain = uncertain
end
end
def call(name, params = {}, body = nil, key = nil)
route = SPEC.fetch('requests').fetch(name)
headers = { 'Authorization' => 'Bearer ' + API_KEY, 'Accept' => 'application/json' }
if route.fetch('method') == 'POST'
headers['Idempotency-Key'] = key || raise('Persist a logical create key before sending POST') # ONCE before retries.
end
data = body.nil? ? nil : JSON.generate(body)
headers['Content-Type'] = 'application/json' unless data.nil?
query = URI.encode_www_form(params)
url = BASE + route.fetch('path') + (query.empty? ? '' : '?' + query)
# Only GET has automatic retries in this workflow. A PATCH or DELETE that got no response or a
# server error is never resent blindly: it may already have been applied, so the caller reads the record first.
resend = route.fetch('method') == 'GET'
5.times do |attempt|
begin
status, raw, response_headers = transport(route.fetch('method'), url, headers, data)
rescue IOError, SystemCallError, Timeout::Error, SocketError
raise ApiError.new(0, nil, 'No response', true) unless resend
raise if attempt == 4
sleep(2**attempt)
next
end
response_headers = response_headers.transform_keys(&:downcase)
result = nil
unless status == 304 || raw.empty?
begin
result = decode_json(raw)
rescue JSON::ParserError, EncodingError
raise 'Expected a JSON success response' if status < 400
end
end
if status >= 500 && !resend
raise ApiError.new(status, result.is_a?(Hash) ? result['error_code'] : nil, "HTTP #{status}", true)
end
transient = resend && (status == 429 || (500..599).cover?(status))
if transient
raise 'Retry limit reached; check the outcome before starting a new create' if attempt == 4
sleep(retry_delay(response_headers, attempt))
next
end
if status >= 400
raise ApiError.new(status, nil, "HTTP #{status}") unless result.is_a?(Hash)
raise ApiError.new(status, result['error_code'], "#{result['error_code']} #{result['error_params'].inspect}: #{result['errors'].inspect} (request #{result['request_id']})")
end
return { status: status, body: result, headers: response_headers, raw: raw }
end
raise 'Retry limit reached'
end
def add_offset(offset,received)
result=Integer(offset)+received
raise "Cannot advance this int32 offset; reconcile the query" if received<=0 || result>2147483647
result.to_s
end
def items(value)
raise "Expected a JSON array" unless value.is_a?(Array)
value
end
def count(value)
items(value).length
end
def either(left,right)
raise "Expected Boolean criteria" unless [true,false].include?(left) && [true,false].include?(right)
left || right
end
def equal(left,right)
left.class==right.class && left==right
end
def field(value,name)
raise "Missing response field: #{name}" unless value.is_a?(Hash) && value.key?(name)
value.fetch(name)
end
def is_empty(value)
count(value)==0
end
def is_present(value)
!value.nil? && value!=""
end
def not_value(value)
raise "Expected a Boolean" unless value==true || value==false
!value
end
def optional(name,fallback)
value=ENV[name]
value.nil? || value.empty? ? fallback : value
end
def page_size(value)
raise "Page size must be a positive int32" unless /\A[1-9][0-9]*\z/.match?(value) && Integer(value)<=2147483647
value
end
def positive_id(value)
raise "Use a positive record ID" unless /\A[1-9][0-9]*\z/.match?(value) && Integer(value)<=9223372036854775807
value
end
def print_value(value)
STDOUT.binmode.write((value.is_a?(String)?value:JSON.generate(value))+"\n")
end
def require_condition(value,message)
raise message unless value==true
end
def required(name)
value=ENV[name]
raise "Set #{name}" if value.nil? || value.strip.empty?
value
end
def text(value)
return "" if value.nil?
return value.to_s if value.is_a?(String)||value.is_a?(Integer)||value==true||value==false
raise "Expected a scalar response value"
end
def main
external_event_key = required('EXHIBITDAY_EXTERNAL_EVENT_KEY')
matched_event_id = optional('EXHIBITDAY_EVENT_ID', '')
if is_present(matched_event_id)
matched_event_id = positive_id(matched_event_id)
else
matching_page_size = page_size(optional('EXHIBITDAY_PAGE_SIZE', '100'))
matching_offset = '0'
matching_query = {'filter_by_integration_metadata_field_1' => external_event_key, '$limit' => matching_page_size}
while true
matching_query['$offset'] = matching_offset
matching_response = call('find_match', matching_query, nil, nil)
matching_page = matching_response.fetch(:body)
matching_rows = items(field(matching_page, 'list_data'))
require_condition(equal(text(field(matching_page, 'records_found')), text(count(matching_rows))), 'records_found does not match this page\'s rows.')
require_condition(is_present(text(field(matching_page, 'total_records'))), 'The collection wrapper needs total_records.')
require_condition(either(equal(field(matching_page, 'has_more'), true), equal(field(matching_page, 'has_more'), false)), 'Expected a Boolean has_more value.')
items(matching_rows).each do |matching_event|
if equal(text(field(matching_event, 'integration_metadata_field_1')), external_event_key)
candidate_event_id = positive_id(text(field(matching_event, 'id')))
if is_present(matched_event_id)
require_condition(equal(matched_event_id, candidate_event_id), 'Multiple Events have this exact external key; resolve the ambiguity before linking.')
end
matched_event_id = candidate_event_id
end
end
if equal(field(matching_page, 'has_more'), false)
break
end
require_condition(not_value(is_empty(matching_rows)), 'An empty page has has_more=true; stop and reconcile the search.')
matching_offset = add_offset(matching_offset, count(matching_rows))
end
require_condition(is_present(matched_event_id), 'No exact match was found. Decide explicitly whether to create or link a record.')
end
confirmation_query = {'id' => matched_event_id}
confirmed_response = call('confirm_match', confirmation_query, nil, nil)
confirmed_event = confirmed_response.fetch(:body)
require_condition(equal(text(field(confirmed_event, 'id')), matched_event_id), 'The confirmed Event ID differs from the selected Event.')
require_condition(equal(text(field(confirmed_event, 'integration_metadata_field_1')), external_event_key), 'The Event\'s current metadata differs from the intended external key. Stop for review.')
print_value({'external_event_key' => external_event_key, 'event_id' => matched_event_id})
end
main if $PROGRAM_NAME == __FILE__
// Go 1.18+; standard library only. Set EXHIBITDAY_API_KEY.
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
"net/url"
"os"
"strconv"
"strings"
"time"
)
const base = "https://api.exhibitday.com/v1"
const specification = "{\"preserveNumbers\":true,\"requests\":{\"find_match\":{\"method\":\"GET\",\"path\":\"/events\"},\"confirm_match\":{\"method\":\"GET\",\"path\":\"/events/info\"}}}"
var spec map[string]any
var apiKey string
var client = &http.Client{Timeout: 30 * time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }}
var send = client.Do
type result struct { status int; body any; headers http.Header; raw []byte }
// An API error response (raised with panic). Branch on code (and status), never on the message text.
// uncertain is true when a PATCH or DELETE got no response or a server error: it may or may not have been applied.
type apiError struct { status int; code string; message string; uncertain bool }
func (failure apiError) Error() string { return failure.message }
func required(name string) string {
value := os.Getenv(name); if strings.TrimSpace(value) == "" { panic("Set " + name) }; return value
}
func text(value any) string { if value == nil { return "" }; return fmt.Sprint(value) }
func object(value any) map[string]any { if value == nil { return map[string]any{} }; return value.(map[string]any) }
func array(value any) []any { if value == nil { return nil }; return value.([]any) }
func decode(raw []byte) (any, error) {
var value any
decoder := json.NewDecoder(bytes.NewReader(raw)); decoder.UseNumber() // keeps exact decimal tokens
err := decoder.Decode(&value); return value, err
}
func call(name string, query map[string]string, body any, key string) result {
route := object(object(spec["requests"])[name]); method := text(route["method"])
headers := map[string]string{"Authorization": "Bearer " + apiKey, "Accept": "application/json"}
if method == "POST" { if key == "" { panic("Persist a logical create key before sending POST") }; headers["Idempotency-Key"] = key } // before retry loop
var data []byte
if body != nil { var err error; data, err = json.Marshal(body); if err != nil { panic(err) }; headers["Content-Type"] = "application/json" }
values := url.Values{}; for k,v := range query { values.Set(k,v) }
address := base + text(route["path"]); if len(values) > 0 { address += "?" + values.Encode() }
// Only GET has automatic retries in this workflow. A PATCH or DELETE that got no response or a
// server error is never resent blindly: it may already have been applied, so the caller reads the record first.
resend := method == "GET"
for attempt := 0; attempt < 5; attempt++ {
request, err := http.NewRequest(method, address, bytes.NewReader(data)); if err != nil { panic(err) }
for k,v := range headers { request.Header.Set(k,v) }
response, err := send(request)
if err != nil { if !resend { panic(apiError{0, "", "No response", true}) }; if attempt == 4 { panic(err) }; time.Sleep(time.Second*time.Duration(1<<attempt)); continue }
raw, readErr := io.ReadAll(response.Body); response.Body.Close()
if readErr != nil { if !resend { panic(apiError{0, "", "No response", true}) }; if attempt == 4 { panic(readErr) }; time.Sleep(time.Second*time.Duration(1<<attempt)); continue }
var parsed any
if response.StatusCode != 304 && len(raw)>0 {
parsed, err = decode(raw)
if err != nil && response.StatusCode < 400 { panic("Expected a JSON success response") }
}
errorBody, _ := parsed.(map[string]any)
if response.StatusCode >= 500 && !resend { panic(apiError{response.StatusCode, text(errorBody["error_code"]), fmt.Sprintf("HTTP %d", response.StatusCode), true}) }
retry := resend && (response.StatusCode == 429 || response.StatusCode >= 500)
if retry {
if attempt == 4 { panic("Retry limit reached; check the outcome before starting a new create") }
seconds := float64(int64(1)<<attempt)
if value, err := strconv.ParseFloat(response.Header.Get("Retry-After"),64); err == nil && value >= 0 { seconds = value }
time.Sleep(time.Duration(seconds*float64(time.Second))); continue
}
if response.StatusCode >= 400 { panic(apiError{response.StatusCode, text(errorBody["error_code"]), fmt.Sprintf("HTTP %d: %v (request %v)",response.StatusCode,errorBody["error_code"],errorBody["request_id"]), false}) }
return result{response.StatusCode, parsed, response.Header, raw}
}
panic("Retry limit reached")
}
func add_offset(offset string,received int64)string{previous,err:=strconv.ParseInt(offset,10,32);if err!=nil||received<=0||received>2147483647-previous{panic("Cannot advance this int32 offset; reconcile the query")};return strconv.FormatInt(previous+received,10)}
func items(value any)[]any{result,ok:=value.([]any);if !ok{panic("Expected a JSON array")};return result}
func count(value any)int64{return int64(len(items(value)))}
func either(left,right bool)bool{return left||right}
func equal(left,right any)bool{switch a:=left.(type){case string:b,ok:=right.(string);return ok&&a==b;case bool:b,ok:=right.(bool);return ok&&a==b;case int64:b,ok:=right.(int64);return ok&&a==b};return left==nil&&right==nil}
func field(value any,name string)any{obj,ok:=value.(map[string]any);if !ok{panic("Missing response object")};item,found:=obj[name];if !found{panic("Missing response field: "+name)};return item}
func is_empty(value any)bool{return count(value)==0}
func is_present(value string)bool{return value!=""}
func not_value(value bool)bool{return !value}
func optional(name,fallback string)string{value:=os.Getenv(name);if value==""{return fallback};return value}
func page_size(value string)string{valid:=len(value)>0&&value[0]!='0';for _,ch:=range value{valid=valid&&ch>='0'&&ch<='9'};size,err:=strconv.ParseInt(value,10,32);if !valid||err!=nil||size<=0{panic("Page size must be a positive int32")};return value}
func positive_id(value string)string{valid:=len(value)>0&&value[0]!='0';for _,ch:=range value{valid=valid&&ch>='0'&&ch<='9'};id,err:=strconv.ParseInt(value,10,64);if !valid||err!=nil||id<=0{panic("Use a positive record ID")};return value}
func print_value(value any){if result,ok:=value.(string);ok{fmt.Println(result);return};raw,err:=json.Marshal(value);if err!=nil{panic(err)};fmt.Println(string(raw))}
func require_condition(value bool,message string){if !value{panic(message)}}
func workflow() {
external_event_key := required("EXHIBITDAY_EXTERNAL_EVENT_KEY")
matched_event_id := optional("EXHIBITDAY_EVENT_ID", "")
if is_present(matched_event_id) {
matched_event_id = positive_id(matched_event_id)
} else {
matching_page_size := page_size(optional("EXHIBITDAY_PAGE_SIZE", "100"))
matching_offset := "0"
matching_query := map[string]string{"filter_by_integration_metadata_field_1": external_event_key, "$limit": matching_page_size}
for true {
matching_query["$offset"] = matching_offset
matching_response := call("find_match", matching_query, nil, "")
matching_page := matching_response.body
matching_rows := items(field(matching_page, "list_data"))
require_condition(equal(text(field(matching_page, "records_found")), text(count(matching_rows))), "records_found does not match this page's rows.")
require_condition(is_present(text(field(matching_page, "total_records"))), "The collection wrapper needs total_records.")
require_condition(either(equal(field(matching_page, "has_more"), true), equal(field(matching_page, "has_more"), false)), "Expected a Boolean has_more value.")
for _, matching_event := range items(matching_rows) {
if equal(text(field(matching_event, "integration_metadata_field_1")), external_event_key) {
candidate_event_id := positive_id(text(field(matching_event, "id")))
if is_present(matched_event_id) {
require_condition(equal(matched_event_id, candidate_event_id), "Multiple Events have this exact external key; resolve the ambiguity before linking.")
}
matched_event_id = candidate_event_id
}
}
if equal(field(matching_page, "has_more"), false) {
break
}
require_condition(not_value(is_empty(matching_rows)), "An empty page has has_more=true; stop and reconcile the search.")
matching_offset = add_offset(matching_offset, count(matching_rows))
}
require_condition(is_present(matched_event_id), "No exact match was found. Decide explicitly whether to create or link a record.")
}
confirmation_query := map[string]string{"id": matched_event_id}
confirmed_response := call("confirm_match", confirmation_query, nil, "")
confirmed_event := confirmed_response.body
require_condition(equal(text(field(confirmed_event, "id")), matched_event_id), "The confirmed Event ID differs from the selected Event.")
require_condition(equal(text(field(confirmed_event, "integration_metadata_field_1")), external_event_key), "The Event's current metadata differs from the intended external key. Stop for review.")
print_value(map[string]any{"external_event_key": external_event_key, "event_id": matched_event_id})
}
func header_key(value string)string{for _,ch:=range value{if ch<32||ch>126{panic("Use the API key as one ASCII header value without control characters")}};return value}
func main(){apiKey=header_key(required("EXHIBITDAY_API_KEY"));if err:=json.Unmarshal([]byte(specification),&spec);err!=nil{panic(err)};workflow()}
Example response
{
"id": 12345,
"exhibitday_url": "https://www.exhibitday.com/Workspace/Event/98765?eid=12345",
"name": "Spring Expo 2030",
"start_date": "2030-01-14",
"end_date": "2030-01-16",
"participation_type_id": 1,
"participation_type": "Committed",
"format_id": 1,
"format": "In-Person",
"star_rating": 0,
"tags": [
"International",
"Field Marketing"
],
"website_url": "",
"venue_name": "",
"venue_address": "",
"venue_location_display_name": "",
"venue_address_latitude": "",
"venue_address_longitude": "",
"booth_size": "",
"booth_number": "",
"booth_reservation_status_id": 1,
"booth_reservation_status": "Need to Reserve",
"booth_reserve_by_date": "",
"booth_date_reserved": "",
"budget_booth_reservation": 0.00,
"budget_booth_services": 0.00,
"budget_attendee_registrations": 0.00,
"budget_travel": 0.00,
"budget_giveaways": 0.00,
"budget_shipments": 0.00,
"budget_event_activities": 0.00,
"budget_misc_expenses": 0.00,
"budget_sponsorships": 0.00,
"total_sum_event_budgets": 0.00,
"booth_reservation_cost": {
"amount": 125.50,
"cost_center_breakdown": [
{
"cost_center_id": 34567,
"cost_center": "Marketing",
"charge": 75.50
},
{
"cost_center_id": 34568,
"cost_center": "Operations",
"charge": 50.00
}
]
},
"cost_booth_reservation": 125.50,
"booth_reservation_payment_status_id": 0,
"booth_reservation_payment_status": "",
"booth_reservation_payment_due_date": null,
"booth_reservation_next_payment_due_date": null,
"booth_reservation_payment_notes": null,
"booth_reservation_invoice_attachment": {
"id": 182345,
"filename": "booth-reservation-invoice.pdf",
"attachment_created_timestamp": "2027-01-30T12:00:00Z"
},
"cost_booth_services": 0.00,
"cost_attendee_registrations": 0.00,
"cost_travel_reservations": 0.00,
"cost_giveaways": 0.00,
"cost_shipments": 0.00,
"cost_event_activities": 0.00,
"cost_misc_expenses": 100.50,
"cost_sponsorships": 0.00,
"total_sum_event_costs": 226.00,
"event_notes": "",
"booth_notes": "",
"budget_notes": "",
"roi_notes": "",
"roi_num_leads": 0,
"roi_num_impressions_booth": 0,
"roi_num_impressions_sponsorships": 0,
"roi_num_impressions_media": 0,
"roi_num_meetings_existing_customers": 0,
"roi_num_meetings_new_customers": 0,
"roi_amount_actual_sales": 0.00,
"roi_amount_potential_sales": 0.00,
"roo_score": null,
"event_created_timestamp": "2029-12-01T17:00:00Z",
"event_last_update_timestamp": "2030-01-02T17:00:00Z",
"event_created_by": null,
"custom_fields": [
{
"label": "Integration status",
"value": "Ready",
"notes": "",
"field_name": "custom_67890",
"field_type": "Text (Single-line)",
"field_event_tab": "Info"
},
{
"label": "Setup instructions",
"value": "Place the display beside the entrance.",
"notes": "",
"field_name": "custom_67891",
"field_type": "Text (Single-line)",
"field_event_tab": "Booth"
}
],
"task_sections": [
{
"id": 13346,
"name": "Planning",
"display_rank": 1
},
{
"id": 13347,
"name": "At the Event",
"display_rank": 2
}
],
"tasks": [
{
"id": 14346,
"exhibitday_url": "https://www.exhibitday.com/Workspace/TaskView/98765?tid=14346",
"event_task_section_id": 13346,
"event_task_section": "Planning",
"display_rank": 1,
"name": "Confirm booth setup",
"due_date": "2026-12-10",
"assignee": {
"id": "11111111-2222-4333-8444-555555555555",
"first_name": "Jane",
"last_name": "Smith",
"display_name": "Jane Smith",
"email": "jane@example.invalid",
"type": "user",
"workspace_role": "team_member",
"is_active": true
},
"is_completed": false,
"task_completed_timestamp": null,
"task_created_timestamp": "2029-12-01T17:01:00Z",
"task_last_update_timestamp": "2029-12-01T17:01:00Z"
},
{
"id": 14347,
"exhibitday_url": "https://www.exhibitday.com/Workspace/TaskView/98765?tid=14347",
"event_task_section_id": 13347,
"event_task_section": "At the Event",
"display_rank": 2,
"name": "Prepare the staff schedule",
"due_date": "2026-12-11",
"assignee": {
"id": "66666666-7777-4888-8999-aaaaaaaaaaaa",
"first_name": "Alex",
"last_name": "Jordan",
"display_name": "Alex Jordan",
"email": "alex@example.invalid",
"type": "user",
"workspace_role": "team_member",
"is_active": true
},
"is_completed": false,
"task_completed_timestamp": null,
"task_created_timestamp": "2029-12-01T17:02:00Z",
"task_last_update_timestamp": "2029-12-01T17:02:00Z"
}
],
"misc_expenses_credits": [
{
"id": 15346,
"exhibitday_url": "https://www.exhibitday.com/Workspace/Event/98765?eid=12345&riType=8&riSub=0&riId=15346",
"description": "Conference meals",
"is_credit": false,
"cost": {
"amount": 125.50,
"cost_center_breakdown": [
{
"cost_center_id": 34567,
"cost_center": "Marketing",
"charge": 75.50
},
{
"cost_center_id": 34568,
"cost_center": "Operations",
"charge": 50.00
}
]
},
"notes": "",
"payment_due_date": null,
"payment_status": {
"id": 0,
"name": "Not Specified"
},
"next_payment_due_date": null,
"next_partial_payment_due_date": null,
"payment_notes": null,
"invoice_attachment": {
"id": 685346,
"filename": "expense-invoice.pdf",
"attachment_created_timestamp": "2027-01-30T12:00:00Z"
},
"event_misc_expense_credit_created_timestamp": "2029-12-01T17:00:00Z",
"event_misc_expense_credit_last_update_timestamp": "2029-12-01T17:00:00Z"
},
{
"id": 15347,
"exhibitday_url": "https://www.exhibitday.com/Workspace/Event/98765?eid=12345&riType=8&riSub=0&riId=15347",
"description": "Supplier refund",
"is_credit": true,
"cost": {
"amount": -25.00,
"cost_center_breakdown": [
{
"cost_center_id": 34567,
"cost_center": "Marketing",
"charge": -15.00
},
{
"cost_center_id": 34568,
"cost_center": "Operations",
"charge": -10.00
}
]
},
"notes": "",
"payment_due_date": null,
"payment_status": {
"id": 0,
"name": "Not Specified"
},
"next_payment_due_date": null,
"next_partial_payment_due_date": null,
"payment_notes": null,
"invoice_attachment": {
"id": 685347,
"filename": "expense-invoice.pdf",
"attachment_created_timestamp": "2027-01-30T12:00:00Z"
},
"event_misc_expense_credit_created_timestamp": "2029-12-01T17:00:00Z",
"event_misc_expense_credit_last_update_timestamp": "2029-12-01T17:00:00Z"
}
],
"integration_metadata_field_1": "crm:event:spring-expo-2030",
"integration_metadata_field_2": null,
"integration_metadata_field_3": null,
"integration_metadata_field_4": null,
"integration_metadata_field_5": null
}
{
"status_code": 400,
"status": "Bad Request",
"message": "HTTP method override is not supported.",
"error_code": "invalid_request",
"errors": [
"Send the documented HTTP method directly. X-HTTP-Method-Override cannot change a request's HTTP method."
],
"error_params": [
"X-HTTP-Method-Override"
],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 401,
"status": "Unauthorized",
"message": "No API key was provided. Send your key in the Authorization header as 'Bearer YOUR_API_KEY'. Alternatively, you can use the api_key parameter.",
"error_code": "missing_api_key",
"errors": [
"Copy the key from Workspace Settings > API & Integrations > API Access in ExhibitDay."
],
"error_params": [
"api_key"
],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 401,
"status": "Unauthorized",
"message": "The API key is not valid. Check that you copied the whole key from Workspace Settings > API & Integrations > API Access, then send it in the Authorization header as 'Bearer YOUR_API_KEY'. Alternatively, you can use the api_key parameter.",
"error_code": "invalid_api_key",
"errors": [
"Check that you sent the whole key. If it was regenerated, use the current key from Workspace Settings > API & Integrations > API Access."
],
"error_params": [
"api_key"
],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 401,
"status": "Unauthorized",
"message": "Access to the ExhibitDay API is not enabled for your workspace. Please contact support@exhibitday.com to enable API Access. Once access is enabled, send your key in the Authorization header as 'Bearer YOUR_API_KEY'.",
"error_code": "api_access_disabled",
"errors": [
"Nothing was read or changed."
],
"error_params": [
"api_key"
],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 404,
"status": "Not Found",
"message": "Event not found. Invalid Event ID: 12345.",
"error_code": "not_found",
"errors": [
"Event not found. Invalid Event ID: 12345."
],
"error_params": [
"id"
],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 409,
"status": "Conflict",
"message": "The invoice attachment or its owning record changed or has conflicting saved information. Retrieve the current record before retrying.",
"error_code": "record_changed",
"errors": [
"The invoice attachment or its owning record changed or has conflicting saved information. Retrieve the current record before retrying."
],
"error_params": [],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 409,
"status": "Conflict",
"message": "The Booth Reservation payment information changed or has an unsupported saved status. Retrieve the current Event before retrying.",
"error_code": "record_changed",
"errors": [
"The Booth Reservation payment information changed or has an unsupported saved status. Retrieve the current Event before retrying."
],
"error_params": [],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 409,
"status": "Conflict",
"message": "The Event objective score changed or could not be read consistently. Retrieve the Event before retrying.",
"error_code": "record_changed",
"errors": [
"The Event objective score changed or could not be read consistently. Retrieve the Event before retrying."
],
"error_params": [],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 409,
"status": "Conflict",
"message": "The record was being changed while it was read, so no record_revision could be issued. Read it again.",
"error_code": "record_changed",
"errors": [
"The record was being changed while it was read, so no record_revision could be issued. Read it again."
],
"error_params": [
"$include_record_revision"
],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 429,
"status": "Too Many Requests",
"message": "Error 429 - Too Many Requests",
"error_code": "rate_limited",
"errors": [
"Error 429 - Too Many Requests"
],
"error_params": [],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 500,
"status": "Unexpected Internal Error",
"message": "An unexpected error occurred. Please try again later.",
"error_code": "internal_error",
"errors": [
"An unexpected error occurred. Please try again later."
],
"error_params": [],
"request_id": "0123456789abcdef0123456789abcdef"
}
{
"status_code": 500,
"status": "Unexpected Internal Error",
"message": "An unexpected error occurred. Please try again later.",
"error_code": "internal_error",
"errors": [
"Check whether your change was saved before trying again."
],
"error_params": [],
"request_id": "0123456789abcdef0123456789abcdef"
}
Things to keep in mind
- A record missing from a list is not proof that it was deleted: lists leave out records on Event tabs that are hidden. Check the Event's tab settings before removing your copy.
- Keep IDs as text or exact integers. The example prints
event_idas text to preserve every digit. - Agree which integration uses each integration field before storing values there.
- Check each match. More than one Event can have the same key.
- The search trims surrounding spaces and may ignore letter case. The example compares the stored key exactly before printing a match.
- If you use another example to create a record and lose the response, check whether the record exists before you try again. See Handle Errors and Retry Failed Requests.
- Track deletions separately. A change-feed cursor does not list deleted records.