BrandWell Intent Data Integration: API Questions and Workflow Checklist

The short answer: choose the interface after defining the operational decision

An API is justified when it removes a recurring handoff without removing accountability. Good candidates include receiving eligible signal records into a client-specific review queue, enriching an approved record, synchronizing a disposition, preparing an advertising audience, or updating a reporting ledger. The interface should support a known decision with an owner, latency target, failure path, and audit requirement.

An API is a poor choice when the agency has one low-volume client, no monitoring owner, changing qualification rules, or a workflow that still needs human interpretation. A scheduled file, native connector, webhook, or branded report can be safer and cheaper. “Real time” is not inherently better; it can simply move noise and mistakes faster.

Before choosing an interface, write this sentence:

When [eligible event] occurs for [client tenant], send [minimum fields] to [destination] within [time], unless [suppression or approval rule], and record [delivery and outcome evidence].

If the team cannot fill every bracket, it is not ready to automate.

Public documentation boundary: what is and is not verified

Evaluate MarketPulse with a relevant topic and defined ICP. Review available records and permitted uses before preparing a next action through configured tools. A usable app workflow does not establish a production API contract.

The table below is a verification-state matrix, not a feature claim.

Swipe the table to see all columns.

The correct response to an unverified cell is not to infer an endpoint from the underlying provider. Ask BrandWell for the current intent-specific contract, or select a documented non-API delivery method.

Decide among API, webhook, batch file, native connector, and manual report

Swipe the table to see all columns.

Required authentication and key-management review

Because current BrandWell intent-data authentication is not publicly verified, treat the following as procurement requirements rather than documented behavior.

1. Tenant and environment registration. Each agency and client environment should have an explicit identifier, allowed use, callback locations, and owner.
2. Least-privilege credential issue. Credentials should be scoped by tenant, operation, environment, and destination. A development key should not read production client data.
3. Secret storage. Store keys in a managed secrets system, never in agent prompts, browser text fields, source control, spreadsheets, or client reports.
4. Request protection. Require TLS; for webhooks, require a documented signature, timestamp tolerance, replay protection, and verification procedure.
5. Authorization enforcement. The server must enforce tenant and record-level access. A client-supplied tenant ID alone is not authorization.
6. Rotation and revocation. Document overlapping rotation, emergency revocation, staff offboarding, and how in-flight jobs behave.
7. Auditability. Record credential identifier, request ID, tenant, operation, time, result, and safe error context without logging secrets or unnecessary personal data.

NIST SP 800-228, updated March 2026, addresses risks and protection controls across API development and runtime. It is a general design reference, not evidence of BrandWell’s controls or certification.

Schema, keys, limits, retries, and monitoring checklist

A usable contract should answer the following before the first production request:

• Identifiers: Which ID is globally unique? Which is tenant-scoped? Can a signal, person, company, report, or delivery be corrected without changing identity?
• Timestamps: Are observed, received, enriched, qualified, delivered, and updated times separate? Which time zone and precision apply?
• Field semantics: Which values are observed, inferred, resolved, enriched, validated, or client-supplied? What does null mean?
• Versioning: Is the schema version in the path, header, or payload? How are deprecations announced and tested?
• Pagination and ordering: Are cursors stable? Can late events appear? Are webhooks at-least-once, and can they arrive out of order?
• Rate and usage limits: Which unit is metered? Are test, retry, duplicate, failed, or suppressed records charged?
• Idempotency: Which operations can safely be retried, and what key prevents duplicate side effects? HTTP semantics help, but the vendor must define application behavior. RFC 9110 explains why retries depend on whether a method and operation are idempotent.
• Errors: Are validation, permission, throttling, dependency, timeout, and partial-result failures distinguishable and machine-readable?
• Observability: Which request IDs, status pages, delivery logs, latency metrics, and incident notices are available?
• Ownership: Who responds at the agency, BrandWell, underlying infrastructure, destination, and client for each failure class?

Illustrative evaluation payload – not a BrandWell API schema

