The three lists to compare
Compare the incoming value against three separate configurations:
A value can exist globally and still be unavailable for the record type. A dependent value can be valid only when the controlling field has a compatible value. Salesforce Help specifically notes that the API name and label can differ, and that record-type availability matters.
- The field’s global value set.
- The values selected for the record type.
- The dependency rules for the controlling picklist.
API name versus label
An administrator can give a picklist value a friendly label and a different API name. Your integration should use the API name expected by the API. Do not copy the visible screen text without checking metadata.
Metadata-driven code can build a mapping:
The left side is your source value; the right side must be confirmed against Salesforce metadata for the target object and field. Keep the mapping versioned and environment-aware.
{
"qualified": "Qualified",
"enterprise": "Enterprise"
}
Record type availability
In Setup, open Object Manager, select the object, open Record Types, and edit the picklist field. Check whether the value is in Selected Values rather than Available Values. If it is not selected for that record type, the API can reject it even though the field definition contains it.
Do not fix this by enabling every value for every record type without understanding reporting and validation consequences. Record types often encode business process, and a restricted list prevents invalid combinations.
Null, empty string, and missing property
These inputs are different:
Test create and update separately. A field that is required during creation may behave differently when clearing an existing value. Do not assume a successful request means the field was set; read the record back.
| Input | Possible meaning |
|---|
| Missing field | Leave existing value unchanged on update |
| null | Clear or reject, depending on API and field |
| Empty string | Blank text, invalid picklist value, or reject |
| Valid API name | Set the chosen value |
Dependent picklists and defaults
If a restricted field depends on a controlling picklist, send compatible values together. A default value on a record type or field can also trigger a bad-value error when the controlling field is absent from the layout or request. Salesforce’s help documentation describes cases where a restricted dependent picklist has a default but the controlling field is unavailable.
Inspect active flows, triggers, quick actions, and deployment metadata. An error may be produced by automation after your request, not by the original JSON property.
A debugging request
Capture object, record type, field, submitted value, API version, and response errors. Redact customer data. Retrieve object metadata and compare the exact value. Then reproduce with one record and no unrelated fields.
If a direct REST request works but an automation fails, inspect mapping transformations and record type selection. If both fail, inspect metadata and permissions first.
Restricted versus unrestricted
Restricted picklists protect data quality by limiting values. Unrestricted picklists can accept values outside the defined set, but changing the setting is a schema and governance decision, not a quick integration patch. It can create reporting variants such as “Qualified,” “qualified,” and “Qualified ” that appear similar to people but differ operationally.
Prefer fixing the source mapping and record-type configuration. Use unrestricted behavior only when the business intentionally allows new values and has a cleanup process.
Deployment and sandbox checks
Picklist values and record-type selections can differ across environments after metadata deployment. After deploying, test each target record type and the values your integration uses. Do not rely on a production-only manual check.
Store a metadata snapshot with the release. If a deployment removes a selected value, the snapshot shows whether the defect began in metadata or code.
The trap: adding the label to the global picklist and stopping there. A restricted record type can still reject it, and a dependent field can still require a compatible controlling value.
Trace errors through automation
If the original record request contains a valid value, inspect flows, Apex triggers, validation rules, and quick actions that run after save. A trigger can replace a valid field with null or with a value that is not allowed for the record type. Compare the field immediately before the request with the final error detail and use a small test record to isolate automation.
For imports, preserve the source row number and external ID in the failure report. That lets an operator correct one mapping rather than rerunning the entire file.
Build a picklist contract
For each integrated field, document object, field API name, accepted API values, record types, controlling-field requirements, and blank-value policy. Version the contract with the integration so a metadata change is visible in code review.
Run the contract against every supported record type before a bulk release. Include one valid API name, one visible label that should be rejected or translated, one unavailable record-type value, and one blank input. Store the result with the deployment so a later failure can be tied to either metadata or mapping.
For a failed row, show the field API name, mapped value, record type, and metadata version in the operator report. That makes the correction actionable without exposing the full customer record.
For a required picklist, document whether the blank case should be rejected before the API call, populated from a record-type default, or routed to an operator. That decision prevents different connectors from treating null and an empty string inconsistently.
Use a dead-letter queue for rows that remain unresolved. Keep the source row, error class, and retry count so an operator can correct the mapping and replay only the affected records.
A compact failure matrix
| Test | Expected result | |---|---| | Exact API value, selected record type | Save succeeds | | Visible label instead of API value | Mapping or validation failure | | Globally valid value, unselected record type | Restricted-picklist error | | Blank required value | Required-field or null-value error |
Run this matrix with the same user and API version used in production. It separates a mapping defect from a metadata defect before a bulk replay begins.
Where these facts come from