HubSpot Forms API Required Fields Fix

What HubSpot expects

HubSpot Forms API submissions should send field values inside a top-level `fields` array. Each item should be an object with `name` and `value`.

{
  "fields": [
    {
      "name": "email",
      "value": "developer@example.com"
    },
    {
      "name": "firstname",
      "value": "Alex"
    }
  ]
}

Common causes

1. The `fields` array is missing

If you send values at the top level instead of inside `fields`, HubSpot cannot map them to the form fields.

{
  "email": "developer@example.com",
  "firstname": "Alex"
}

Move those values into the `fields` array instead.

2. Field objects are malformed

Each field item should be an object. Sending a string, number, or nested array inside `fields` can produce validation errors.

{
  "fields": [
    "developer@example.com"
  ]
}

3. You are using labels instead of internal names

Use the HubSpot internal property name, such as `email`, `firstname`, `lastname`, `company`, or your custom property's internal name. Do not use labels like "Email Address" or "First Name".

{
  "fields": [
    {
      "name": "Email Address",
      "value": "developer@example.com"
    }
  ]
}

4. A required value is empty

An empty string may pass JSON validation but still fail form validation when the corresponding field is required in HubSpot.

{
  "fields": [
    {
      "name": "email",
      "value": ""
    }
  ]
}

Debug pattern

Start with the smallest payload that should work. If that succeeds, add the rest of the fields one at a time until the error appears again.

{
  "fields": [
    {
      "name": "email",
      "value": "developer@example.com"
    }
  ],
  "context": {
    "pageUri": "https://example.com/contact",
    "pageName": "Contact"
  }
}

PHP payload pattern

In PHP or WordPress, build the field list from validated values. Trim values first and only submit required fields when they contain usable data.

$email = trim((string) ($_POST['email'] ?? ''));
$firstName = trim((string) ($_POST['first_name'] ?? ''));

$fields = [];

if ($email !== '') {
    $fields[] = [
        'name' => 'email',
        'value' => $email,
    ];
}

if ($firstName !== '') {
    $fields[] = [
        'name' => 'firstname',
        'value' => $firstName,
    ];
}

$payload = [
    'fields' => $fields,
];

Fix HubSpot Forms API required field errors.

Fast checklist