What we learned mapping Beeline’s API

We reviewed Beeline’s published technical specifications to understand how a composer decision reference could be represented in Beeline. That research tells us how an adapter should be built. It does not, by itself, prove that a production customer integration is live, and this article is careful about the difference: mapping an API is not the same as having a live integration.

Start from the specifications, not the marketing site

Beeline publishes its API specifications through its developer portal, one per API product. We took copies of all of them into our repository, with a record of where each came from, and wrote the mapping against them rather than against the overview pages. That is the difference between saying “Beeline has a requisition API” and saying that a contingent request is created with POST /sites/{clientSiteId}/business-intake-requests, that the body carries an externalId that can hold the decision reference, and that tenant-specific fields are written afterwards with a separate call.

Then attack your own page

A mapping written from specifications can still be wrong, so we reviewed our own Beeline page against the specifications, looking for anything an integration engineer at Beeline would read and stop trusting us over. Four findings, all fixed:

1. The page presented Beeline’s Supplemental Data Service as if it could carry the decision reference. It cannot; it is a report-based read service. The externalId on the intake request is the carrier.
2. The statement-of-work flow was described as creatable through the API. Beeline’s SOW specification exposes no create operation, so the page now says so.
3. The base URL was written as a host that does not resolve. The specifications give client.beeline.com/api, with an EU-region variant.
4. The mapping table listed fields that were plausible rather than real. It was rebuilt from the actual create schema with its actual required fields.

Each of those would have cost credibility in the first technical conversation. Finding them on our own side first is the point of the exercise.

What the specifications say about the hard parts

Authentication: Beeline documents OAuth 2.0 client credentials with an audience per API product, day-long tokens, and permissions granted per product. A 403 means a missing permission for the site, not a wrong password, and an adapter should say so in its errors.

Duplicates: Beeline documents no idempotency key on its create call, but it does let a caller filter on externalId. So a careful adapter would search for an existing record carrying the decision reference before creating one. The duplicates article covers why that works.

Events: Beeline documents webhooks with a validation handshake, and an event-history endpoint that lets a subscriber recover events missed during an outage. Both matter for any future reconciliation design.

Tested offline, against a stand-in

To check the research holds together, we built a stand-in Beeline: a local server that behaves the way the specifications say Beeline behaves, including the token audiences, the externalId filter and the webhook handshake. An adapter runs against it over real HTTP in our automated tests. What that proves is that our reading of the specifications is coherent and implementable. What it has not done is talk to an actual Beeline tenant, and until it has, no page of ours will say otherwise.

What “specification mapped” means

On our coverage pages, a mapped status means researched and mapped against the vendor’s specification: every field in the mapping table exists in a vendored specification with its real name and its real required flag, the authentication description matches the vendor’s, the base URL resolves, and the things the API cannot do are stated. It does not mean production tested with a customer. When that day comes, the changelog will say so in those words.