Skip to main content
POST
/
form_batches
Create a form batch
curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/form_batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "owner_id": "<id>",
  "form_type": "t4",
  "effective_date": "2026-01-01",
  "form_stage": "original",
  "contact_name": "Prof. Brody Ernser III",
  "contact_email": "weber.pierre@example.net",
  "contact_area_code": "657",
  "contact_phone_number": "3654916"
}
'
{
  "id": "<id>",
  "object": "form_batch",
  "data": {
    "owner": {
      "id": "<id>",
      "object": "business_entity",
      "links": {
        "self": "/business_entities/<id>"
      }
    },
    "form_type": "t4",
    "form_stage": "original",
    "effective_date": "2026-01-01",
    "status": "draft",
    "contact_name": "Prof. Brody Ernser III",
    "contact_email": "weber.pierre@example.net",
    "contact_area_code": "657",
    "contact_phone_number": "3654916",
    "contact_extension": null,
    "note": null,
    "metadata": {
      "counts": {
        "total": 0,
        "valid": 0,
        "invalid": 0,
        "draft": 0,
        "approved": 0,
        "processing": 0,
        "submitted": 0,
        "done": 0,
        "rejected": 0
      },
      "flags": {
        "is_submittable": false
      },
      "timestamps": {
        "submitted_at": null,
        "completed_at": null
      },
      "identifiers": {
        "confirmation_number": null
      }
    },
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/form_batches/<id>"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
owner_id
string
required
​
form_type
enum<string>
required

The type of Forms in this batch (e.g. T4, RL-1).

Must be a form type that supports form batches. Not all form types support batches.

Available options:
rl1,
roe,
t4,
t4a,
td1,
td1ab,
td1bc,
td1mb,
td1nb,
td1nl,
td1ns,
td1nt,
td1nu,
td1on,
td1pe,
td1sk,
td1x,
td1yt,
tp_1015_3_v,
tp_1015_r_13_v
​
contact_name
string
required

The name of the contact person responsible for this submission.

Maximum string length: 255
​
contact_email
string
required

The email address of the contact person.

Maximum string length: 255
​
contact_area_code
string
required

The 3-digit area code of the contact's phone number.

​
contact_phone_number
string
required

The 7-digit phone number of the contact.

​
effective_date
string<date>

The effective date used to determine the form variant for all Forms in this batch.

Determines the form variant. Defaults to January 1 of the current year if not provided.

​
form_stage
enum<string>

The lifecycle stage of the Forms in this batch: original, amendment, or cancellation.

Defaults to original if not provided.

Available options:
amendment,
cancellation,
original
​
contact_extension
string | null

The optional extension for the contact's phone number.

​
note
string | null

An optional note for this form batch.

Maximum string length: 65000

Response

201 - application/json

Created

​
id
string
read-only

The unique identifier of the object in Nmbr.

​
object
string
read-only

The type of the object in Nmbr ("form_batch").

​
data
Form Batch · object