> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Explore the Zeal REST API: base URL, authentication, request and response formats, environments, and available resource groups for embedded payroll.

The Zeal REST API gives you programmatic access to every aspect of embedded payroll - from creating companies and onboarding workers to running payroll and filing taxes. All requests go to a single base URL, use JSON for both request bodies and response payloads, and are authenticated with a Bearer token tied to your Zeal partner account.

## Base URL

Every API request is sent to:

```
https://api.zeal.com
```

There is no version prefix in the path. All current endpoints are available directly beneath this root (for example, `https://api.zeal.com/companies`).

## Request and response format

All request bodies must be sent as JSON with the `Content-Type: application/json` header. All successful responses are returned as JSON. Dates follow ISO 8601 (`YYYY-MM-DD`) unless otherwise noted in a specific endpoint's documentation.

## Authentication

Every request must include an `Authorization` header with a Bearer token equal to your API key:

```
Authorization: Bearer {apiKey}
```

Your API keys are available on the **API** page of your Partner Dashboard at [app.zeal.com](https://app.zeal.com). See the [Authentication](/reference/introduction/authentication-and-keys) page for full details.

## Example request

The snippet below shows a minimal authenticated request that lists all companies under your partner account.

```bash theme={null}
curl --request GET \
     --url 'https://api.zeal.com/companies?partnerID=YOUR_PARTNER_ID' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR_API_KEY'
```

## Environments

Zeal provides two isolated environments, each with its own set of API keys.

| Environment    | Purpose                             | Money movement             |
| -------------- | ----------------------------------- | -------------------------- |
| **Test**       | Development and integration testing | No real money is disbursed |
| **Production** | Live payroll operations             | Real money is disbursed    |

<Note>
  Use your **Test API key** for all development and QA work. Switch to your **Production API key** only when you are ready to process real payroll. Test and Production resources are completely separate - data created in one environment does not appear in the other.
</Note>

## Partner ID vs Company ID

Two identifiers appear frequently across the API:

* **`partnerID`** - Identifies your Zeal partner account. Use this when creating companies or fetching resources that are scoped to your entire partner account. You can find your `partnerID` on the **API** page of the Partner Dashboard.
* **`companyID`** - Identifies a specific employer company under your partner account. Most company-level and worker-level endpoints require a `companyID`. It is returned when you call `POST /companies` and is also visible in the Partner Dashboard.

## Error format

When a request fails, Zeal returns a non-2xx HTTP status code and a JSON body describing the problem. Errors follow the standard response envelope: `success` is `false` and `errors` is an array of error objects, each with a `message` and a `code` (see [Error Codes](/reference/introduction/error-codes)):

```json theme={null}
{
  "success": false,
  "errors": [
    {
      "message": "Description of what went wrong",
      "code": 13
    }
  ]
}
```

Common status codes:

| Status | Meaning                                           |
| ------ | ------------------------------------------------- |
| `200`  | Success                                           |
| `400`  | Bad request - check your request parameters       |
| `401`  | Unauthorized - invalid or missing API key         |
| `404`  | Not found - the requested resource does not exist |
| `429`  | Too many requests - you have been rate-limited    |
| `500`  | Internal server error - contact Zeal support      |

## Resource groups

The API reference is organized into resource groups - Companies, Employees, Contractors, Employee Checks, Contractor Payments, Reports, Webhooks, and more. Browse the sidebar to explore each group and its endpoints.