generated: '2026-07-21'
method: searched
source: https://developers.vbout.com/quickstart
docs: https://developers.vbout.com/docs
description: >-
  Cross-cutting request/response semantics of the VBOUT API, captured from the
  developer quickstart and the provider-published OpenAPI 3.1.0
  (info.description) and derived from its operation parameters.
base_url: https://api.vbout.com/1
api_style: >-
  RPC-flavored REST over HTTPS — paths are Resource/Action pairs
  (EmailMarketing/AddContact, SocialMedia/GetPost); reads are GET, writes are
  POST, removals are DELETE. Responses available in JSON or XML (.json/.xml
  extension on the endpoint, e.g. /1/app/me.json).

authentication:
  scheme: API key
  parameter: key
  detail: authentication/vbout-authentication.yml
  notes: >-
    User Key or Application Key from Account Settings, passed as the `key`
    parameter (JSON body in the quickstart example, query parameter in the
    legacy console). OAuth exists for third-party apps via VBOUT Connect
    (app.vbout.com/Authorize) but has no public scope catalog.

idempotency:
  supported: false
  notes: >-
    No idempotency-key header or replay-safety contract is documented anywhere
    on the developer portal or in the OpenAPI (checked 2026-07-21). Writes are
    plain POSTs; only EmailMarketing/SyncContact ("add or update") offers an
    upsert-style alternative to AddContact.

pagination:
  style: page
  request_params:
    page: Set which page you want to get (number).
    limit: Set your record limit number per page (number).
  applies_to:
    - EmailMarketing/Campaigns
    - SocialMedia/Calendar
  notes: >-
    Page/limit parameters are declared only on the campaign and social-calendar
    list operations; other list endpoints (GetContacts, GetLists) take only
    filter ids. Derived from openapi/vbout-openapi-original.json.

field_expansion:
  supported: false
  notes: No expand/sparse-fieldset mechanism documented.

metadata:
  supported: false
  notes: >-
    No free-form metadata object on API resources; contact records instead
    carry list-defined custom fields (the `fields` parameter on
    AddContact/EditContact/SyncContact).

request_tracing:
  supported: false
  notes: No request-id header documented.

versioning:
  scheme: uri-path
  current: '1.0'
  detail: lifecycle/vbout-lifecycle.yml

error_envelope:
  shape: |-
    {"response": {"header": {"status": "ok|error", "dataType": "...", "limit": ...},
                  "data": {"errorCode": ..., "errorMessage": "..."}}}
  detail: errors/vbout-problem-types.yml

rate_limiting:
  limit: 15 requests / 1 second
  exceeded_status: 429
  signaling: rate-limit JSON object on every response + x-rate-limit-* headers
  detail: rate-limits/vbout-rate-limits.yml

# --- appended 2026-08-13 (enrichment round 2) ---

undocumented_surfaces:
  checked: '2026-08-13'
  note: >-
    A REST family that VBOUT documents in HTML but ships in NEITHER published
    OpenAPI document. Both specs in this repo were re-parsed on 2026-08-13:
    openapi/_original/vbout-openapi-original.json has 71 paths and
    openapi/_original/vbout-plugin-openapi-original.yaml has 37, and grepping
    both for "commerce" returns zero matches. The endpoints below are read
    verbatim from the fully-specified parameter tables at
    https://developers.vbout.com/ecommerceIntegration. They are recorded here,
    not synthesized into a spec — API Evangelist does not author contracts on a
    provider's behalf. This is the single largest contract gap on the VBOUT
    surface and the correct thing for VBOUT to close.
  surfaces:
    - name: Ecommerce API
      base_url: https://api.vbout.com/1
      docs: https://developers.vbout.com/ecommerceIntegration
      in_openapi: false
      auth: 'key (API key) + domain (verified ecommerce domain identifier, VBT-XXXXXX-XXXXX)'
      method: POST
      operation_count: 14
      operations:
        - {path: Ecommerce/CreateCart, group: cart}
        - {path: Ecommerce/UpdateCart, group: cart}
        - {path: Ecommerce/EmptyCart, group: cart}
        - {path: Ecommerce/RemoveCart, group: cart}
        - {path: Ecommerce/AddCartItem, group: cart}
        - {path: Ecommerce/RemoveCartItem, group: cart}
        - {path: Ecommerce/CreateOrder, group: order}
        - {path: Ecommerce/UpdateOrder, group: order}
        - {path: Ecommerce/CreateOrderTransaction, group: order}
        - {path: Ecommerce/AddProductSearch, group: intent}
        - {path: Ecommerce/AddProductView, group: intent}
        - {path: Ecommerce/AddCategoryView, group: intent}
        - {path: Ecommerce/UpsertCustomer, group: customer}
        - {path: Ecommerce/UpdateCustomerPreferences, group: customer}
      client_side_twin: components/vbout-components.yml
      client_side_note: >-
        Every one of these has a browser-side counterpart in the VboutEcommerce
        tracker (store.cart.send, store.order.send, store.product.view …), so
        the same capability ships twice — once as an untyped REST family and
        once as an untyped JS command queue. Neither is machine-readable.
      status: 'Version 1.0 (BETA), per the page header'

events:
  webhooks: asyncapi/vbout-webhooks.yml
  asyncapi_published: false
  note: >-
    Inbound webhook receiver + automation webhook trigger + an outbound
    "Sync to Third Party" automation action (GET or POST to a customer URL).
    No AsyncAPI document and no published payload schemas.

testing:
  detail: sandbox/vbout-sandbox.yml
  sandbox: false
  console: https://developers.vbout.com/console
  note: 'Live Swagger UI console against production; no test mode, no test keys, no fixtures.'

plans:
  detail: plans/vbout-plans-pricing.yml
  api_access_gated_to: Professional
  note: >-
    API access is not sold below the Professional tier, so the 14-day free
    trial cannot be used to evaluate the API.