{
  "openapi": "3.1.0",
  "info": {
    "title": "Certiv Public Forms API",
    "summary": "Public lead-capture endpoints for the certiv.ai marketing site.",
    "description": "Covers the lead-capture surface used by the public website: requesting a product demo and subscribing to the product newsletter. This spec intentionally does NOT describe Certiv's authenticated product API (app.certiv.ai / api.certiv.ai), which is private and requires an account. For Certiv positioning and product context, see https://certiv.ai/llms.txt and https://certiv.ai/AGENTS.md.\n\nVersioning and deprecation: this API is versioned. The current and only version is v1 (see the version field below: 1.0.0). Clients may pin a version with the optional Certiv-Api-Version request header; when it is omitted the current version is used. The header is informational today because only v1 exists, so it does not change behavior and unknown or omitted values are accepted. Deprecation policy: breaking changes ship under a new major version (v2, v3, and so on). A deprecated version is announced at least 90 days before removal, via the Deprecation and Sunset response headers (RFC 8594) and an update to this document. Additive, non-breaking changes may ship without a version bump.",
    "version": "1.0.0",
    "termsOfService": "https://certiv.ai/terms/",
    "contact": {
      "name": "Certiv",
      "url": "https://certiv.ai/",
      "email": "hello@certiv.ai"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://certiv.ai/terms/"
    }
  },
  "servers": [
    {
      "url": "https://forms.certiv.ai",
      "description": "Production forms API"
    }
  ],
  "externalDocs": {
    "description": "Certiv agent briefing (llms.txt)",
    "url": "https://certiv.ai/llms.txt"
  },
  "tags": [
    {
      "name": "Lead capture",
      "description": "Public endpoints for requesting a demo or subscribing to the newsletter."
    }
  ],
  "security": [],
  "paths": {
    "/demo-request": {
      "post": {
        "operationId": "createDemoRequest",
        "tags": ["Lead capture"],
        "summary": "Request a product demo",
        "description": "Submit a request for a Certiv product demo. Mirrors the public demo form at https://certiv.ai/demo/. No authentication is required.",
        "parameters": [{ "$ref": "#/components/parameters/ApiVersionHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DemoRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Demo request accepted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "examples": {
                  "accepted": { "value": { "message": "OK" } }
                }
              }
            }
          },
          "409": {
            "description": "This email is already registered. Treated as success by the website.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "examples": {
                  "duplicate": { "value": { "message": "Already registered" } }
                }
              }
            }
          },
          "400": {
            "description": "Validation error (missing or malformed fields).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "examples": {
                  "invalidEmail": { "value": { "error": "Invalid email" } },
                  "missingFields": {
                    "value": { "error": "Missing required fields" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/newsletter": {
      "post": {
        "operationId": "subscribeNewsletter",
        "tags": ["Lead capture"],
        "summary": "Subscribe to the newsletter",
        "description": "Add an email address to the Certiv product newsletter. No authentication is required.",
        "parameters": [{ "$ref": "#/components/parameters/ApiVersionHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewsletterRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email added to the newsletter.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "examples": {
                  "added": { "value": { "message": "OK" } }
                }
              }
            }
          },
          "409": {
            "description": "This email is already subscribed to the newsletter. Treated as success by the website.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "examples": {
                  "duplicate": { "value": { "message": "Already registered" } }
                }
              }
            }
          },
          "400": {
            "description": "Validation error (missing or malformed email).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "examples": {
                  "invalidEmail": { "value": { "error": "Invalid email" } }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ApiVersionHeader": {
        "name": "Certiv-Api-Version",
        "in": "header",
        "required": false,
        "description": "Optional API version selector. Accepts a semantic version (e.g. \"1.0.0\") or a major-version alias (\"v1\"). When omitted, the current version is used. Reserved for forward compatibility: only v1 exists today, so this header is informational and does not change behavior.",
        "schema": {
          "type": "string",
          "default": "v1",
          "examples": ["v1", "1.0.0"]
        }
      }
    },
    "schemas": {
      "DemoRequest": {
        "type": "object",
        "required": ["first_name", "last_name", "email", "company", "linkedin"],
        "properties": {
          "first_name": {
            "type": "string",
            "minLength": 1,
            "description": "Requester's first name.",
            "examples": ["Jane"]
          },
          "last_name": {
            "type": "string",
            "minLength": 1,
            "description": "Requester's last name.",
            "examples": ["Doe"]
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Work email address.",
            "examples": ["jane@company.com"]
          },
          "company": {
            "type": "string",
            "minLength": 1,
            "description": "Company name.",
            "examples": ["Acme Corp"]
          },
          "linkedin": {
            "type": "string",
            "description": "LinkedIn profile URL.",
            "examples": ["https://linkedin.com/in/janedoe"]
          },
          "phone": {
            "type": "string",
            "description": "Optional phone number.",
            "examples": ["+1 555 123 4567"]
          },
          "source": {
            "type": "string",
            "description": "Optional attribution source for the submission.",
            "examples": ["demo-page"]
          },
          "posthog_distinct_id": {
            "type": "string",
            "description": "Optional PostHog analytics distinct id, sent by the website to link the submission to an analytics session."
          }
        }
      },
      "NewsletterRequest": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Work email address.",
            "examples": ["jane@company.com"]
          },
          "source": {
            "type": "string",
            "description": "Optional attribution source for the submission.",
            "examples": ["newsletter"]
          },
          "posthog_distinct_id": {
            "type": "string",
            "description": "Optional PostHog analytics distinct id, sent by the website to link the submission to an analytics session."
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "required": ["message"],
        "description": "Success envelope returned on a 200 (accepted) or 409 (already registered, treated as success) response.",
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable status. \"OK\" for a new submission, \"Already registered\" when the email already exists.",
            "examples": ["OK", "Already registered"]
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "description": "Error envelope returned on a 400 validation failure.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable validation error message.",
            "examples": ["Invalid email", "Missing required fields"]
          }
        }
      }
    }
  }
}