Provision a property

ORG_ID="7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11"
# One key per provisioning attempt. Send the same value again only to retry this
# exact request after a timeout, a dropped connection or a 5xx. After a 4xx that
# you have fixed, generate a new key.
IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS -i -X POST "https://api.surfais.com/v1/orgs/$ORG_ID/properties" \
  -H "Authorization: Bearer $SURFAIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "name": "Hotel Aurora",
    "domain": "hotel-aurora.example",
    "geography": "GB",
    "external_ref": "PROP-01342",
    "competitors": [
      { "name": "Grand Meridian", "domain": "grand-meridian.example" },
      { "name": "Harbour Court", "domain": "harbour-court.example" }
    ],
    "markets": ["GB", "IE"]
  }'

import os
import uuid

import requests

BASE_URL = "https://api.surfais.com/v1"
ORG_ID = "7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11"

property_body = {
    "name": "Hotel Aurora",
    "domain": "hotel-aurora.example",
    "geography": "GB",
    "external_ref": "PROP-01342",
    "competitors": [
        {"name": "Grand Meridian", "domain": "grand-meridian.example"},
        {"name": "Harbour Court", "domain": "harbour-court.example"},
    ],
    "markets": ["GB", "IE"],
}

# One key per provisioning attempt. Send the same value again only to retry this
# exact request after a timeout, a dropped connection or a 5xx. After a 4xx that
# you have fixed, generate a new key.
idempotency_key = str(uuid.uuid4())

response = requests.post(
    f"{BASE_URL}/orgs/{ORG_ID}/properties",
    headers={
        "Authorization": f"Bearer {os.environ['SURFAIS_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json=property_body,
    timeout=60,
)
body = response.json()

if response.status_code == 201:
    print("created:", body["data"]["id"])
else:
    error = body["error"]
    # `details` is a list on a validation error and an object on the others.
    details = error.get("details") if isinstance(error.get("details"), dict) else {}

    if "brand_id" in details:
        # Partial success: the brand exists. Do not send this request again.
        print("created, with competitors still to link:", details["brand_id"])
        for competitor in details["competitors"]:
            if competitor["status"] != "applied":
                reason = competitor.get("error", {}).get("code", "not attempted")
                print(" ", competitor["domain"], "-", reason)
    elif "existing_id" in details:
        # brand_exists or external_ref_exists: nothing was created.
        print("already there:", details["existing_id"])
    else:
        raise SystemExit(
            f"{response.status_code} {error['code']}: {error['message']} "
            f"(request {body['request_id']})"
        )

// provision.mjs — run with Node 18 or later: node provision.mjs
import { randomUUID } from "node:crypto";

const BASE_URL = "https://api.surfais.com/v1";
const ORG_ID = "7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11";

const propertyBody = {
  name: "Hotel Aurora",
  domain: "hotel-aurora.example",
  geography: "GB",
  external_ref: "PROP-01342",
  competitors: [
    { name: "Grand Meridian", domain: "grand-meridian.example" },
    { name: "Harbour Court", domain: "harbour-court.example" },
  ],
  markets: ["GB", "IE"],
};

// One key per provisioning attempt. Send the same value again only to retry this
// exact request after a timeout, a dropped connection or a 5xx. After a 4xx that
// you have fixed, generate a new key.
const idempotencyKey = randomUUID();

const response = await fetch(`${BASE_URL}/orgs/${ORG_ID}/properties`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SURFAIS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify(propertyBody),
});
const body = await response.json();

if (response.status === 201) {
  console.log("created:", body.data.id);
} else {
  const { error } = body;
  // `details` is a list on a validation error and an object on the others.
  const details =
    error.details && !Array.isArray(error.details) ? error.details : {};

  if (details.brand_id) {
    // Partial success: the brand exists. Do not send this request again.
    console.log("created, with competitors still to link:", details.brand_id);
    for (const competitor of details.competitors) {
      if (competitor.status !== "applied") {
        const reason = competitor.error?.code ?? "not attempted";
        console.log(" ", competitor.domain, "-", reason);
      }
    }
  } else if (details.existing_id) {
    // brand_exists or external_ref_exists: nothing was created.
    console.log("already there:", details.existing_id);
  } else {
    throw new Error(
      `${response.status} ${error.code}: ${error.message} (request ${body.request_id})`,
    );
  }
}

ORG_ID="7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11"
BRAND_ID="c2a4e8f0-6b1d-4c3a-8e5f-9d7b2a1c4e60"

curl -sS -i -X POST "https://api.surfais.com/v1/orgs/$ORG_ID/brands/$BRAND_ID/competitors" \
  -H "Authorization: Bearer $SURFAIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "Villa Serena", "domain": "villa-serena.example" }'

import os
import uuid

import requests

BASE_URL = "https://api.surfais.com/v1"
ORG_ID = "7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11"
BRAND_ID = "c2a4e8f0-6b1d-4c3a-8e5f-9d7b2a1c4e60"

still_to_link = [
    {"name": "Villa Serena", "domain": "villa-serena.example"},
    {"name": "The Linden", "domain": "the-linden.example"},
]

for competitor in still_to_link:
    response = requests.post(
        f"{BASE_URL}/orgs/{ORG_ID}/brands/{BRAND_ID}/competitors",
        headers={
            "Authorization": f"Bearer {os.environ['SURFAIS_API_KEY']}",
            "Idempotency-Key": str(uuid.uuid4()),
        },
        json=competitor,
        timeout=30,
    )
    body = response.json()

    if response.status_code == 201:
        print("linked:", body["data"]["domain"], "reused" if body["data"]["reused"] else "new")
    elif body["error"]["code"] == "conflict":
        print("already linked:", competitor["domain"])
    elif body["error"]["code"] == "competitor_cap_exceeded":
        # Nothing was linked. Every later competitor would be refused too.
        print("cap reached at:", competitor["domain"])
        break
    else:
        error = body["error"]
        raise SystemExit(f"{response.status_code} {error['code']} (request {body['request_id']})")

// link-competitors.mjs — run with Node 18 or later: node link-competitors.mjs
import { randomUUID } from "node:crypto";

const BASE_URL = "https://api.surfais.com/v1";
const ORG_ID = "7b1e6c1a-3f52-4d0e-9a57-2c8f1e0b4d11";
const BRAND_ID = "c2a4e8f0-6b1d-4c3a-8e5f-9d7b2a1c4e60";

const stillToLink = [
  { name: "Villa Serena", domain: "villa-serena.example" },
  { name: "The Linden", domain: "the-linden.example" },
];

for (const competitor of stillToLink) {
  const response = await fetch(
    `${BASE_URL}/orgs/${ORG_ID}/brands/${BRAND_ID}/competitors`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.SURFAIS_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": randomUUID(),
      },
      body: JSON.stringify(competitor),
    },
  );
  const body = await response.json();

  if (response.status === 201) {
    console.log("linked:", body.data.domain, body.data.reused ? "reused" : "new");
  } else if (body.error.code === "conflict") {
    console.log("already linked:", competitor.domain);
  } else if (body.error.code === "competitor_cap_exceeded") {
    // Nothing was linked. Every later competitor would be refused too.
    console.log("cap reached at:", competitor.domain);
    break;
  } else {
    throw new Error(`${response.status} ${body.error.code} (request ${body.request_id})`);
  }
}