Use a neutral payload like the following to test whether vendor documentation preserves the business meaning you need. Do not send this to a BrandWell endpoint or implement against it. Replace it only with a current, versioned contract supplied by BrandWell.

{
  "schema_version": "vendor_documented_value",
  "event_id": "stable_unique_identifier",
  "tenant_id": "agency_client_boundary",
  "observed_at": "source_event_time",
  "signal": {
    "type": "topic_or_first_party_event",
    "topic_or_behavior": "documented_definition",
    "source_class": "observed_or_inferred",
    "recency_window": "documented_window"
  },
  "identity": {
    "level": "company_person_or_unresolved",
    "status": "documented_match_status",
    "confidence_or_method": "if_documented"
  },
  "qualification": {
    "rule_version": "agency_rule_set",
    "decision": "accepted_rejected_or_review",
    "reason_codes": []
  },
  "delivery": {
    "destination": "approved_system",
    "approval_status": "required_state",
    "idempotency_key": "stable_side_effect_key"
  }
}

The important feature is not the field names. It is the separation of source observation, identity, agency inference, approval, and delivery. A production contract should never turn these into one undifferentiated “buyer” object.

Error model the buyer should require

This is a required behavior matrix, not a claim about current BrandWell response codes.

Swipe the table to see all columns.

For every automated action, decide whether to retry, quarantine, notify, or require a person. “Log the error” is not a recovery plan.

Documentation, SDK, sample, and testing requirements

Ask BrandWell for an intent-specific OpenAPI or equivalent machine-readable contract, human guide, change log, authentication guide, field dictionary, sample requests and responses, webhook verification example, usage and rate table, status page, support process, sandbox, test data, and deprecation policy. If an SDK exists, inspect its license, supported language versions, release cadence, dependency risk, and whether it exposes raw request IDs and errors.

A sandbox should support successful match, no match, invalid input, duplicate, excluded tenant, rate limit, delayed job, retry, correction, deletion, and credential rotation. Synthetic records are suitable for functional testing. A governed client sample is still required to test real coverage and field quality.

Use AIMEE through configured tools for a bounded task, such as preparing a field dictionary or sourced integration brief. Confirm actual permissions and supported actions; do not supply secrets in a prompt or infer an undocumented connector.

A safe integration workflow from discovery to production

Begin with interface discovery, not code. First, inventory the client decision, fields, destinations, timing, data rights, and failure tolerance. Second, obtain the current intent-specific contract and mark every requested capability as documented, unavailable, or unresolved. Third, conduct a threat and privacy review that includes tenant authorization, secret handling, logging, retention, deletion, and downstream access. Fourth, create a field-level mapping with sample values, nulls, source classes, and reversible transformations.

Fifth, test synthetic records across the full error matrix. Sixth, run an appropriately governed client sample and reconcile source counts, accepted rows, rejects, duplicates, delivery status, and destination counts. Seventh, obtain written client acceptance for fields, cadence, qualification, approval, and fallback. Eighth, launch with a low usage ceiling and a named on-call owner. Ninth, compare daily totals across the BrandWell delivery record, the agency ledger, and the destination. Tenth, hold a post-launch review before enabling a second client or automated action.

The output of each step should be an artifact: decision statement, evidence matrix, review record, mapping, test report, acceptance sign-off, runbook, reconciliation, and expansion decision. This creates a defensible chain when a record is questioned or an invoice does not reconcile.

Cost and packaging questions

For any proposed API contract, confirm available operations, metering, test allowance, workspace scope, delivery, backfill, reprocessing, support and implementation. Model engineering, monitoring, incidents, destinations, storage and review separately. Do not infer API access or topic exclusivity from a plan’s export allowance.

An agency’s implementation service is separate from product access. Define QA, monitoring, reporting, client responsibilities and permissions in the service contract. Do not describe BrandWell billing as wholesale or promise data resale, exclusivity or unlimited use without the applicable rights.

Metrics for API and business fitness

Measure the interface before measuring revenue:

