A vendor's payload and Guidewire's structure never match field for field. Someone has to map one to the other, and where that mapping lives decides who maintains it, who sees the errors, and what breaks when either side changes.
Most teams decide by default. The vendor builds the mapping because the vendor owns the data. That default holds for one carrier and one stable payload, and it strains as carriers, lines of business, and schema changes multiply.
This article defines the two placements, compares them on the criteria that matter, and gives a four-question test you can run before you build.
What is the difference between vendor-side and gateway-side mapping?
Vendor-side mapping converts data into the target structure before it leaves the sender, while gateway-side mapping converts it at a mediation layer between sender and target.
The placement changes who writes the mapping and where its failures show up. It does not change the work itself.
Vendor-side mapping
The sender holds the map. Its engineers read the target structure, convert each field in their own code, and send a payload already shaped for Guidewire.
The target sees a clean request, and the sender owns every conversion rule behind it.
Gateway-side mapping
The sender keeps its own payload shape. A mediation layer holds the map and converts the payload into the target structure.
This is the Anti-Corruption Layer pattern from Microsoft's Azure Architecture Center. Communication between the sender and the layer uses the sender's data model, and calls from the layer to the target conform to the target's data model.
What both placements share
Both placements need the same mapping logic. Payload mapping matches each field in a sender's data to the field Guidewire expects, so a submission or claim lands in the right place on the first send.
Moving the logic from one component to another does not shrink it. It changes who carries it.
What does Guidewire do with a payload that does not match?
Guidewire's Cloud API rejects a payload that contains a property its schema does not define. Whoever owns the mapping owns that rejection.
Guidewire's Cloud API documentation (BillingCenter guide, release 202507) states that rejection is the default behavior.
Unknown properties are rejected by default
A Cloud API call can include a property that is not defined in the associated schema. By default, Cloud API rejects it.
A misspelled field name, an extra field, or a field copied from the source payload without a match all fail the call. For a vendor-side map, that means every output field must exist in the target schema.
The header changes the behavior
The GW-UnknownPropertyHandling header accepts three values. Setting it to reject returns a validation error that names the unknown properties.
Setting it to log writes a service-side info message and processes the call while ignoring the unknown properties. Setting it to ignore does the same with no message and no validation error.
Why ignoring hides mapping mistakes
An ignored property does not land in Guidewire, and nothing reports the loss. A mapping mistake that would have failed loudly now succeeds quietly.
During build, leave the default in place so every mapping gap surfaces as an error.
How do the two placements compare?
Each placement trades one cost for another. The table sets them side by side on six criteria.
Criterion | Vendor-side mapping | Gateway-side mapping |
|---|---|---|
Where the map lives | In the sender's code | In a layer between sender and target |
Who maintains it | The sender's engineers | Whoever runs the layer, with sender input |
Added latency | None beyond the sender's own processing | One translation hop on every call |
Extra service to run | None | A service to manage, scale, and monitor |
Several carriers | One mapping per carrier inside the sender | One mapping per carrier held in the layer |
Where errors appear | In the sender's logs, before or after the send | At the layer boundary, where validation runs |
The cost of the layer
The layer adds latency to calls between the two systems. It also adds a service that must be managed, maintained, and scaled.
Because the layer can become a single point of failure, plan for resilience, such as retries and circuit breakers. Microsoft's guidance says the pattern is not suitable when the two systems have no significant semantic differences, since the layer then has little to translate.
The cost of owning the mapping at the vendor
The sender's engineers must learn the Guidewire structure and keep current with it. Every change to the target becomes a change to the sender's code and its release schedule.
A vendor that serves several carriers can face a different target at each one. The map then multiplies inside the sender, and each copy needs its own testing.
Where the errors land
With vendor-side mapping, a rejected request lands in the sender's own logs. The sender sees the failure first and can fix it first.
With gateway-side mapping, translation failures appear at the layer. The layer needs structured logging and correlation IDs so a failed translation can be traced back to the request that caused it.
When does each placement fit?
Four questions decide the placement. Answer them for your own situation before you write any mapping code.
How many targets does the sender serve: one carrier or several?
How often does the target structure change?
Who on the sender's team knows the Guidewire structure well enough to keep a map current?
Where do you want mapping errors to appear: inside the sender or at a boundary?
Vendor-side fits when
The sender serves one carrier, the target structure is stable, and the sender's engineers already know Guidewire. In that case the layer adds latency and a service to run without removing real work.
It also fits when the sender needs the lowest possible latency on every call.
Gateway-side fits when
The sender serves several carriers, the target structure changes, or the sender's engineers would rather spend their time on the sender's own product. Two systems with different semantics that must still communicate is the case the layer exists for.
Putting input validation at the layer also gives you one place to enforce it. Microsoft's guidance recommends validation and sanitization at this boundary.
What belongs in neither
Keep business rules out of the mapping, whichever side holds it. A map that decides whether to bind a risk has stopped being a map.
Translation logic changes when schemas change. Business rules change when underwriting appetite changes, and the two should not share a release.
What does a sound mapping practice look like?
The practice is the same in either placement. Six steps carry a mapping from first draft to production.
Pull the target schema for the line of business and the transaction type.
Match each source field to a target field, and list the source fields with no match.
Decide what happens to each unmatched field: map it elsewhere, drop it on purpose, or ask the source for more data.
Run the map with unknown-property handling left at its default so gaps fail loudly.
Have a person who knows the source data review the map before it ships.
Re-run the map whenever the target structure changes.
Treat unmatched fields as decisions
An unmatched source field is a question, not an error. Someone decides whether the field matters to the underwriter or adjuster, and the answer goes in the record.
Dropping a field on purpose is a valid choice. Dropping it by accident is the failure the ignore setting hides.
Review before deployment
A person should confirm every mapping before data moves. An unreviewed map moves wrong data as readily as it moves right data.
The reviewer needs to know the source data, not the Guidewire internals. Source knowledge is what catches a field that looks right and means something else.
Trace every failure
Plan for observability from the start. Structured logging and correlation IDs let you diagnose a translation failure without guessing which request caused it.
Log each request, each response, and each error against the same identifier, so a rejected send can be followed from sender to target.
How InsOps Helps
InsOps builds an insurance-trained AI that assists with moving submission data into Guidewire. LiLa, our insurance-trained LLM, drafts the mapping from your payload to the Guidewire structure, and your administrator reviews, edits, and confirms it before any data moves.
The InsOps Integration Gateway gives vendors, MGAs, TPAs, and brokers a prebuilt route into Guidewire. Your team brings a payload and configures it in a self-service portal, so you keep your native shape and skip building a connector. A vendor that serves several carriers keeps tenant-specific mappings.
The gateway flags incomplete data before it reaches an underwriter or adjuster. It also alerts you when Guidewire adds a mandatory field, while the flow keeps running, and a dashboard records every request, response, and error.
The gateway runs inside your own environment, so PII and PHI stay in controlled infrastructure. InsOps is a Guidewire technology partner with prebuilt connectors to Guidewire's core products.
If you are evaluating how to exchange submission data with Guidewire without a custom connector build, contact us to talk through what this looks like for your operation.
Frequently Asked Questions
What is vendor-side mapping?
Vendor-side mapping converts a sender's data into the target structure inside the sender's own code. The sender then sends a payload already shaped for Guidewire.
What is gateway-side mapping?
Gateway-side mapping lets the sender keep its own payload shape while a mediation layer converts it into the target structure. The layer holds the map and handles the translation between the two data models.
Does Guidewire accept extra fields in a payload?
By default, Guidewire's Cloud API rejects properties that its schema does not define. A request header can change that behavior to ignore, log, or reject unknown properties.
What does gateway-side mapping cost?
It adds latency to calls between the two systems and adds a service that must be managed and maintained. It also needs planning for scale and for resilience, since the layer can become a single point of failure.
How should a vendor that serves several carriers place its mapping?
Count the targets first. One carrier with a stable structure fits a map inside the sender, while several carriers or frequent changes favor holding one map per carrier in a layer.
What should you track to know a mapping works?
Track rejected requests by reason, source fields with no target match, fields dropped by ignore handling, and failures traced by correlation ID. A rising count in any of the four points to a specific gap in the map.
How does the InsOps Integration Gateway help?
The InsOps Integration Gateway lets a sender keep its own payload shape while LiLa drafts the mapping to the Guidewire structure. An administrator at the sender reviews, edits, and confirms every mapping before data moves.