Mercovi API · v1 Preview

Build on the record your crews already keep.

Clients, sites, jobs, containers, manifests and invoices, over a REST API that speaks JSON, with webhooks when something changes. Every endpoint answers in the sandbox today. Production access is by request, set up with you during onboarding.

Read the API reference Open the console

GET /v1/jobs

curl "https://mercovi.com/api/sandbox/v1/jobs?type=hhw_event" \
  -H "Authorization: Bearer mk_test_sbx_Ridgeview7Hq2Lk4Wd9"

Sends this request to the sandbox from your browser.

Response200

{
  "object": "list",
  "data": [
    {
      "id": "job_5Ev2Ridgeview0912",
      "object": "job",
      "type": "hhw_event",
      "client": "cli_2Rv8Ridgeview",
      "site": "site_4Kp1Fairgrounds",
      "status": "billed",
      "scheduled_for": "2026-09-12",
      "window": {
        "start": "08:00",
        "end": "14:00"
      },
      "crew": [
        {
          "name": "Dana Ortiz",
          "role": "Site lead",
          "accepted": true
        },
        {
          "name": "Sam Patel",
          "role": "Chemist",
          "accepted": true
        },
        {
          "name": "Lee Moreno",
          "role": "Technician",
          "accepted": true
        }
      ],
      "container_count": 18,
      "invoice": "inv_1040Ridgeview",
      "metadata": {},
      "created_at": "2026-07-01T14:00:00Z",
      "updated_at": "2026-09-15T14:00:00Z"
    },
    {
      "id": "job_8Wb2Westbrook1017",
      "object": "job",
      "type": "hhw_event",
      "client": "cli_9Wb1Westbrook",
      "site": "site_4Kp1Fairgrounds",
      "status": "scheduled",
      "scheduled_for": "2026-10-17",
      "window": {
        "start": "09:00",
        "end": "13:00"
      },
      "crew": [
        {
          "name": "Dana Ortiz",
          "role": "Site lead",
          "accepted": true
        }
      ],
      "container_count": 0,
      "invoice": null,
      "metadata": {},
      "created_at": "2026-08-12T14:00:00Z",
      "updated_at": "2026-10-01T14:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

A live call to the sandbox. Press Run.

Your first call in a minute.

No sign-up for the sandbox. Copy the key, make a request, read the answer.

Take the sandbox key
It opens the sandbox: sample records, every endpoint, nothing kept. It's already in every code sample on these pages.
mk_test_sbx_Ridgeview7Hq2Lk4Wd9
Make a call
Any language that speaks HTTPS works. The samples use each language's own HTTP client, so there's nothing to install.
Open the console
Ask for production
Production keys are issued per account, scoped to what your integration needs. We set them up with you during onboarding.
Book a call

What the API covers.

The same records the app keeps, in the same words. Each area links to its endpoints in the reference. For the tools Mercovi connects to for you, see integrations.

Clients and sites

Who you serve and where

Programs, plants and labs, with every location you collect from.

Clients and sites

Waste profiles

What's in the drum

Waste codes, the DOT description and approval status, checked against the code library.

Waste profiles

Jobs and containers

The work itself

Events, pickups and lab packs; their crews; and every container with its storage status.

Jobs

Manifests

The paperwork, as data

Lines built from profiles, with the e-Manifest status, submission method and tracking number on the record.

Manifests

Invoices

What closing a job billed

Amounts in cents, status, due date and the jobs behind each invoice.

Invoices

Webhooks and events

Told when it happens

Signed deliveries when a manifest is signed, an invoice is sent or a container's storage status moves.

Webhooks

Sandbox now. Production by request.

Two environments, one API. Code written against the sandbox runs against production by changing the base URL and the key.

Sandbox

Who: Anyone. No sign-up.
Key: The public sandbox key, beginning mk_test_.
Data: Sample records — Ridgeview County, Halden Manufacturing, Vantage Laboratories.
Writes: Checked and answered like production, then dropped. Nothing is kept.
Base URL: https://mercovi.com/api/sandbox/v1

Production

Who: Mercovi customers, set up during onboarding.
Key: One per integration, beginning mk_live_, with the scopes you choose.
Data: Your own records, and only yours.
Writes: Kept, shown in the app straight away, and sent to your webhooks.
Base URL: Issued with your keys.
Stage: Preview — set up per customer, by request.

Built the way you'd expect.

Conventions you've used with other APIs, so there's little new to learn.

REST and JSON

Resource URLs, standard methods — GET, POST, PATCH, DELETE — JSON bodies and HTTP status codes. Times are ISO 8601 in UTC; money is an integer in cents.

Introduction

Keys with scopes

Bearer keys over HTTPS. Each production key carries only the scopes its integration needs, such as manifests:read, and can be revoked on its own.

Authentication

Safe retries

Send an Idempotency-Key with a POST and a retried request returns the first result instead of creating a second record.

Idempotency

Cursor pagination

Lists return data, has_more and next_cursor. Pass the cursor back as starting_after for the next page.

Pagination

One error shape

Every error has a type, a machine-readable code, a plain message, the param at fault and a request_id to quote to us.

Errors

Signed webhooks

Each delivery carries a Mercovi-Signature header: an HMAC-SHA256 of the timestamp and body, keyed by your endpoint's secret.

Webhooks

Versioned by path

/v1 stays compatible. New fields and event types can arrive at any time; anything that would break a client ships as a new version.

Versioning

OpenAPI 3.1

The whole API as one OpenAPI file. Import it into Postman or Insomnia, or generate a client in the language you use.

Download openapi.json

Questions developers ask

Is the Mercovi API available today?

The API is in preview. The sandbox is open to anyone and answers every endpoint in the reference with sample data. Production access is set up with each customer during onboarding, with keys scoped to what the integration needs. Endpoints and fields may still change before general availability, and key holders hear about changes first.

Do I need a Mercovi SDK?

No. The API is plain HTTPS and JSON, so any language's own HTTP client works. The samples on these pages are written that way in cURL, Python, Node.js, Ruby, Java, Go, PHP and C#. If you prefer a typed client, generate one from the OpenAPI file with the generator your team already uses.

Can I use Postman or Insomnia?

Yes. Download the OpenAPI file and import it into Postman, Insomnia or any tool that reads OpenAPI 3.1. Set the bearer token to the sandbox key and every request runs against the sandbox. The console on this site does the same in your browser, with the code for each request in eight languages.

Do I need to build my own integrations?

Often you won't need to. Mercovi connects the accounting, payment, fleet, inventory and crew tools contractors already run during onboarding, without code on your side. The integrations page lists them by job. Build on the API when you need something those connections don't cover, such as your own ERP, a data warehouse or an in-house system.

What data never goes through the API?

Social Security numbers, bank account details, drug and alcohol testing records and medical information stay out of the API and out of webhooks. Those stay inside the app, behind its own permissions. Everything the API returns belongs to the account the key was issued to; a key can never read another customer's records.

How do I get production keys?

Book a call or write to info@mercovi.com and tell us what you're connecting — an ERP, a billing system, a data warehouse. Production keys are issued per account during onboarding, one per integration, with only the scopes it needs. You can revoke any key without touching the others.

Ready to connect for real?

Tell us what you're connecting and we'll set up production keys with the scopes it needs.

Book a call Email info@mercovi.com