• successful and failed requests by class;
• p50/p95 delivery latency using documented timestamps;
• webhook duplicate and out-of-order rates;
• retry recovery and dead-letter backlog;
• schema errors and version drift;
• usage versus contracted capacity by client;
• matched, unmatched, stale, duplicate, rejected, and corrected records;
• activation success and reversal rate;
• disposition completeness;
• cost per accepted candidate and per successful delivery;
• downstream opportunity outcomes with baseline and attribution caveats.

An API is operationally successful when it delivers the right meaning to the right tenant with recoverable failure. It is commercially useful only when the client can act and the agency can operate the service at a sustainable margin.

Multi-client operating model

Give every client an isolated tenant, credentials or destination authorization, configuration version, suppression set, usage ledger, evidence ledger, and incident trail. Never encode client identity only in a mutable spreadsheet column. Keep development and production separate. Test one client before enabling a shared workflow template.

Use a promotion path: draft mapping → synthetic test → governed sample → client acceptance → limited production → monitored expansion. Require approval for new topics, fields, destinations, automated person-level actions, and higher usage bands. A shared integration can reuse code without sharing data or authority.

Start with an app-based topic review and a manual field map unless a current contract explicitly supports the required integration test. That can assess available fields and operating effort; it does not establish branded delivery or native API support.

Buyer go/no-go checklist

Proceed only if all answers are documented:

• [ ] The exact intent-specific API or alternate interface is currently available in the purchased scope.
• [ ] Authentication, tenant authorization, credential rotation, and audit behavior are documented.
• [ ] Schemas distinguish observation, inference, identity, enrichment, agency decisions, and outcomes.
• [ ] Limits, metering, retries, idempotency, webhooks, errors, versions, and deprecations are testable.
• [ ] Data rights cover the agency, named client use, destinations, retention, and deletion.
• [ ] A sandbox and governed acceptance sample produce explainable pass and fail results.
• [ ] Monitoring, incident ownership, support escalation, and a manual fallback exist.
• [ ] Pricing includes platform, usage, engineering, storage, destinations, support, and variance.
• [ ] The client has an action owner and will return dispositions.
• [ ] Legal, privacy, security, product, and claim review are complete.

Frequently asked questions

What problems should BrandWell intent-data APIs solve?

They should remove repeatable handoffs for eligible signal delivery, enrichment, client-specific routing, activation, or outcome return. They should not automate an undefined service or substitute for approval.

What authentication, schema, limit, retry, and monitoring details are required?

Require tenant-scoped authentication, a versioned field contract, documented metering and limits, idempotent recovery, machine-readable errors, request IDs, status and incident evidence, rotation, and revocation.

Which docs and tools should a buyer request?

Request machine-readable and human documentation, examples, change logs, sandbox, synthetic fixtures, webhook-verification code, SDK details, status information, support contacts, and monitors.

When is an API better than a webhook, batch, connector, or report?

Use an API for controlled on-demand interactions, a webhook for event delivery, a batch for reconcilable volume, a connector for a supported destination, and a manual report while rules remain fluid.

What does API access cost?

No separate public BrandWell intent-API price was established in the reviewed evidence. Confirm inclusion, units, tests, retries, clients, backfills, implementation, and support in the written quote.

Which metrics matter?

Track reliability, latency, duplicates, retries, schema drift, usage, data dispositions, activation, evidence completeness, cost per accepted candidate, and downstream outcomes with a baseline.

Who is a good fit?

Agencies with multiple repeatable client workflows, technical ownership, tenant isolation, monitoring, and meaningful volume. A small or changing workflow is usually better served by reports or batch delivery.

What signal and identity requirements matter?

Preserve source class, observation time, topic or behavior, identity level and status, enrichment provenance, qualification version, approval, destination, and outcome. Never merge inference with fact.

What are the biggest risks?

The largest risks are building against unverified documentation, broken tenant authorization, leaked secrets, duplicate side effects, silent schema changes, unlawful use, unreliable retries, and automation without client adoption.

How should an agency operate the API across clients?

Use isolated tenants, least-privilege credentials, per-client configuration and usage ledgers, acceptance tests, approval gates, monitored queues, correction and deletion workflows, and a documented manual fallback.