Why Business Central Rejects API Data: Understanding Validation Errors and Posting Setup

1. Introduction: When an API Request Isn’t Enough

In an integration project, the first assumption is often that a successful HTTP request means the data has been accepted. In Business Central, that is only part of the story.

A request can successfully reach an API endpoint and still fail when Business Central validates the record. The platform may check whether a customer exists, whether a posting group is configured, whether a referenced item or project is available, whether a value has the expected OData data type, or whether the transaction satisfies the rules required for posting.

This distinction becomes especially important in integrations involving Dynamics 365 Project Operations, Dataverse, Logic Apps, and Business Central. Source systems and Business Central may use different field names, identifiers, data types, and record relationships.

For example, a source system may expose a project through a Dataverse lookup while Business Central expects a project number. A time-entry source may provide a duration in minutes while the target process expects hours. A date-time value may be returned from the source even though the Business Central API field is a date-only field.

These are not necessarily API connectivity problems. They are integration and business-validation problems.

2. Where an Integration Error Can Occur

A useful way to troubleshoot an integration is to divide it into stages:

The important point is that the error message should be interpreted according to the stage where the failure occurred.

3. Missing Posting Groups and Setup

Business Central uses posting groups and related setup to determine how business transactions are represented in the general ledger and other ledgers. Depending on the record and transaction, this can involve customer posting groups, vendor posting groups, general product posting groups, VAT posting groups, inventory posting setup, and other configuration.

Example: Customer Posting Group Validation

Consider an integration creating or updating a customer with a posting group value:

{
  "displayName": "Apex Manufacturing",
  "customerPostingGroup": "DOMESTIC"
}

The JSON can be valid, but Business Central can reject the value if the referenced posting group is not available in the target company or if the value does not match the destination setup.

What to check in Business Central

• Open the relevant customer, vendor, item, or setup page.
• Identify the posting-group field mentioned by the error.
• Check whether the corresponding setup record exists in the same Business Central company and environment.
• Confirm that the source-to-target mapping uses the correct Business Central code.
• Check related VAT, general posting, or product posting setup where applicable.

4. Missing References and Document Dependencies

One common integration design mistake is to send dependent transactional data before the master record that it references has been created or synchronized.

Example: Project Reference

Suppose Project Operations exposes a project through a Dataverse lookup. The integration may receive a lookup identifier, but Business Central needs a meaningful target identifier such as the Project No.

A source record might conceptually contain:

{
  "_msdyn_project_value": "source-project-guid",
  "subject": "Conveyor Cell Automation"
}

The integration should not assume that the Dataverse GUID is automatically the Business Central Project No. A lookup or expansion can be used to retrieve the source project’s integration identifier, such as an int_sourceid, and that value can then be mapped to the corresponding Business Central project.

Recommended dependency sequence

This sequencing is particularly important for integrations involving customers, vendors, products/items, projects, resources, dimensions, payment terms, and transactional documents.

5. Incorrect Data Types and Formats

OData-based Business Central APIs expose field types that must be respected by the integration. A value that looks reasonable to a developer may still be incompatible with the target field.

Cannot convert the literal '9/22/2026 12:00:00 AM'
to the expected type 'Edm.Date'.

{
  "msdyn_date": "9/22/2026 12:00:00 AM"
}

{% assign rawDate = entry.msdyn_datetimezoneindependent %}
{% assign formattedDate = rawDate | slice: 0, 10 %}

"Posting_Date": "{{ formattedDate }}"

"Posting_Date": "2026-09-22"

{
  "Unit_Price": "10000"
}

{
  "Unit_Price": 10000
}

{% if line_type == "Budget" %}
{
  "Line_Type": "Budget",
  "Unit_Cost": 50
}
{% elsif line_type == "Billable" %}
{
  "Line_Type": "Billable",
  "Unit_Price": 50
}
{% endif %}

{
  "Line_No": ""
}

{% if entry.line_number %}
  "Line_No": {{ entry.line_number }}
{% endif %}

{% assign lineNo = 30000 | plus: index | times: 10000 %}

6. Mapping and Transformation Problems

Even when the source and destination APIs are available, the transformation layer can introduce errors.

Example: Liquid Variable Mismatch

{% assign data = source.value %}

{% for _data in data %}
{
  "PrimaryId": "{{ _data.accountid }}",
  "Name": "{{ account.name }}"
}
{% endfor %}

The loop uses _data, while the name is being read from account.name. Unless account has been defined elsewhere, the expected value may not be produced.

Corrected example

{% assign data = source.value %}

{% for _data in data %}
{
  "PrimaryId": "{{ _data.accountid }}",
  "Name": "{{ _data.name }}"
}
{% endfor %}

7. Lookup and Relationship Handling

Dataverse and Business Central both use relationships between records, but the way those relationships are exposed can differ.

A lookup field may provide a GUID while the integration actually needs a related business identifier such as an account number, vendor number, project number, or document number.

Example: Retrieving a Related Invoice Value

For an invoice-detail integration, the detail record can be related to its invoice through a navigation property. Instead of treating a lookup identifier as the final business value, the integration can expand the related invoice and select the required fields.

$expand=Invoices($select=name,cf_sourceid)

The exact navigation property and entity relationship must be verified against the Dataverse metadata for the environment. The important integration principle is that a lookup identifier and a business identifier are not automatically interchangeable.

8. Document Numbers and Transaction Dependencies

Transactional integrations often have another layer of dependency: the header and its lines.

For example, an invoice line may contain an item, quantity, price, and dimensions, but it may also need to belong to a valid invoice header. If the document number is missing, generated differently than expected, or not available at the point where the line is created, the transaction can fail or produce an unexpected result.

Example

{
  "Document_No": "",
  "Type": "Item",
  "No": "1968-S",
  "Quantity": 1,
  "Unit_Price": 10000
}

Before investigating the item or price, determine whether the line has a valid relationship to its document header and whether the API is designed to generate the document number or expects the integration to provide it.

This is also why a record can exist in Business Central but still fail later during posting: creation and posting are separate stages with different validation requirements.

9. A Practical Troubleshooting Workflow

10. Best Practices for Reliable Integrations

• Document source-to-target mappings: Record source property, target field, data type, transformation, and dependency.
• Validate master data first: Synchronize customers, vendors, items, projects, resources, currencies, dimensions, and other prerequisites before transactions.
• Validate the final payload: Do not rely only on the transformation template. Inspect the actual serialized JSON.
• Respect Business Central configuration: Posting groups and related setup are part of the integration landscape, not just application administration.
• Use meaningful defaults carefully: A default value should represent a valid business rule, not merely make an API request pass.
• Separate transient and permanent errors: Network failures may be retryable; invalid data and missing setup usually require correction first.
• Design safe retries: Make sure retrying a create operation does not unintentionally create duplicate records.
• Test edge cases: Include nulls, empty strings, missing references, invalid dates, decimal precision, and unexpected source values.
• Log enough context: Capture correlation IDs, record identifiers, endpoint information, and sanitized error responses without exposing credentials or confidential data.
• Test in a controlled environment: Validate mapping and posting behavior before sending integration changes to production.

11. Integration Debugging Checklist

12. Common Errors at a Glance

13. Frequently Asked Questions

14. Conclusion

Reliable Business Central integrations require more than correct API endpoints and valid JSON. They require an understanding of the destination application’s data types, master data, relationships, posting configuration, and business rules.

The most effective troubleshooting approach is to follow the data end to end: inspect the source, inspect the transformation, inspect the exact outgoing payload, identify the Business Central field that is failing, verify related records and setup, and then test the corrected transaction in a controlled environment.