Four lists must agree
For a reliable integration, compare these four inputs:
“Closed Won” displayed in Setup may have an API value with different punctuation or capitalization. A value can be active globally but not selected for the record type. A dependent value can be selected but unavailable for the controlling value in the same request.
- The field’s defined values or global value set.
- The values selected for the target record type.
- The controlling-field values when the picklist is dependent.
- The exact API value sent by the client.
Find the record type used by the API
Do not infer record type from the page a human last viewed. The request may include a `RecordTypeId`, an integration default, or an automation may assign one during save. Retrieve the target record type and log its ID in a redacted diagnostic record.
Example create shape:
The exact stage values must come from the target org and record type. If the record type is omitted, Salesforce can use a default that is different from the one tested by the team.
{
"Name": "Example opportunity",
"StageName": "Prospecting",
"CloseDate": "2026-12-31",
"RecordTypeId": "012XXXXXXXXXXXX"
}
Check selected values in Setup
An administrator can inspect the picklist values available to each record type. The value may appear in the field’s global list but remain in Available Values rather than Selected Values for the target record type. Review this in every org where the integration runs.
Record types can also be associated with different business processes for objects such as opportunities, cases, and leads. That association can affect which values are valid. Do not broaden every record type to fix one integration without confirming the business meaning.
Dependencies create a second failure path
A dependent picklist is controlled by another field. The dependent option may be legal only when the controlling field has a specific value. Test the pair, not just the dependent value by itself. If the client sends fields in separate updates, the first update can temporarily create an invalid combination.
For a dependent field, document the permitted pairs and the order of writes. If the business process requires both values at creation, send them together when the API path and validation rules support it.
Exact matching and blank values
Restricted picklists can reject case differences, trailing spaces, altered punctuation, and translated labels. Normalize source input at the boundary, but do not silently map an unknown value to the first option. Send it to review with the source row and record type.
Missing, `null`, and empty string are different cases. A required picklist may reject all blank forms. An update that clears a value may follow a different rule from a create. Test the clearing behavior explicitly rather than assuming the UI’s blank option is an API value.
A deterministic debugging procedure
Capture the error, target object, record type ID, field API name, exact submitted value, API version, and user. Reproduce one record with unrelated fields removed. Verify the value globally, then verify record-type availability and dependencies. Confirm the integration user can edit the field. Finally inspect flows, triggers, and validation rules that may change the record during save.
If the same JSON works under one record type but not another, the record type is the leading suspect. If it fails for every record type, inspect API value mapping, field definition, permissions, and object metadata.
Prevent recurring failures
Version a picklist contract with canonical API values, record types, controlling values, blank policy, and owner. Run a pre-release test for each supported record type. In bulk imports, classify rows as exact matches, normalized matches, unknown values, and record-type mismatches before sending them.
Monitor rejected values and record-type distribution. A sudden increase can indicate a new default record type, metadata deployment, source-system vocabulary change, or a connector that stopped sending `RecordTypeId`.
Keep one redacted failing fixture for every important record type. It should contain the object, record type, field API name, source value, mapped value, and expected outcome, but no customer data. Run those fixtures after metadata deployments and after changes to the connector’s mapping code. When a business owner adds a new option, update the contract and the record-type selection together; deploying only the global value can leave production integrations failing even though the option appears correctly in Setup.
When a business owner adds a new option, update the contract and the record-type selection together. Deploying only the global value can leave production integrations failing even though the option appears correctly in Setup. Add the option to the release checklist and verify one API write under the affected record type.
Also test an update to an existing record, because its current record type and automation path may differ from a new-record test.
The trap: changing a restricted picklist to unrestricted. That can hide the failed mapping while creating reporting variants that are harder to repair.
Test the record type as part of the payload contract
Store the record type ID, field API name, allowed API values, dependency pairs, and blank-value policy together. When the default record type changes, run the same fixture again. A globally valid value is not enough evidence; the acceptance test must prove that the target record type, integration user, and save automation accept the exact value sent by the client.
Where these facts come from
