_Mercovi API preview: clients, jobs, containers, manifests and invoices over REST, with signed webhooks. Open sandbox; production by request._ # 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. ## Your first call in a minute. No sign-up for the sandbox. Copy the key, make a request, read the answer. 1. **Take the sandbox key.** It opens the sandbox: sample records, every endpoint, nothing kept. It's already in every code sample on these pages. 2. **Make a call.** Any language that speaks HTTPS works. The samples use each language's own HTTP client, so there's nothing to install. 3. **Ask for production.** Production keys are issued per account, scoped to what your integration needs. We set them up with you during onboarding. Sandbox base URL: `https://mercovi.com/api/sandbox/v1`. Sandbox key: `mk_test_sbx_Ridgeview7Hq2Lk4Wd9`. ## 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](/integrations). - Clients and sites — **Who you serve and where** Programs, plants and labs, with every location you collect from. [Clients and sites](/developers/reference#clients) - Waste profiles — **What's in the drum** Waste codes, the DOT description and approval status, checked against the code library. [Waste profiles](/developers/reference#profiles) - Jobs and containers — **The work itself** Events, pickups and lab packs; their crews; and every container with its storage status. [Jobs](/developers/reference#jobs) - Manifests — **The paperwork, as data** Lines built from profiles, with the e-Manifest status, submission method and tracking number on the record. [Manifests](/developers/reference#manifests) - Invoices — **What closing a job billed** Amounts in cents, status, due date and the jobs behind each invoice. [Invoices](/developers/reference#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](/developers/reference#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](/developers/reference#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](/developers/reference#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](/developers/reference#idempotency) ### Cursor pagination Lists return `data`, `has_more` and `next_cursor`. Pass the cursor back as `starting_after` for the next page. [Pagination](/developers/reference#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](/developers/reference#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](/developers/reference#webhook-signatures) ### 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](/developers/reference#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](/developers/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](/developers/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](/developers/openapi.json) with the generator your team already uses. ### Can I use Postman or Insomnia? Yes. Download the [OpenAPI file](/developers/openapi.json) 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](/developers/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](/integrations) 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](/security). 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](/demo?from=developers) or write to [info@mercovi.com](mailto: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](/demo?from=developers) [Email info@mercovi.com](mailto:info@mercovi.com?subject=Mercovi%20API%20access)