Write the integration spec before anyone writes code, and keep it to one page. When a vendor’s API documentation is thin, the productive move is to treat that vendor as a black box: state exactly what you will send, how you will authenticate, what counts as success, and what happens when a call fails, then prove each assumption with a controlled set of test calls and real logging. That order sends engineering hours at known unknowns instead of guesswork. This is for the marketing operations manager at a B2B services or software company whose lead form works, whose vendor exposes an API, and whose documentation is a page of sample requests with no error reference behind it.
The one page spec you write before coding
A minimum viable integration spec is a decision record, not an architecture document. A developer should be able to build against it, and a marketer should be able to check it. Every line gets a named answer, even if the answer is “unknown, test it on Tuesday”.
- Payload contract: endpoint, method, exact field names and types, required versus optional fields, length limits, and accepted formats for dates and phone numbers.
- Lead identity: the field that makes a lead unique, usually email plus form name, and whether the vendor dedupes on it.
- Authentication: key or OAuth flow, where the secret is stored, who can rotate it, and which person is accountable for it.
- Environments: test and production base addresses, and the rule that production stays untouched until the test plan passes.
- Success criteria: the status code, the response shape, and the returned identifier that proves a record exists rather than a friendly message that proves nothing.
- Failure behavior: what the site does on timeout, rejection, server error and rate limit, and where the lead waits so it is not lost.
- Idempotency: the key sent with every request and what the vendor does with a repeat.
- Retries: attempt count, interval, backoff ceiling, and which errors are worth retrying at all.
- Logging: correlation ID, timestamp, status, vendor reference, latency, and the fields you redact.
- Ownership: who reads the failure queue, how often, and the date this page gets revised.
The lead contract is where reporting breaks first
Give the payload the most care, because every downstream report depends on it. Decide which fields are required, which are optional, and how values are normalized before they leave your site: casing on email, country and state codes, date format, phone digits, and how empty optional fields are represented. The form itself is half of that contract. Field names, hidden values such as page source or campaign, and the format your form really submits are set during web design and development, so capture a real submitted payload rather than a mock before you write anything down.
Add a version number to both the payload and the spec. When a field changes, the version changes, and reports can tell which shape they are reading. Without it, a renamed field quietly empties a column in your lead reporting a quarter later and nobody can date the change.
Authentication and the sandbox that may not exist
Assume there is no sandbox until someone shows you one. If there is none, ask the vendor to issue a separate credential for testing and agree on a tag such as a test source value so the test records can be filtered out of the pipeline and deleted afterwards. Write down whether the API requires an IP allowlist, because that decides whether calls leave from a fixed server or from your website host, and it changes the build. Keep the credential in a password manager with one named owner and a rotation date, never pasted into a shared document or a ticket.
Design for the vendor being unavailable
Send an idempotency key on every request so a retry cannot create a second lead. Retry only on timeouts, rate limits and server errors, with a short interval, a cap and some randomness so a backlog does not hit the vendor all at once. Set the request timeout below the point where your form starts to feel broken to the visitor. When a call fails, hold the payload in a queue or a fallback notification that a person can act on, and keep a manual replay path. Deduping on your side protects reporting even if the vendor promises nothing.
The black box test plan
Ten calls tell you most of what the documentation left out. Run them in this order, keep every request and response, and stop if two results contradict the spec.
| Test case | Expected response | Log fields | Fallback or rollback |
|---|---|---|---|
| Valid lead, all required fields | Success status plus a record identifier | Correlation ID, status, vendor ID, latency | Keep the test record tagged for cleanup |
| Valid lead, optional fields empty | Success, defaults applied | Payload sent, full response body | Check the stored record for defaults |
| Same lead submitted twice | Success or conflict, one record | Idempotency key, both responses | Confirm a single record exists |
| Expired or wrong credential | Unauthorized status | Status, masked key prefix, timestamp | Rotate secret, queue the lead |
| Malformed field such as a date | Rejection naming the field | Payload copy, error body | Fix the mapping before build |
| Vendor timeout or server error | No response inside the timeout | Attempt count, latency, timestamps | Hold in queue, retry with backoff |
What a black box spec cannot protect you from
Undocumented rate limits can still appear once real traffic arrives, so plan a pause and resume behavior rather than discovering it in a launch week. Hidden required fields often surface as production rejections, which is why one test call should mimic a full real submission, including hidden form values. Watch for a success status carrying an error message inside the body, and for one generic error code reused for five different problems; both make automated handling unreliable.
Privacy limits apply to your logging. Lead records hold personal data, so decide what may be stored, where, for how long, and who can read it before you turn on verbose request logging in a shared tool. Expect to spend a few hours of engineering and marketing time on the workshop and the test calls, and expect the page to be revised once reality answers a listed unknown.
Stop and choose another method if the vendor requires a browser redirect for every user, has no test credential and no error reference, and will not answer questions. A hosted form embed, a scheduled file exchange or a middleware service may be the cheaper route.
Run one meeting and ten test calls
Book an hour with the person who owns the form, the person who holds the credentials, one engineer and the person who will read the failures. Bring the real payload and the vendor documentation, fill the one page live, and mark every gap as an unknown to test. Then run the ten calls and record the results against the table. You finish with either a spec the team can build from or a clear reason to change approach, and no one has committed build time to guesswork.
If it would help, we can go through the lead flow as it runs now and put together a minimum viable integration spec and test plan your team can build against, or hand to any developer. That review is one of the integration projects Wilton Web works on, and there is no obligation to use us for the build.
