Companies
Create Company
Create a new employer company under your Zeal partner account. Returns a companyID used in all subsequent company and payroll API calls.
POST
/
companies
Create Company
curl --request POST \
--url https://api.zeal.com/companies \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"partnerID": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"email": "<string>",
"business_name": "<string>",
"business_ein": "<string>",
"business_address": "<string>",
"business_city": "<string>",
"business_state": "<string>",
"business_zip": "<string>",
"business_phone": "<string>",
"mail_address": "<string>",
"mail_city": "<string>",
"mail_state": "<string>",
"mail_zip": "<string>",
"ssn": "<string>",
"ownership_percentage": 123,
"dob": "<string>",
"address": "<string>",
"city": "<string>",
"state": "<string>",
"zip": "<string>",
"skip_migration": false,
"job_title": "<string>",
"address_line2": "<string>",
"payroll_firstDate": "<string>",
"payroll_firstPayPeriodID": "<string>"
}
'import requests
url = "https://api.zeal.com/companies"
payload = {
"partnerID": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"email": "<string>",
"business_name": "<string>",
"business_ein": "<string>",
"business_address": "<string>",
"business_city": "<string>",
"business_state": "<string>",
"business_zip": "<string>",
"business_phone": "<string>",
"mail_address": "<string>",
"mail_city": "<string>",
"mail_state": "<string>",
"mail_zip": "<string>",
"ssn": "<string>",
"ownership_percentage": 123,
"dob": "<string>",
"address": "<string>",
"city": "<string>",
"state": "<string>",
"zip": "<string>",
"skip_migration": False,
"job_title": "<string>",
"address_line2": "<string>",
"payroll_firstDate": "<string>",
"payroll_firstPayPeriodID": "<string>"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
partnerID: '<string>',
first_name: '<string>',
last_name: '<string>',
email: '<string>',
business_name: '<string>',
business_ein: '<string>',
business_address: '<string>',
business_city: '<string>',
business_state: '<string>',
business_zip: '<string>',
business_phone: '<string>',
mail_address: '<string>',
mail_city: '<string>',
mail_state: '<string>',
mail_zip: '<string>',
ssn: '<string>',
ownership_percentage: 123,
dob: '<string>',
address: '<string>',
city: '<string>',
state: '<string>',
zip: '<string>',
skip_migration: false,
job_title: '<string>',
address_line2: '<string>',
payroll_firstDate: '<string>',
payroll_firstPayPeriodID: '<string>'
})
};
fetch('https://api.zeal.com/companies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zeal.com/companies",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'partnerID' => '<string>',
'first_name' => '<string>',
'last_name' => '<string>',
'email' => '<string>',
'business_name' => '<string>',
'business_ein' => '<string>',
'business_address' => '<string>',
'business_city' => '<string>',
'business_state' => '<string>',
'business_zip' => '<string>',
'business_phone' => '<string>',
'mail_address' => '<string>',
'mail_city' => '<string>',
'mail_state' => '<string>',
'mail_zip' => '<string>',
'ssn' => '<string>',
'ownership_percentage' => 123,
'dob' => '<string>',
'address' => '<string>',
'city' => '<string>',
'state' => '<string>',
'zip' => '<string>',
'skip_migration' => false,
'job_title' => '<string>',
'address_line2' => '<string>',
'payroll_firstDate' => '<string>',
'payroll_firstPayPeriodID' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zeal.com/companies"
payload := strings.NewReader("{\n \"partnerID\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"<string>\",\n \"business_name\": \"<string>\",\n \"business_ein\": \"<string>\",\n \"business_address\": \"<string>\",\n \"business_city\": \"<string>\",\n \"business_state\": \"<string>\",\n \"business_zip\": \"<string>\",\n \"business_phone\": \"<string>\",\n \"mail_address\": \"<string>\",\n \"mail_city\": \"<string>\",\n \"mail_state\": \"<string>\",\n \"mail_zip\": \"<string>\",\n \"ssn\": \"<string>\",\n \"ownership_percentage\": 123,\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"zip\": \"<string>\",\n \"skip_migration\": false,\n \"job_title\": \"<string>\",\n \"address_line2\": \"<string>\",\n \"payroll_firstDate\": \"<string>\",\n \"payroll_firstPayPeriodID\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.zeal.com/companies")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"partnerID\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"<string>\",\n \"business_name\": \"<string>\",\n \"business_ein\": \"<string>\",\n \"business_address\": \"<string>\",\n \"business_city\": \"<string>\",\n \"business_state\": \"<string>\",\n \"business_zip\": \"<string>\",\n \"business_phone\": \"<string>\",\n \"mail_address\": \"<string>\",\n \"mail_city\": \"<string>\",\n \"mail_state\": \"<string>\",\n \"mail_zip\": \"<string>\",\n \"ssn\": \"<string>\",\n \"ownership_percentage\": 123,\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"zip\": \"<string>\",\n \"skip_migration\": false,\n \"job_title\": \"<string>\",\n \"address_line2\": \"<string>\",\n \"payroll_firstDate\": \"<string>\",\n \"payroll_firstPayPeriodID\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zeal.com/companies")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"partnerID\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"<string>\",\n \"business_name\": \"<string>\",\n \"business_ein\": \"<string>\",\n \"business_address\": \"<string>\",\n \"business_city\": \"<string>\",\n \"business_state\": \"<string>\",\n \"business_zip\": \"<string>\",\n \"business_phone\": \"<string>\",\n \"mail_address\": \"<string>\",\n \"mail_city\": \"<string>\",\n \"mail_state\": \"<string>\",\n \"mail_zip\": \"<string>\",\n \"ssn\": \"<string>\",\n \"ownership_percentage\": 123,\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"zip\": \"<string>\",\n \"skip_migration\": false,\n \"job_title\": \"<string>\",\n \"address_line2\": \"<string>\",\n \"payroll_firstDate\": \"<string>\",\n \"payroll_firstPayPeriodID\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"companyID": "1ea89873acdae98734",
"status": "initial_onboarding",
"first_name": "richard",
"last_name": "hendricks",
"email": "richard@piedpiper.com",
"business_name": "Pied Piper",
"business_ein": "073647583",
"business_address": "1 Market St.",
"business_city": "San Francisco",
"business_state": "CA",
"business_zip": "94110",
"skip_migration": false,
"business_phone": "2025550151",
"mail_address": "1 Market St.",
"mail_city": "San Francisco",
"mail_state": "CA",
"mail_zip": "94110",
"requirements": [],
"account_number": null,
"routing_number": null,
"is_sandbox": true,
"ssn": "22-333-4444",
"ownership_percentage": 25,
"dob": "01/01/1990",
"legal_structure": "ccorp",
"job_title": "CEO",
"address": "1 Ferry Building",
"city": "San francisco",
"state": "CA",
"zip": "94105",
"company_type": "all",
"onboarding_url": "/employeronboard/1ea89873acdae98734?companyID=1ea89873acdae98734&classification=TEST",
"payroll_firstCheckDate": "2024-08-30",
"payroll_schedule": "weekly",
"payroll_firstPayPeriodID": "6580ce4a3808d60023b4e412"
}
}{
"success": false,
"errors": [
{
"message": "The address provided is not a valid, mail-deliverable address",
"code": 48
}
]
}This endpoint registers a new employer company under your Zeal partner account and returns a
companyID you will use in every subsequent API call for that company. See The Company Object for the full field reference.Authorizations
Body
application/json
Your Partner ID (found in the API page of your Admin portal)
First name of business owner or administrator.
Last name of business owner or administrator.
Email address of business.
Legal name of business.
Federal EIN of business.
Street address component of business address
City component of business address
State component of business address
Zip code component of business address
Phone number of business
Mailing address of company
Mailing city of company
Mailing state of company
Mailing ZIP code of company
SSN of the primary business owner.
The ownership percentage held by the primary business owner.
The legal structure of the business.
Available options:
ccorp, corp, estate, foreign_entity, llc, llp, lp, nonprofit, partnership, scheme, scorp, soleprop, trust Date of birth of the primary business owner. This should be in theMM/DD/YYYY format
Address of the primary business owner.
City of the primary business owner.
State of the primary business owner.
Zip code of the primary business owner.
If true, Zeal will skip migrating payroll information from the company's old payroll provider. Note: please confirm with the company that migration is not necessary. Failure to migrate old records may impact tax reporting and filing.
The job title of the primary business owner.
Mark your company as "all" (employees and contractors) or "contractor_only" to limit company's scope to 1099 contractors.
Available options:
all, contractor_only Address line 2 of the primary business owner.
The default payroll schedule that the company follows
Available options:
daily, weekly, biweekly, semimonthly, monthly The ISO-8601 date of the first regular payroll
Reporting period ID of the first regular payroll
⌘I
Create Company
curl --request POST \
--url https://api.zeal.com/companies \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"partnerID": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"email": "<string>",
"business_name": "<string>",
"business_ein": "<string>",
"business_address": "<string>",
"business_city": "<string>",
"business_state": "<string>",
"business_zip": "<string>",
"business_phone": "<string>",
"mail_address": "<string>",
"mail_city": "<string>",
"mail_state": "<string>",
"mail_zip": "<string>",
"ssn": "<string>",
"ownership_percentage": 123,
"dob": "<string>",
"address": "<string>",
"city": "<string>",
"state": "<string>",
"zip": "<string>",
"skip_migration": false,
"job_title": "<string>",
"address_line2": "<string>",
"payroll_firstDate": "<string>",
"payroll_firstPayPeriodID": "<string>"
}
'import requests
url = "https://api.zeal.com/companies"
payload = {
"partnerID": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"email": "<string>",
"business_name": "<string>",
"business_ein": "<string>",
"business_address": "<string>",
"business_city": "<string>",
"business_state": "<string>",
"business_zip": "<string>",
"business_phone": "<string>",
"mail_address": "<string>",
"mail_city": "<string>",
"mail_state": "<string>",
"mail_zip": "<string>",
"ssn": "<string>",
"ownership_percentage": 123,
"dob": "<string>",
"address": "<string>",
"city": "<string>",
"state": "<string>",
"zip": "<string>",
"skip_migration": False,
"job_title": "<string>",
"address_line2": "<string>",
"payroll_firstDate": "<string>",
"payroll_firstPayPeriodID": "<string>"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
partnerID: '<string>',
first_name: '<string>',
last_name: '<string>',
email: '<string>',
business_name: '<string>',
business_ein: '<string>',
business_address: '<string>',
business_city: '<string>',
business_state: '<string>',
business_zip: '<string>',
business_phone: '<string>',
mail_address: '<string>',
mail_city: '<string>',
mail_state: '<string>',
mail_zip: '<string>',
ssn: '<string>',
ownership_percentage: 123,
dob: '<string>',
address: '<string>',
city: '<string>',
state: '<string>',
zip: '<string>',
skip_migration: false,
job_title: '<string>',
address_line2: '<string>',
payroll_firstDate: '<string>',
payroll_firstPayPeriodID: '<string>'
})
};
fetch('https://api.zeal.com/companies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zeal.com/companies",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'partnerID' => '<string>',
'first_name' => '<string>',
'last_name' => '<string>',
'email' => '<string>',
'business_name' => '<string>',
'business_ein' => '<string>',
'business_address' => '<string>',
'business_city' => '<string>',
'business_state' => '<string>',
'business_zip' => '<string>',
'business_phone' => '<string>',
'mail_address' => '<string>',
'mail_city' => '<string>',
'mail_state' => '<string>',
'mail_zip' => '<string>',
'ssn' => '<string>',
'ownership_percentage' => 123,
'dob' => '<string>',
'address' => '<string>',
'city' => '<string>',
'state' => '<string>',
'zip' => '<string>',
'skip_migration' => false,
'job_title' => '<string>',
'address_line2' => '<string>',
'payroll_firstDate' => '<string>',
'payroll_firstPayPeriodID' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zeal.com/companies"
payload := strings.NewReader("{\n \"partnerID\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"<string>\",\n \"business_name\": \"<string>\",\n \"business_ein\": \"<string>\",\n \"business_address\": \"<string>\",\n \"business_city\": \"<string>\",\n \"business_state\": \"<string>\",\n \"business_zip\": \"<string>\",\n \"business_phone\": \"<string>\",\n \"mail_address\": \"<string>\",\n \"mail_city\": \"<string>\",\n \"mail_state\": \"<string>\",\n \"mail_zip\": \"<string>\",\n \"ssn\": \"<string>\",\n \"ownership_percentage\": 123,\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"zip\": \"<string>\",\n \"skip_migration\": false,\n \"job_title\": \"<string>\",\n \"address_line2\": \"<string>\",\n \"payroll_firstDate\": \"<string>\",\n \"payroll_firstPayPeriodID\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.zeal.com/companies")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"partnerID\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"<string>\",\n \"business_name\": \"<string>\",\n \"business_ein\": \"<string>\",\n \"business_address\": \"<string>\",\n \"business_city\": \"<string>\",\n \"business_state\": \"<string>\",\n \"business_zip\": \"<string>\",\n \"business_phone\": \"<string>\",\n \"mail_address\": \"<string>\",\n \"mail_city\": \"<string>\",\n \"mail_state\": \"<string>\",\n \"mail_zip\": \"<string>\",\n \"ssn\": \"<string>\",\n \"ownership_percentage\": 123,\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"zip\": \"<string>\",\n \"skip_migration\": false,\n \"job_title\": \"<string>\",\n \"address_line2\": \"<string>\",\n \"payroll_firstDate\": \"<string>\",\n \"payroll_firstPayPeriodID\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zeal.com/companies")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"partnerID\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"<string>\",\n \"business_name\": \"<string>\",\n \"business_ein\": \"<string>\",\n \"business_address\": \"<string>\",\n \"business_city\": \"<string>\",\n \"business_state\": \"<string>\",\n \"business_zip\": \"<string>\",\n \"business_phone\": \"<string>\",\n \"mail_address\": \"<string>\",\n \"mail_city\": \"<string>\",\n \"mail_state\": \"<string>\",\n \"mail_zip\": \"<string>\",\n \"ssn\": \"<string>\",\n \"ownership_percentage\": 123,\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"zip\": \"<string>\",\n \"skip_migration\": false,\n \"job_title\": \"<string>\",\n \"address_line2\": \"<string>\",\n \"payroll_firstDate\": \"<string>\",\n \"payroll_firstPayPeriodID\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"companyID": "1ea89873acdae98734",
"status": "initial_onboarding",
"first_name": "richard",
"last_name": "hendricks",
"email": "richard@piedpiper.com",
"business_name": "Pied Piper",
"business_ein": "073647583",
"business_address": "1 Market St.",
"business_city": "San Francisco",
"business_state": "CA",
"business_zip": "94110",
"skip_migration": false,
"business_phone": "2025550151",
"mail_address": "1 Market St.",
"mail_city": "San Francisco",
"mail_state": "CA",
"mail_zip": "94110",
"requirements": [],
"account_number": null,
"routing_number": null,
"is_sandbox": true,
"ssn": "22-333-4444",
"ownership_percentage": 25,
"dob": "01/01/1990",
"legal_structure": "ccorp",
"job_title": "CEO",
"address": "1 Ferry Building",
"city": "San francisco",
"state": "CA",
"zip": "94105",
"company_type": "all",
"onboarding_url": "/employeronboard/1ea89873acdae98734?companyID=1ea89873acdae98734&classification=TEST",
"payroll_firstCheckDate": "2024-08-30",
"payroll_schedule": "weekly",
"payroll_firstPayPeriodID": "6580ce4a3808d60023b4e412"
}
}{
"success": false,
"errors": [
{
"message": "The address provided is not a valid, mail-deliverable address",
"code": 48
}
]
}