{ "openapi": "3.1.0", "info": { "title": "Mercovi API", "version": "v1 (preview)", "description": "Clients, sites, waste profiles, jobs, containers, manifests, invoices and webhooks. The sandbox server answers with sample data and keeps nothing; use the sandbox key mk_test_sbx_Ridgeview7Hq2Lk4Wd9. Production keys and base URL are issued with your account. Reference: https://mercovi.com/developers/reference", "contact": { "name": "Mercovi", "email": "info@mercovi.com", "url": "https://mercovi.com/developers" } }, "servers": [ { "url": "https://mercovi.com/api/sandbox/v1", "description": "Sandbox" } ], "tags": [ { "name": "Clients", "description": "The organizations you serve: an HHW program, a plant or institution you collect from, or a laboratory. Sites, profiles, jobs and invoices all hang off a client." }, { "name": "Sites", "description": "A place you collect from: an event location, a plant's loading dock, a lab's stockroom. A client can have many." }, { "name": "Waste profiles", "description": "A characterized waste stream for a client: what it is, its waste codes and DOT description, and whether the receiving facility has approved it. Manifest lines are built from profiles." }, { "name": "Jobs", "description": "One piece of work: an HHW collection event, a commercial pickup, or a lab pack. A job has a client, a site, a date, a crew and containers; closing it writes the bill." }, { "name": "Containers", "description": "A drum, tote, box or cart on a job, from the moment it's opened until it ships. At a facility it carries a storage status: where it stands against the limit that applies to that container." }, { "name": "Manifests", "description": "A hazardous waste manifest built from a job's containers and profiles. Each manifest carries its EPA e-Manifest status, submission method and tracking number on the record. In the sandbox, tracking numbers are samples." }, { "name": "Invoices", "description": "The bill a closed job writes. Amounts are integers in cents." }, { "name": "Webhook endpoints", "description": "A URL of yours that Mercovi calls when something happens. Each delivery is signed so you can check it came from Mercovi." }, { "name": "Events", "description": "A record of something that happened. The same object is what a webhook delivers, and you can list recent events to catch up after downtime." } ], "paths": { "/clients": { "get": { "operationId": "clientsList", "summary": "List clients", "description": "Returns your clients, newest first. Scope: clients:read.", "tags": [ "Clients" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hhw_program", "commercial_industrial", "laboratory" ], "description": "Only clients of this kind." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." }, "example": "3" }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": "cli_2Rv8Ridgeview", "object": "client", "name": "Ridgeview County HHW program", "kind": "hhw_program", "epa_id": null, "billing_email": "hhw@ridgeview.example", "portal_enabled": true, "metadata": { "erp_id": "C-10233" }, "created_at": "2026-03-02T14:00:00Z", "updated_at": "2026-09-14T14:00:00Z" }, { "id": "cli_7Hd3Halden", "object": "client", "name": "Halden Manufacturing", "kind": "commercial_industrial", "epa_id": "OHD987654321", "billing_email": "ap@halden.example", "portal_enabled": true, "metadata": {}, "created_at": "2026-04-18T14:00:00Z", "updated_at": "2026-09-30T14:00:00Z" }, { "id": "cli_4Vl6Vantage", "object": "client", "name": "Vantage Laboratories", "kind": "laboratory", "epa_id": "NJR000123456", "billing_email": "ehs@vantagelabs.example", "portal_enabled": false, "metadata": {}, "created_at": "2026-05-07T14:00:00Z", "updated_at": "2026-08-21T14:00:00Z" } ], "has_more": true, "next_cursor": "cli_4Vl6Vantage" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "operationId": "clientsCreate", "summary": "Create a client", "description": "Adds a client. Send an Idempotency-Key so a retried request can't create it twice. Scope: clients:write.", "tags": [ "Clients" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A unique value per operation; a retry with the same key returns the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The client's name." }, "kind": { "type": "string", "enum": [ "hhw_program", "commercial_industrial", "laboratory" ], "description": "Which line the client is served under." }, "epa_id": { "type": "string", "description": "Twelve characters: two-letter state code, a letter, nine digits." }, "billing_email": { "type": "string", "description": "Where invoices go." }, "portal_enabled": { "type": "boolean", "description": "Invite the client to the client portal. Defaults to false." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." } }, "required": [ "name", "kind" ] }, "example": { "name": "Fairhaven Township", "kind": "hhw_program", "billing_email": "dpw@fairhaven.example", "portal_enabled": true, "metadata": { "erp_id": "C-20418" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" }, "example": { "id": "cli_7Gx2Sample0001", "object": "client", "epa_id": null, "billing_email": "dpw@fairhaven.example", "portal_enabled": true, "metadata": { "erp_id": "C-20418" }, "created_at": "2026-10-09T14:00:00Z", "updated_at": "2026-10-09T14:00:00Z", "name": "Fairhaven Township", "kind": "hhw_program" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/clients/{id}": { "get": { "operationId": "clientsRetrieve", "summary": "Retrieve a client", "description": "Returns one client. Scope: clients:read.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The client's ID, beginning cli_." }, "example": "cli_2Rv8Ridgeview" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" }, "example": { "id": "cli_2Rv8Ridgeview", "object": "client", "name": "Ridgeview County HHW program", "kind": "hhw_program", "epa_id": null, "billing_email": "hhw@ridgeview.example", "portal_enabled": true, "metadata": { "erp_id": "C-10233" }, "created_at": "2026-03-02T14:00:00Z", "updated_at": "2026-09-14T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "operationId": "clientsUpdate", "summary": "Update a client", "description": "Changes the fields you send and leaves the rest alone. Scope: clients:write.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The client's ID, beginning cli_." }, "example": "cli_2Rv8Ridgeview" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The client's name." }, "billing_email": { "type": "string", "description": "Where invoices go." }, "portal_enabled": { "type": "boolean", "description": "Turn client portal access on or off." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." } }, "required": [] }, "example": { "billing_email": "hhw-billing@ridgeview.example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Client" }, "example": { "id": "cli_2Rv8Ridgeview", "object": "client", "name": "Ridgeview County HHW program", "kind": "hhw_program", "epa_id": null, "billing_email": "hhw-billing@ridgeview.example", "portal_enabled": true, "metadata": { "erp_id": "C-10233" }, "created_at": "2026-03-02T14:00:00Z", "updated_at": "2026-10-09T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/sites": { "get": { "operationId": "sitesList", "summary": "List sites", "description": "Returns sites, newest first. Scope: sites:read.", "tags": [ "Sites" ], "parameters": [ { "name": "client", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this client's sites." }, "example": "cli_7Hd3Halden" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": "site_8Tn5HaldenDock", "object": "site", "client": "cli_7Hd3Halden", "name": "Plant 1 — shipping dock", "address": { "line1": "40 Foundry Rd", "line2": null, "city": "Halden", "state": "OH", "postal_code": "44101" }, "epa_id": "OHD987654321", "access_notes": "Dock 2. Hard hats past the yellow line.", "metadata": {}, "created_at": "2026-04-18T14:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "operationId": "sitesCreate", "summary": "Create a site", "description": "Adds a site to a client. Scope: sites:write.", "tags": [ "Sites" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A unique value per operation; a retry with the same key returns the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "string", "description": "The client's ID." }, "name": { "type": "string", "description": "What your crew calls the place." }, "address": { "type": "object", "additionalProperties": true, "description": "line1, city, state, postal_code are required." }, "access_notes": { "type": "string", "description": "Gate codes, dock hours, who to ask for." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." } }, "required": [ "client", "name", "address" ] }, "example": { "client": "cli_7Hd3Halden", "name": "Plant 2 — receiving dock", "address": { "line1": "41 Foundry Rd", "city": "Halden", "state": "OH", "postal_code": "44101" }, "access_notes": "Dock 4. Ask for EHS at the guard house." } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" }, "example": { "id": "site_7Gx2Sample0001", "object": "site", "epa_id": null, "access_notes": "Dock 4. Ask for EHS at the guard house.", "metadata": {}, "created_at": "2026-10-09T14:00:00Z", "client": "cli_7Hd3Halden", "name": "Plant 2 — receiving dock", "address": { "line1": "41 Foundry Rd", "city": "Halden", "state": "OH", "postal_code": "44101" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/sites/{id}": { "get": { "operationId": "sitesRetrieve", "summary": "Retrieve a site", "description": "Returns one site. Scope: sites:read.", "tags": [ "Sites" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The site's ID, beginning site_." }, "example": "site_4Kp1Fairgrounds" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" }, "example": { "id": "site_4Kp1Fairgrounds", "object": "site", "client": "cli_2Rv8Ridgeview", "name": "Ridgeview County Fairgrounds — Lot C", "address": { "line1": "1200 Fair St", "line2": null, "city": "Ridgeview", "state": "NJ", "postal_code": "07401" }, "epa_id": null, "access_notes": "Enter from Gate B.", "metadata": {}, "created_at": "2026-03-02T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "operationId": "sitesUpdate", "summary": "Update a site", "description": "Changes the fields you send. Scope: sites:write.", "tags": [ "Sites" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The site's ID, beginning site_." }, "example": "site_4Kp1Fairgrounds" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "What your crew calls the place." }, "access_notes": { "type": "string", "description": "Gate codes, dock hours, who to ask for." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." } }, "required": [] }, "example": { "access_notes": "Enter from Gate B. Traffic cones in the shed." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" }, "example": { "id": "site_4Kp1Fairgrounds", "object": "site", "client": "cli_2Rv8Ridgeview", "name": "Ridgeview County Fairgrounds — Lot C", "address": { "line1": "1200 Fair St", "line2": null, "city": "Ridgeview", "state": "NJ", "postal_code": "07401" }, "epa_id": null, "access_notes": "Enter from Gate B. Traffic cones in the shed.", "metadata": {}, "created_at": "2026-03-02T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/waste_profiles": { "get": { "operationId": "profilesList", "summary": "List waste profiles", "description": "Returns profiles, newest first. Scope: profiles:read.", "tags": [ "Waste profiles" ], "parameters": [ { "name": "client", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this client's profiles." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "submitted", "approved", "expired" ], "description": "Only profiles in this status." }, "example": "approved" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WasteProfile" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": "prof_9Wq2Paint", "object": "waste_profile", "client": "cli_2Rv8Ridgeview", "name": "Oil-based paint", "waste_codes": [ "D001" ], "dot_description": "UN1263, Waste Paint, 3, PG II", "status": "approved", "approved_by": "Ashfield Chemical Recovery", "created_at": "2026-03-04T14:00:00Z", "updated_at": "2026-03-20T14:00:00Z" }, { "id": "prof_6Ox4Oxidizer", "object": "waste_profile", "client": "cli_4Vl6Vantage", "name": "Lab pack — oxidizers", "waste_codes": [ "D001" ], "dot_description": "UN1479, Waste Oxidizing solid, n.o.s. (potassium permanganate), 5.1, PG II", "status": "approved", "approved_by": "Ashfield Chemical Recovery", "created_at": "2026-05-09T14:00:00Z", "updated_at": "2026-05-30T14:00:00Z" }, { "id": "prof_1Ac7Batteries", "object": "waste_profile", "client": "cli_2Rv8Ridgeview", "name": "Lead-acid batteries", "waste_codes": [ "D002", "D008" ], "dot_description": "UN2794, Batteries, wet, filled with acid, 8, PG III", "status": "approved", "approved_by": "Ashfield Chemical Recovery", "created_at": "2026-03-04T14:00:00Z", "updated_at": "2026-03-20T14:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "operationId": "profilesCreate", "summary": "Create a waste profile", "description": "Starts a profile in draft. Waste codes are checked against the federal and state code library. Scope: profiles:write.", "tags": [ "Waste profiles" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A unique value per operation; a retry with the same key returns the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "string", "description": "The client's ID." }, "name": { "type": "string", "description": "The stream's common name." }, "waste_codes": { "type": "array", "items": { "type": "string" }, "description": "One or more waste codes." }, "dot_description": { "type": "string", "description": "The proper shipping name and hazard class." } }, "required": [ "client", "name", "waste_codes" ] }, "example": { "client": "cli_7Hd3Halden", "name": "Spent parts-washer solvent", "waste_codes": [ "D001", "F002" ], "dot_description": "UN1993, Waste Flammable liquid, n.o.s., 3, PG II" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WasteProfile" }, "example": { "id": "prof_7Gx2Sample0001", "object": "waste_profile", "dot_description": "UN1993, Waste Flammable liquid, n.o.s., 3, PG II", "status": "draft", "approved_by": null, "created_at": "2026-10-09T14:00:00Z", "updated_at": "2026-10-09T14:00:00Z", "client": "cli_7Hd3Halden", "name": "Spent parts-washer solvent", "waste_codes": [ "D001", "F002" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/waste_profiles/{id}": { "get": { "operationId": "profilesRetrieve", "summary": "Retrieve a waste profile", "description": "Returns one profile. Scope: profiles:read.", "tags": [ "Waste profiles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The profile's ID, beginning prof_." }, "example": "prof_9Wq2Paint" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WasteProfile" }, "example": { "id": "prof_9Wq2Paint", "object": "waste_profile", "client": "cli_2Rv8Ridgeview", "name": "Oil-based paint", "waste_codes": [ "D001" ], "dot_description": "UN1263, Waste Paint, 3, PG II", "status": "approved", "approved_by": "Ashfield Chemical Recovery", "created_at": "2026-03-04T14:00:00Z", "updated_at": "2026-03-20T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "operationId": "profilesUpdate", "summary": "Update a waste profile", "description": "Changes a profile in draft. An approved profile is changed by creating a new one. Scope: profiles:write.", "tags": [ "Waste profiles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The profile's ID, beginning prof_." }, "example": "prof_3Lb8Solvent" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The stream's common name." }, "waste_codes": { "type": "array", "items": { "type": "string" }, "description": "Replaces the list." }, "dot_description": { "type": "string", "description": "The proper shipping name and hazard class." } }, "required": [] }, "example": { "waste_codes": [ "D001", "F003", "F005" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WasteProfile" }, "example": { "id": "prof_3Lb8Solvent", "object": "waste_profile", "client": "cli_7Hd3Halden", "name": "Spent degreasing solvent", "waste_codes": [ "D001", "F003", "F005" ], "dot_description": "UN1993, Waste Flammable liquid, n.o.s. (xylene, acetone), 3, PG II", "status": "submitted", "approved_by": null, "created_at": "2026-09-22T14:00:00Z", "updated_at": "2026-10-09T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/jobs": { "get": { "operationId": "jobsList", "summary": "List jobs", "description": "Returns jobs, soonest first. Scope: jobs:read.", "tags": [ "Jobs" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hhw_event", "ci_pickup", "lab_pack" ], "description": "Only jobs of this type." }, "example": "hhw_event" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "scheduled", "in_progress", "closed", "billed", "cancelled" ], "description": "Only jobs in this status." } }, { "name": "client", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this client's jobs." } }, { "name": "scheduled_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "description": "On or after this date, YYYY-MM-DD." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "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 } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "operationId": "jobsCreate", "summary": "Create a job", "description": "Creates a job in draft. Add a date and window and it moves to scheduled. Scope: jobs:write.", "tags": [ "Jobs" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A unique value per operation; a retry with the same key returns the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "hhw_event", "ci_pickup", "lab_pack" ], "description": "What kind of work it is." }, "client": { "type": "string", "description": "The client's ID." }, "site": { "type": "string", "description": "The site's ID." }, "scheduled_for": { "type": "string", "format": "date", "description": "The date, YYYY-MM-DD." }, "window": { "type": "object", "additionalProperties": true, "description": "start and end, HH:MM." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." } }, "required": [ "type", "client", "site" ] }, "example": { "type": "ci_pickup", "client": "cli_7Hd3Halden", "site": "site_8Tn5HaldenDock", "scheduled_for": "2026-11-04", "window": { "start": "08:00", "end": "12:00" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_7Gx2Sample0001", "object": "job", "status": "scheduled", "scheduled_for": "2026-11-04", "window": { "start": "08:00", "end": "12:00" }, "crew": [], "container_count": 0, "invoice": null, "metadata": {}, "created_at": "2026-10-09T14:00:00Z", "updated_at": "2026-10-09T14:00:00Z", "type": "ci_pickup", "client": "cli_7Hd3Halden", "site": "site_8Tn5HaldenDock" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/jobs/{id}": { "get": { "operationId": "jobsRetrieve", "summary": "Retrieve a job", "description": "Returns one job with its crew. Scope: jobs:read.", "tags": [ "Jobs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The job's ID, beginning job_." }, "example": "job_5Ev2Ridgeview0912" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "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" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "operationId": "jobsUpdate", "summary": "Update a job", "description": "Reschedules or annotates a job that isn't closed. Scope: jobs:write.", "tags": [ "Jobs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The job's ID, beginning job_." }, "example": "job_6Cp4HaldenNov" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_for": { "type": "string", "format": "date", "description": "The new date." }, "window": { "type": "object", "additionalProperties": true, "description": "start and end, HH:MM." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." } }, "required": [] }, "example": { "window": { "start": "09:00", "end": "13:00" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_6Cp4HaldenNov", "object": "job", "type": "ci_pickup", "client": "cli_7Hd3Halden", "site": "site_8Tn5HaldenDock", "status": "scheduled", "scheduled_for": "2026-11-04", "window": { "start": "09:00", "end": "13:00" }, "crew": [ { "name": "Jordan Kim", "role": "Driver", "accepted": true } ], "container_count": 4, "invoice": null, "metadata": { "po": "HM-4471" }, "created_at": "2026-09-30T14:00:00Z", "updated_at": "2026-10-09T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/jobs/{id}/cancel": { "post": { "operationId": "jobsCancel", "summary": "Cancel a job", "description": "Cancels a job that hasn't started. The crew is told; nothing is billed. Scope: jobs:write.", "tags": [ "Jobs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The job's ID, beginning job_." }, "example": "job_6Cp4HaldenNov" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A unique value per operation; a retry with the same key returns the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Shown to the crew and on the job's history." } }, "required": [] }, "example": { "reason": "Client rescheduled to December." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_6Cp4HaldenNov", "object": "job", "type": "ci_pickup", "client": "cli_7Hd3Halden", "site": "site_8Tn5HaldenDock", "status": "cancelled", "scheduled_for": "2026-11-04", "window": { "start": "08:00", "end": "12:00" }, "crew": [ { "name": "Jordan Kim", "role": "Driver", "accepted": true } ], "container_count": 4, "invoice": null, "metadata": { "po": "HM-4471" }, "created_at": "2026-09-30T14:00:00Z", "updated_at": "2026-10-09T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/containers": { "get": { "operationId": "containersList", "summary": "List containers", "description": "Returns containers, newest first. Scope: containers:read.", "tags": [ "Containers" ], "parameters": [ { "name": "job", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this job's containers." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "full", "received", "consolidated", "shipped" ], "description": "Only containers in this status." } }, { "name": "storage_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "within_limit", "approaching_limit", "at_limit" ], "description": "Only containers with this storage status." }, "example": "approaching_limit" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Container" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": "cont_7Pt2Paint", "object": "container", "job": "job_5Ev2Ridgeview0912", "profile": "prof_9Wq2Paint", "kind": "Cubic-yard box", "status": "received", "weight_lb": 1140, "storage_status": "approaching_limit", "received_at": "2026-09-12T14:00:00Z", "created_at": "2026-09-12T14:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/containers/{id}": { "get": { "operationId": "containersRetrieve", "summary": "Retrieve a container", "description": "Returns one container. Scope: containers:read.", "tags": [ "Containers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The container's ID, beginning cont_." }, "example": "cont_1Dr0Flammables" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Container" }, "example": { "id": "cont_1Dr0Flammables", "object": "container", "job": "job_3Lp9VantageOct", "profile": null, "kind": "55-gal fiber drum", "status": "full", "weight_lb": 210, "storage_status": null, "received_at": null, "created_at": "2026-10-08T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "patch": { "operationId": "containersUpdate", "summary": "Update a container", "description": "Records a weight or moves the container to its next status. Scope: containers:write.", "tags": [ "Containers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The container's ID, beginning cont_." }, "example": "cont_3Dr0Oxidizers" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "full", "received", "consolidated", "shipped" ], "description": "The next status. Moves forward only." }, "weight_lb": { "type": "integer", "description": "Net weight in pounds." } }, "required": [] }, "example": { "status": "full", "weight_lb": 85 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Container" }, "example": { "id": "cont_3Dr0Oxidizers", "object": "container", "job": "job_3Lp9VantageOct", "profile": "prof_6Ox4Oxidizer", "kind": "30-gal metal drum", "status": "full", "weight_lb": 85, "storage_status": null, "received_at": null, "created_at": "2026-10-08T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/manifests": { "get": { "operationId": "manifestsList", "summary": "List manifests", "description": "Returns manifests, newest first. Scope: manifests:read.", "tags": [ "Manifests" ], "parameters": [ { "name": "job", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this job's manifests." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "ready_for_signature", "submitted", "signed", "corrected" ], "description": "Only manifests in this status." }, "example": "signed" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Manifest" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": "man_0Mt1Ridgeview", "object": "manifest", "job": "job_5Ev2Ridgeview0912", "manifest_tracking_number": "000123456ELC", "status": "signed", "submission_type": "Hybrid", "generator": { "name": "Ridgeview County HHW program", "epa_id": "NJD987654321" }, "designated_facility": { "name": "Ashfield Chemical Recovery", "epa_id": "OHD000111222" }, "lines": [ { "profile": "prof_9Wq2Paint", "dot_description": "UN1263, Waste Paint, 3, PG II", "waste_codes": [ "D001" ], "containers": 1, "quantity": 1140, "unit": "P" }, { "profile": "prof_1Ac7Batteries", "dot_description": "UN2794, Batteries, wet, filled with acid, 8, PG III", "waste_codes": [ "D002", "D008" ], "containers": 1, "quantity": 620, "unit": "P" } ], "created_at": "2026-09-12T14:00:00Z", "updated_at": "2026-09-13T14:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "operationId": "manifestsCreate", "summary": "Create a manifest", "description": "Builds a draft manifest from a job: one line per profile, waste codes from the contents. Scope: manifests:write.", "tags": [ "Manifests" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A unique value per operation; a retry with the same key returns the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "string", "description": "The job's ID." }, "designated_facility": { "type": "string", "description": "The receiving facility's EPA ID." }, "submission_type": { "type": "string", "enum": [ "FullElectronic", "Hybrid", "DataImage5Copy", "Image" ], "description": "Defaults to Hybrid." } }, "required": [ "job", "designated_facility" ] }, "example": { "job": "job_6Cp4HaldenNov", "designated_facility": "OHD000111222", "submission_type": "Hybrid" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" }, "example": { "id": "man_7Gx2Sample0001", "object": "manifest", "job": "job_6Cp4HaldenNov", "manifest_tracking_number": null, "status": "draft", "submission_type": "Hybrid", "generator": { "name": "Halden Manufacturing", "epa_id": "OHD987654321" }, "designated_facility": { "name": "Ashfield Chemical Recovery", "epa_id": "OHD000111222" }, "lines": [], "created_at": "2026-10-09T14:00:00Z", "updated_at": "2026-10-09T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/manifests/{id}": { "get": { "operationId": "manifestsRetrieve", "summary": "Retrieve a manifest", "description": "Returns one manifest with its lines. Scope: manifests:read.", "tags": [ "Manifests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The manifest's ID, beginning man_." }, "example": "man_0Mt1Ridgeview" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" }, "example": { "id": "man_0Mt1Ridgeview", "object": "manifest", "job": "job_5Ev2Ridgeview0912", "manifest_tracking_number": "000123456ELC", "status": "signed", "submission_type": "Hybrid", "generator": { "name": "Ridgeview County HHW program", "epa_id": "NJD987654321" }, "designated_facility": { "name": "Ashfield Chemical Recovery", "epa_id": "OHD000111222" }, "lines": [ { "profile": "prof_9Wq2Paint", "dot_description": "UN1263, Waste Paint, 3, PG II", "waste_codes": [ "D001" ], "containers": 1, "quantity": 1140, "unit": "P" }, { "profile": "prof_1Ac7Batteries", "dot_description": "UN2794, Batteries, wet, filled with acid, 8, PG III", "waste_codes": [ "D002", "D008" ], "containers": 1, "quantity": 620, "unit": "P" } ], "created_at": "2026-09-12T14:00:00Z", "updated_at": "2026-09-13T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/invoices": { "get": { "operationId": "invoicesList", "summary": "List invoices", "description": "Returns invoices, newest first. Scope: invoices:read.", "tags": [ "Invoices" ], "parameters": [ { "name": "client", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this client's invoices." } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "open", "paid", "void" ], "description": "Only invoices in this status." }, "example": "open" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": "inv_1040Ridgeview", "object": "invoice", "number": "1040", "client": "cli_2Rv8Ridgeview", "jobs": [ "job_5Ev2Ridgeview0912" ], "status": "open", "currency": "usd", "amount_due": 1846500, "amount_paid": 0, "due_date": "2026-10-15", "created_at": "2026-09-15T14:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/invoices/{id}": { "get": { "operationId": "invoicesRetrieve", "summary": "Retrieve an invoice", "description": "Returns one invoice. Scope: invoices:read.", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The invoice's ID, beginning inv_." }, "example": "inv_1040Ridgeview" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "example": { "id": "inv_1040Ridgeview", "object": "invoice", "number": "1040", "client": "cli_2Rv8Ridgeview", "jobs": [ "job_5Ev2Ridgeview0912" ], "status": "open", "currency": "usd", "amount_due": 1846500, "amount_paid": 0, "due_date": "2026-10-15", "created_at": "2026-09-15T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/webhook_endpoints": { "get": { "operationId": "webhooksList", "summary": "List webhook endpoints", "description": "Returns your endpoints. Scope: webhooks:read.", "tags": [ "Webhook endpoints" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": "we_4Hk9Erp", "object": "webhook_endpoint", "url": "https://erp.example.com/hooks/mercovi", "events": [ "manifest.signed", "invoice.sent", "invoice.paid" ], "secret": null, "enabled": true, "created_at": "2026-09-01T14:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "operationId": "webhooksCreate", "summary": "Create a webhook endpoint", "description": "Registers a URL. The response carries the signing secret — store it; it isn't shown again. Scope: webhooks:write.", "tags": [ "Webhook endpoints" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A unique value per operation; a retry with the same key returns the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "An HTTPS URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types, or [\"*\"]." } }, "required": [ "url", "events" ] }, "example": { "url": "https://erp.example.com/hooks/mercovi", "events": [ "manifest.signed", "invoice.sent" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "id": "we_7Gx2Sample0001", "object": "webhook_endpoint", "enabled": true, "secret": "whsec_7Gx2Sample00017Gx2Sample0001", "created_at": "2026-10-09T14:00:00Z", "url": "https://erp.example.com/hooks/mercovi", "events": [ "manifest.signed", "invoice.sent" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/webhook_endpoints/{id}": { "delete": { "operationId": "webhooksDelete", "summary": "Delete a webhook endpoint", "description": "Stops deliveries and removes the endpoint. Scope: webhooks:write.", "tags": [ "Webhook endpoints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The endpoint's ID, beginning we_." }, "example": "we_4Hk9Erp" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean" } } }, "example": { "id": "we_4Hk9Erp", "object": "webhook_endpoint", "deleted": true } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/events": { "get": { "operationId": "eventsList", "summary": "List events", "description": "Returns recent events, newest first. Scope: events:read.", "tags": [ "Events" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this event type." }, "example": "manifest.signed" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many records to return, 1 to 100. Defaults to 25." } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string", "description": "A record ID. Returns the page after it — pass the next_cursor of the previous page." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": "evt_8Qs1ManSigned", "object": "event", "type": "manifest.signed", "data": { "object": { "id": "man_0Mt1Ridgeview", "object": "manifest", "job": "job_5Ev2Ridgeview0912", "manifest_tracking_number": "000123456ELC", "status": "signed", "submission_type": "Hybrid", "generator": { "name": "Ridgeview County HHW program", "epa_id": "NJD987654321" }, "designated_facility": { "name": "Ashfield Chemical Recovery", "epa_id": "OHD000111222" }, "lines": [ { "profile": "prof_9Wq2Paint", "dot_description": "UN1263, Waste Paint, 3, PG II", "waste_codes": [ "D001" ], "containers": 1, "quantity": 1140, "unit": "P" }, { "profile": "prof_1Ac7Batteries", "dot_description": "UN2794, Batteries, wet, filled with acid, 8, PG III", "waste_codes": [ "D002", "D008" ], "containers": 1, "quantity": 620, "unit": "P" } ], "created_at": "2026-09-12T14:00:00Z", "updated_at": "2026-09-13T14:00:00Z" } }, "created_at": "2026-09-13T14:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } }, "/events/{id}": { "get": { "operationId": "eventsRetrieve", "summary": "Retrieve an event", "description": "Returns one event. Scope: events:read.", "tags": [ "Events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The event's ID, beginning evt_." }, "example": "evt_8Qs1ManSigned" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_8Qs1ManSigned", "object": "event", "type": "manifest.signed", "data": { "object": { "id": "man_0Mt1Ridgeview", "object": "manifest", "job": "job_5Ev2Ridgeview0912", "manifest_tracking_number": "000123456ELC", "status": "signed", "submission_type": "Hybrid", "generator": { "name": "Ridgeview County HHW program", "epa_id": "NJD987654321" }, "designated_facility": { "name": "Ashfield Chemical Recovery", "epa_id": "OHD000111222" }, "lines": [ { "profile": "prof_9Wq2Paint", "dot_description": "UN1263, Waste Paint, 3, PG II", "waste_codes": [ "D001" ], "containers": 1, "quantity": 1140, "unit": "P" }, { "profile": "prof_1Ac7Batteries", "dot_description": "UN2794, Batteries, wet, filled with acid, 8, PG III", "waste_codes": [ "D002", "D008" ], "containers": 1, "quantity": 620, "unit": "P" } ], "created_at": "2026-09-12T14:00:00Z", "updated_at": "2026-09-13T14:00:00Z" } }, "created_at": "2026-09-13T14:00:00Z" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearer": [] } ] } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string", "enum": [ "parameter_missing", "parameter_invalid", "api_key_missing", "api_key_invalid", "scope_missing", "resource_missing", "method_not_allowed", "idempotency_conflict", "state_invalid", "rate_limited", "api_error" ] }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "type", "code", "message" ] } } }, "Client": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the client, beginning cli_." }, "object": { "type": "string", "description": "Always client." }, "name": { "type": "string", "description": "The client's name as it appears on documents." }, "kind": { "type": "string", "enum": [ "hhw_program", "commercial_industrial", "laboratory" ], "description": "Which line the client is served under. Drives the client portal's navigation." }, "epa_id": { "type": "string", "description": "The client's EPA ID number, when it is the generator of record." }, "billing_email": { "type": "string", "description": "Where invoices go." }, "portal_enabled": { "type": "boolean", "description": "Whether the client can sign in to the client portal." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed, ISO 8601 in UTC." } }, "required": [ "id", "name" ] }, "Site": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the site, beginning site_." }, "object": { "type": "string", "description": "Always site." }, "client": { "type": "string", "description": "The client's ID." }, "name": { "type": "string", "description": "What your crew calls the place." }, "address": { "type": "object", "additionalProperties": true, "description": "line1, line2, city, state, postal_code." }, "epa_id": { "type": "string", "description": "The site's own EPA ID, when it has one." }, "access_notes": { "type": "string", "description": "Gate codes, dock hours, who to ask for." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." } }, "required": [ "id", "client", "name" ] }, "WasteProfile": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the profile, beginning prof_." }, "object": { "type": "string", "description": "Always waste_profile." }, "client": { "type": "string", "description": "The client's ID." }, "name": { "type": "string", "description": "The stream's common name." }, "waste_codes": { "type": "array", "items": { "type": "string" }, "description": "Federal and state waste codes, for example D001, F003." }, "dot_description": { "type": "string", "description": "The proper shipping name, hazard class, UN number and packing group." }, "status": { "type": "string", "enum": [ "draft", "submitted", "approved", "expired" ], "description": "Where the profile is in approval." }, "approved_by": { "type": "string", "description": "The receiving facility's name, once approved." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed, ISO 8601 in UTC." } }, "required": [ "id", "client", "name" ] }, "Job": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the job, beginning job_." }, "object": { "type": "string", "description": "Always job." }, "type": { "type": "string", "enum": [ "hhw_event", "ci_pickup", "lab_pack" ], "description": "What kind of work it is." }, "client": { "type": "string", "description": "The client's ID." }, "site": { "type": "string", "description": "The site's ID." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "in_progress", "closed", "billed", "cancelled" ], "description": "Where the job is." }, "scheduled_for": { "type": "string", "format": "date", "description": "The date of the work." }, "window": { "type": "object", "additionalProperties": true, "description": "start and end, local time, HH:MM." }, "crew": { "type": "array", "items": { "type": "object" }, "description": "Assigned staff: name, role, accepted." }, "container_count": { "type": "integer", "description": "Containers on the job so far." }, "invoice": { "type": "string", "description": "The invoice ID, once the job is billed." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 20 key-value pairs of your own, for example the record's ID in your system. Mercovi stores them and never reads them." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed, ISO 8601 in UTC." } }, "required": [ "id", "type", "client", "site" ] }, "Container": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the container, beginning cont_." }, "object": { "type": "string", "description": "Always container." }, "job": { "type": "string", "description": "The job's ID." }, "profile": { "type": "string", "description": "The waste profile in it." }, "kind": { "type": "string", "description": "Type and size, for example 55-gal steel drum." }, "status": { "type": "string", "enum": [ "open", "full", "received", "consolidated", "shipped" ], "description": "Where the container is." }, "weight_lb": { "type": "integer", "description": "Net weight in pounds, once weighed." }, "storage_status": { "type": "string", "enum": [ "within_limit", "approaching_limit", "at_limit" ], "description": "At a facility: where the container stands against the limit that applies to it. Null before receipt." }, "received_at": { "type": "string", "format": "date-time", "description": "When it was checked in at a facility." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." } }, "required": [ "id" ] }, "Manifest": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the manifest, beginning man_." }, "object": { "type": "string", "description": "Always manifest." }, "job": { "type": "string", "description": "The job's ID." }, "manifest_tracking_number": { "type": "string", "description": "The manifest tracking number: nine digits and three letters." }, "status": { "type": "string", "enum": [ "draft", "ready_for_signature", "submitted", "signed", "corrected" ], "description": "Where the manifest is." }, "submission_type": { "type": "string", "enum": [ "FullElectronic", "Hybrid", "DataImage5Copy", "Image" ], "description": "The EPA e-Manifest submission method." }, "generator": { "type": "object", "additionalProperties": true, "description": "name and epa_id." }, "designated_facility": { "type": "object", "additionalProperties": true, "description": "name and epa_id." }, "lines": { "type": "array", "items": { "type": "object" }, "description": "One per waste: profile, dot_description, waste_codes, containers, quantity, unit." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the record last changed, ISO 8601 in UTC." } }, "required": [ "id" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the invoice, beginning inv_." }, "object": { "type": "string", "description": "Always invoice." }, "number": { "type": "string", "description": "The invoice number on the document." }, "client": { "type": "string", "description": "The client's ID." }, "jobs": { "type": "array", "items": { "type": "string" }, "description": "The job IDs it bills." }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void" ], "description": "Where the invoice is." }, "currency": { "type": "string", "description": "Three-letter ISO code, lowercase." }, "amount_due": { "type": "integer", "description": "Total in cents." }, "amount_paid": { "type": "integer", "description": "Paid so far, in cents." }, "due_date": { "type": "string", "format": "date", "description": "When payment is due." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." } }, "required": [ "id" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the endpoint, beginning we_." }, "object": { "type": "string", "description": "Always webhook_endpoint." }, "url": { "type": "string", "description": "An HTTPS URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types to send, or [\"*\"] for all." }, "secret": { "type": "string", "description": "The signing secret, beginning whsec_. Returned once, on create." }, "enabled": { "type": "boolean", "description": "Whether deliveries are on." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." } }, "required": [ "id", "url" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the event, beginning evt_." }, "object": { "type": "string", "description": "Always event." }, "type": { "type": "string", "enum": [ "job.created", "job.scheduled", "job.closed", "staff.accepted", "container.received", "container.storage_status_changed", "manifest.ready_for_signature", "manifest.signed", "profile.approved", "profile.expiring", "invoice.sent", "invoice.paid" ], "description": "What happened." }, "data": { "type": "object", "additionalProperties": true, "description": "object: the record as it was right after the change." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created, ISO 8601 in UTC." } }, "required": [ "id" ] } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API key. Sandbox keys begin mk_test_; live keys begin mk_live_." } } } }