API Lead Creation Error (417): Requires 'first_name' Despite 'company_name' Being Provided (v15.58

[777]

Hi everyone,

I’m encountering a persistent validation issue when creating Leads via the ERPNext REST API, specifically using n8n as the integration tool. My ERPNext instance is self-hosted using the standard Coolify template.

Environment:

• ERPNext Version: v15.58.1 (Image tag frappe/erpnext:v15.58.1 pulled around April 17, 2025)

• Deployment: Self-hosted via Coolify (Link to template)

• Integration Tool: n8n (using the standard ERPNext node - Resource: Document, Operation: Create, DocType: Lead)

The Problem:

When attempting to create a new Lead via the API and providing the organization’s name mapped to the standard company_name field, I consistently receive a 417 Validation Error:

{
  "exception": "frappe.exceptions.ValidationError: A Lead requires either a person's name or an organization's name",
  "exc_type": "ValidationError",
  "_exc_source": "erpnext (app)",
  "exc": "[\"Traceback (... traceback details pointing to lead.py -> set_lead_name function ... )\"]",
  "_server_messages": "[...]"
}

This error occurs even though the company_name field (the standard field for the organization’s name) is being correctly mapped and sent with a valid string value in the API payload.

Troubleshooting Steps & Findings:

1. company_name Only: Sending the API request with only company_name (and other necessary/custom fields like status, custom_category, etc.) consistently fails with the 417 error above.

2. Adding first_name: If I add the standard first_name field to the API payload in addition to company_name, the API call succeeds (returns a 200 OK status).

• This works even if the value provided for first_name is just a placeholder string (e.g., “Contact” or “Lead”).

3. Side Effect: Providing first_name also triggers ERPNext’s standard behavior of automatically creating a linked Contact document, which is understandable but highlights that the first_name field is being processed.

Core Issue/Question:

The validation error message suggests that either a person’s name (like first_name) or an organization’s name (company_name) is sufficient. However, based on API testing with v15.58.1, it seems that providing company_name alone is not enough to satisfy the validation check performed during the API request handling (set_lead_name function). The presence of a non-empty first_name appears to be mandatory via the API to prevent the 417 error, even if company_name is validly provided.

Has anyone else encountered this specific behavior when creating Leads via the API, particularly on v15? Is this a known issue with certain ERPNext versions or API handling? Is there a configuration setting or a different approach to satisfy this validation rule strictly with company_name via the API, without needing to send a potentially redundant first_name?

Any insights or suggestions would be greatly appreciated!

Thanks!

[777]

Posting an update and solution to the issue I previously raised regarding the 417 Validation Error (A Lead requires either a person’s name or an organization’s name) when creating Leads via API (using n8n) on ERPNext v15.58.1 deployed via Coolify.

Recap of Initial Problem:
The standard API endpoint seemed to require the first_name field to be populated, even when the company_name field (organization’s name) was correctly provided. Sending only company_name resulted in the 417 error, while adding even a placeholder first_name allowed the API call to succeed. This behavior was inconsistent, adding to the confusion.

Troubleshooting Journey:
We went through extensive debugging, including confirming Server Script enablement, attempting Server Script workarounds (which failed due to ERPNext’s internal field population timing), and exploring custom API options (which led to separate issues related to custom app deployment in Docker).

The Actual Root Cause:
The core issue turned out to be invalid source data coming from my Google Sheet trigger. Specifically:

• The Google Sheet contained completely empty rows .

• When n8n processed these empty rows, it sent API requests to ERPNext with essentially no data for company_name or any name fields.

Why This Caused the Error:
ERPNext’s validation rule requires either a person’s name or an organization’s name. When an API request arrived representing an empty row from the sheet (meaning company_name, first_name, and last_name were all effectively null or empty), the validation check failed, resulting in the 417 error. The times the API call worked were likely when n8n was processing valid rows from the sheet.

The Solution:
The fix was simple data hygiene at the source:

1. Deleted all completely empty rows from the Google Sheet that were being picked up by the n8n trigger.

Outcome:
Once the empty rows were removed, ensuring that every API call initiated by n8n contained valid data (specifically, a non-empty company_name).

Key Takeaway:
Before diving deep into potential ERPNext API quirks or complex workarounds, always meticulously check and clean your source data. Empty records or rows can lead to validation errors that might initially seem misleading. Ensuring essential fields (like company_name in this case) have valid data before hitting the API is crucial.