{ "openapi": "3.1.0", "info": { "title": "C2K Legacy API", "version": "1.0.0", "description": "Get instant truckload quotes, book freight, track shipments, and exchange EDI X12 documents with C2K Legacy.\n\n**Authentication.** Send `Authorization: Bearer `. Create keys in the customer portal (API access). Live keys start with `c2k_live_`; **test keys start with `c2k_test_`** and use an isolated sandbox: nothing is booked for real, no one at C2K Legacy is notified, and you can simulate the whole lifecycle (see the `/test` endpoints). Limit: 120 requests per minute per key.\n\n**Webhooks.** Register one HTTPS URL in the portal. We POST signed JSON (`X-C2K-Signature: sha256=HMAC(secret, timestamp + \".\" + body)`, `X-C2K-Timestamp`, `X-C2K-Event`). Test-key activity is delivered with `X-C2K-Test: true` and `\"test\": true`.\n\n**EDI.** X12 004010 over three transports: HTTPS (`POST /api/v1/edi/204`), SFTP (drop 204 files in `/in`, collect 997/990/214/210 from `/out`), and AS2 (`POST /as2`, signed MDN). Sandbox/test accounts exist for each. An interchange with ISA15 = `T` sent to a live account is rejected, not booked.\n\nMoney is in US dollars. Dates are `YYYY-MM-DD`. Errors are `{ \"error\": \"message\" }`." }, "servers": [ { "url": "https://www.c2klegacy.com", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Quotes" }, { "name": "Bookings" }, { "name": "Shipments" }, { "name": "EDI" }, { "name": "Test mode", "description": "Only with a c2k_test_ key." }, { "name": "Carrier tracking" } ], "paths": { "/api/v1/quotes": { "post": { "tags": [ "Quotes" ], "summary": "Get an instant quote", "description": "Applies your contract rates when you have them. Up to 6 extra stops. Returns 503 if instant quotes are switched off (test keys still work).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Lane or weight needs a manual quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit: 120 requests per minute per key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Instant quotes unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/quotes/{ref}": { "get": { "tags": [ "Quotes" ], "summary": "Fetch a quote", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Quote reference, e.g. Q-1A2B3C4D" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings": { "post": { "tags": [ "Bookings" ], "summary": "Book a load", "description": "Either book a quote (`quote_ref`) or send the lane details and we price and book in one step. The booking is `pending` until C2K Legacy accepts or declines (webhook `booking.accepted` / `booking.declined`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Quote expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Bookings" ], "summary": "List your bookings (latest 100)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/{ref}": { "get": { "tags": [ "Bookings" ], "summary": "Fetch a booking by C2K Legacy reference or your own customer_ref", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking reference or your customer_ref" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Booking" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments": { "get": { "tags": [ "Shipments" ], "summary": "List your shipments with status and events (latest 100)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" } } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/shipments/{ref}": { "get": { "tags": [ "Shipments" ], "summary": "Fetch one shipment with its full event history", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment reference, e.g. C2K2026000123" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/edi/204": { "post": { "tags": [ "EDI" ], "summary": "Send a 204 load tender", "description": "Body is the raw X12 004010 204 (`text/plain`, up to 100 KB). B2-04 is your unique tender ID (idempotency key). B2A 00 = original, 01 = cancel. We answer with a 997.", "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Tender received (997 accepted)", "headers": { "X-C2K-Booking": { "schema": { "type": "string" }, "description": "The booking reference for this tender." }, "X-C2K-Duplicate": { "schema": { "type": "string" }, "description": "true when this tender ID was already received (idempotent: no second booking)." }, "X-C2K-Test": { "schema": { "type": "string" }, "description": "true for test-key traffic." } }, "content": { "text/plain": { "schema": { "type": "string", "description": "X12 004010 997 Functional Acknowledgment" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Rejected (997 rejected, reason in X-C2K-Error)", "headers": { "X-C2K-Booking": { "schema": { "type": "string" }, "description": "The booking reference for this tender." }, "X-C2K-Duplicate": { "schema": { "type": "string" }, "description": "true when this tender ID was already received (idempotent: no second booking)." }, "X-C2K-Test": { "schema": { "type": "string" }, "description": "true for test-key traffic." } }, "content": { "text/plain": { "schema": { "type": "string", "description": "X12 004010 997 Functional Acknowledgment" } } } } } } }, "/api/v1/edi/990/{ref}": { "get": { "tags": [ "EDI" ], "summary": "Get the 990 response to a tender", "description": "409 while the tender is still pending.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking reference or your B2-04 tender ID" } ], "responses": { "200": { "description": "X12 990", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not accepted or declined yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/edi/214/{ref}": { "get": { "tags": [ "EDI" ], "summary": "Get a 214 shipment status message", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment reference" } ], "responses": { "200": { "description": "X12 214", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/edi/210/{ref}": { "get": { "tags": [ "EDI" ], "summary": "Get a 210 freight invoice", "description": "Available once the shipment is Delivered.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment reference" } ], "responses": { "200": { "description": "X12 210", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not delivered yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/test/bookings/{ref}/accept": { "post": { "tags": [ "Test mode" ], "summary": "Simulate C2K Legacy accepting a booking", "description": "Creates a test shipment, sends the `booking.accepted` webhook and (for EDI bookings) queues a 990.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Test booking reference" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean" }, "booking": { "$ref": "#/components/schemas/Booking" }, "shipment": { "$ref": "#/components/schemas/Shipment" } } } } } }, "403": { "description": "Needs a test key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/test/bookings/{ref}/decline": { "post": { "tags": [ "Test mode" ], "summary": "Simulate C2K Legacy declining a booking", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Test booking reference" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean" }, "booking": { "$ref": "#/components/schemas/Booking" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/test/shipments/{ref}/advance": { "post": { "tags": [ "Test mode" ], "summary": "Move a test shipment to its next status", "description": "Booked → Picked up → In transit → Out for delivery → Delivered. Each step sends the `shipment.status` webhook and queues a 214 (and a 210 on Delivered) for EDI bookings.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Test shipment reference" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "test": { "type": "boolean" }, "shipment": { "$ref": "#/components/schemas/Shipment" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already delivered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/test/reset": { "delete": { "tags": [ "Test mode" ], "summary": "Delete all your test data", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deleted": { "type": "integer" } } } } } } } } }, "/api/tracking/ingest": { "post": { "tags": [ "Carrier tracking" ], "summary": "Push a truck position (ELD / GPS feeds, carriers only)", "description": "Authenticate with a carrier **tracking key** (`c2kt_...`, created in the carrier portal). Send one point or up to 50 in `points`. The load must be assigned to that carrier and moving.", "security": [ { "trackingKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingPoint" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "ok": { "type": "boolean" }, "stored": { "type": "boolean" }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/as2": { "post": { "tags": [ "EDI" ], "summary": "AS2 receiving endpoint (RFC 4130)", "description": "Send a 204 as an AS2 message (S/MIME signed and/or encrypted with our certificate, `application/edi-x12` payload). Headers `AS2-From` (your configured AS2 ID), `AS2-To`, `Message-ID`, `Disposition-Notification-To`. We reply with a signed MDN synchronously. Download our public certificate at `/as2/cert.pem`. Configure your partner (AS2 ID + certificate) in the customer portal.", "security": [], "responses": { "200": { "description": "Signed MDN (processed or failed disposition in the body)" } } } } }, "webhooks": { "booking.accepted": { "post": { "summary": "A booking was accepted; a shipment now exists", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "booking.accepted" }, "created": { "type": "string", "format": "date-time" }, "test": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "responses": { "200": { "description": "Return any 2xx within 8 seconds" } } } }, "booking.declined": { "post": { "summary": "A booking was declined", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "booking.declined" }, "created": { "type": "string", "format": "date-time" }, "test": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Booking" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "shipment.status": { "post": { "summary": "A shipment changed status", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "shipment.status" }, "created": { "type": "string", "format": "date-time" }, "test": { "type": "boolean" }, "data": { "type": "object", "properties": { "shipment_ref": { "type": "string" }, "status": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "eta": { "type": [ "string", "null" ] }, "at": { "type": "string", "format": "date-time" } } } } } } } }, "responses": { "200": { "description": "OK" } } } }, "document.available": { "post": { "summary": "A document (BOL, POD...) was shared with you", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "document.available" }, "data": { "type": "object", "properties": { "shipment_ref": { "type": "string" }, "kind": { "type": "string" }, "filename": { "type": "string" }, "document_id": { "type": "integer" } } } } } } } }, "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "c2k_live_... (live) or c2k_test_... (sandbox)" }, "trackingKey": { "type": "http", "scheme": "bearer", "description": "c2kt_... carrier tracking key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Place": { "type": "object", "required": [ "city", "state" ], "properties": { "city": { "type": "string", "maxLength": 80 }, "state": { "type": "string", "description": "2-letter US state or Canadian province", "example": "ON" } } }, "QuoteRequest": { "type": "object", "required": [ "origin", "destination", "weight_lbs" ], "properties": { "origin": { "$ref": "#/components/schemas/Place" }, "destination": { "$ref": "#/components/schemas/Place" }, "stops": { "type": "array", "maxItems": 6, "items": { "$ref": "#/components/schemas/Place" }, "description": "Optional extra stops between pickup and delivery, in order." }, "equipment": { "type": "string", "default": "Dry van", "example": "Dry van" }, "weight_lbs": { "type": "integer", "example": 40000 }, "pickup_date": { "type": "string", "format": "date" }, "accessorials": { "type": "array", "items": { "type": "string" }, "example": [ "Liftgate" ] } } }, "Quote": { "type": "object", "properties": { "ref": { "type": "string" }, "origin": { "$ref": "#/components/schemas/Place" }, "destination": { "$ref": "#/components/schemas/Place" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } }, "equipment": { "type": "string" }, "weight_lbs": { "type": "integer" }, "pickup_date": { "type": [ "string", "null" ] }, "accessorials": { "type": "array", "items": { "type": "string" } }, "miles": { "type": "integer" }, "distance_method": { "type": "string", "enum": [ "road", "estimated" ] }, "currency": { "type": "string", "const": "USD" }, "breakdown": { "type": "object", "properties": { "linehaul": { "type": "number" }, "fuel_surcharge": { "type": "number" }, "accessorials": { "type": "number" }, "extra_stops": { "type": "number" } } }, "total": { "type": "number" }, "contract": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" } } }, "pricing_note": { "type": [ "string", "null" ] }, "valid_until": { "type": "string", "format": "date-time" }, "expired": { "type": "boolean" }, "test": { "type": "boolean", "description": "true for sandbox quotes" } } }, "BookingRequest": { "type": "object", "description": "Provide `quote_ref`, or origin/destination/equipment/weight_lbs.", "properties": { "quote_ref": { "type": "string" }, "origin": { "$ref": "#/components/schemas/Place" }, "destination": { "$ref": "#/components/schemas/Place" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } }, "equipment": { "type": "string" }, "weight_lbs": { "type": "integer" }, "pickup_date": { "type": "string", "format": "date" }, "delivery_date": { "type": "string", "format": "date" }, "commodity": { "type": "string" }, "customer_ref": { "type": "string", "description": "Your PO / load ID" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "notes": { "type": "string" }, "accessorials": { "type": "array", "items": { "type": "string" } } } }, "Booking": { "type": "object", "properties": { "ref": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "declined" ] }, "source": { "type": "string", "enum": [ "web", "api", "edi" ] }, "quote_ref": { "type": [ "string", "null" ] }, "shipment_ref": { "type": [ "string", "null" ] }, "origin": { "$ref": "#/components/schemas/Place" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } }, "destination": { "$ref": "#/components/schemas/Place" }, "equipment": { "type": "string" }, "weight_lbs": { "type": "integer" }, "pickup_date": { "type": [ "string", "null" ] }, "delivery_date": { "type": [ "string", "null" ] }, "commodity": { "type": [ "string", "null" ] }, "customer_ref": { "type": [ "string", "null" ] }, "rate": { "type": "number" }, "currency": { "type": "string", "const": "USD" }, "decline_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "test": { "type": "boolean" } } }, "ShipmentEvent": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Booked", "Picked up", "In transit", "Out for delivery", "Delivered", "Delayed", "Cancelled" ] }, "location": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } } }, "Shipment": { "type": "object", "properties": { "ref": { "type": "string" }, "status": { "type": "string" }, "origin": { "type": "string" }, "stops": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } }, "destination": { "type": "string" }, "eta": { "type": [ "string", "null" ] }, "po": { "type": [ "string", "null" ] }, "bol": { "type": [ "string", "null" ] }, "pro": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentEvent" }, "description": "Newest first" }, "test": { "type": "boolean" } } }, "TrackingPoint": { "type": "object", "description": "One point, or { points: [...] } with up to 50.", "properties": { "shipment_ref": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "speed_mph": { "type": "number" }, "heading": { "type": "number" }, "at": { "type": "string", "format": "date-time", "description": "Optional, up to 24 h old" }, "points": { "type": "array", "maxItems": 50, "items": { "type": "object" } } } } } } }