A payload comes back from the carrier rejected, and the sender has no clear reason why. A required field is empty, a date arrives in the wrong format, or two totals disagree. Each resend restarts intake and pushes the submission further down the underwriting queue.
A rejected payload points back to the payload specification, the document that governs what a sender transmits and what a carrier checks. This guide covers a four-layer structure for writing one, a test sequence to run before the carrier sees it, and the metrics that show it works.
What Is a Payload Specification, and Why Do Carriers Reject Payloads?
A payload specification is the written contract that lists every field a sender transmits, the format of each field, and the response a carrier returns when a check fails. Carriers validate each payload on arrival, so the specification decides whether a submission is accepted or sent back.
What a carrier checks on arrival
Intake validation runs in three passes. It confirms the JSON is well formed, confirms each field matches its expected type and allowed values, and confirms the values agree with each other. A payload that fails the first pass never reaches the second.
Why payloads get sent back
Rejections cluster around three causes: missing required fields, values in the wrong format, and figures that contradict each other across the packet. The third cause is the hardest to fix, because nobody can tell which figure is correct without asking the sender.
Rejected payloads and retries are the visible cost of unreliable insurance data exchange. The same pattern explains why poor submission quality slows down underwriting.
How Do You Write a Payload Specification? The Four-Layer Spec
Write the specification in four layers: Identity, Structure, Consistency, and Response. Each layer answers one question the carrier asks about every payload, and each gets its own section in the document.
Layer | Question the carrier asks | What the specification defines |
|---|---|---|
Identity | Who sent this, and for which product? | Sender ID, producer code, line of business |
Structure | Is every field present and valid? | Field names, types, formats, allowed values, required flags |
Consistency | Do the values agree with each other? | Cross-field rules, such as schedule totals matching stated exposure |
Response | What happens when a check fails? | Error codes, messages, and the sender's next step |
Layer 1: Identity
Open every payload with who is sending and what is being requested. Define the sender identifier, the producer code, and the line of business, because the carrier authorizes and routes on these before it reads anything else.
A payload with a wrong producer code fails no matter how clean the rest of the data is. Keep these three fields at the top of the payload so a failure here surfaces before any deeper check runs.
Layer 2: Structure
List each field once, with its name, type, format, required flag, and allowed values. State date, currency, and number formats explicitly instead of leaving them to convention. Required fields differ between property and workers' compensation, so mark them per line of business. An illustrative set of field definitions looks like this:
Field | Type | Required | Rule |
|---|---|---|---|
producerCode | string | Yes | Matches an appointed producer |
lineOfBusiness | enumeration | Yes | One of the lines the carrier writes |
effectiveDate | date, YYYY-MM-DD | Yes | Falls on or after the submission date |
totalPayroll | number, USD | Per line | Equals the sum of the schedule rows |
Layer 3: Consistency
Write the cross-field rules the carrier applies as plain sentences a sender can test. Payroll on the application matches payroll on the schedule. The location count matches the schedule rows. A published rule turns a rejection into something the sender prevents.
Layer 4: Response
Document every failure the carrier returns: an error code, a plain-language message, the field that failed, and the sender's next step. A response that reads "invalid payload" sends the sender back to guess. One that names the field and the rule ends the guessing.
Return the same error format for every failure, so the sender writes one handler instead of one per rule.
How Do You Test a Specification Before the Carrier Sees It?
Test with real sample payloads, including deliberately broken ones, before the first production send. A specification that documents only the clean path leaves every failure for the sender to discover live.
Run the test sequence
Validate the JSON syntax with a schema validator.
Send a complete, clean sample and confirm it is accepted.
Remove one required field at a time and confirm the error names that field.
Break one consistency rule at a time and confirm the response states the rule.
Have a named reviewer confirm the field mapping before data moves.
Review the mapping with a person
Mapping errors pass syntax checks, so a validator alone does not catch them. A value that lands in the wrong target field validates cleanly and corrupts the record. The reviewer compares each source field to its target and signs off before deployment.
Measure what the carrier accepts
Count how many payloads the carrier accepts on the first send, and log every rejection against the field and rule that caused it. A rule that triggers repeatedly points to a gap in the specification, not a one-off data error. Review the log after each carrier release and update the Consistency and Response layers first.
How Long Does It Take, and Where Do Teams Get Stuck?
Timeline scales with the number of lines of business. Each added line repeats the Structure and Consistency layers, while Identity and Response carry over largely unchanged.
A realistic sequence
Draft the four layers, build a sample payload, run the test sequence, fix the gaps, then send a test submission that exercises the producer code check. Plan for a revision cycle after the carrier's first review, because the carrier applies rules the sender has not seen until a payload fails.
Where teams get stuck
Three failures repeat. Some teams define fields without allowed values, so plausible data fails. Others write the Consistency layer last, so cross-field rules go untested. A third group skips the Response layer, so a rejection arrives with no instruction.
When every partner needs its own specification, maintenance grows with each connection. That is why standardized API gateways are replacing point-to-point connections.
How InsOps Helps
InsOps builds an insurance-trained AI that assists with mapping payloads into a carrier's core platform. LiLa, our insurance-trained LLM, drafts the field mapping from your payload to the platform's structure, and your administrator reviews and confirms every mapping before data moves.
The InsOps Integration Gateway gives MGAs, brokers, and underwriting vendors a prebuilt route into the carrier's core platform. You register in a self-service portal, bring your payload, and configure it without building your own connector. The gateway runs inside the carrier's own environment, so PII and PHI stay in controlled infrastructure. InsOps is a Guidewire technology partner.
The gateway handles authentication, validation, and request logging, so your engineers spend their time on your product instead of platform APIs. If you are evaluating how to exchange submission data with a carrier without a custom connector build, contact us to talk through what this looks like for your operation.
Frequently Asked Questions
What is a payload specification?
It is the document a sender and a carrier both work from: fields, formats, validation rules, and error responses for one payload type.
Why do carriers send payloads back?
A payload fails when a required field is missing, a value breaks its format, or figures disagree across the packet. Each failure stops the file before an underwriter sees it.
How do you write a payload specification a carrier will accept?
Define four layers in separate sections: Identity, Structure, Consistency, and Response. Then test with clean and deliberately broken sample payloads before the first production send.
Which fields belong in every payload?
The sender identifier, producer code, and line of business belong in every payload, along with the effective date and core exposure fields for the product. Required sets differ by line, so list them per line of business.
What should you track to know a specification works?
First-pass acceptance rate is the primary measure: the share of payloads accepted without sender correction. Pair it with rejections by field, resends per submission, and time from send to an underwriter-ready file.
How does the InsOps Integration Gateway help?
The gateway gives senders a prebuilt route into a carrier's core platform, with LiLa drafting the payload mapping. A person on the sender's side reviews and confirms every mapping before data moves.
How long does it take to get a specification accepted?
It depends on how many lines of business you send and how many review rounds the carrier needs. Running the test sequence first removes the avoidable rejections, so the carrier's review covers carrier-specific rules only.