{ "components": { "schemas": { "AddressRiskScore": { "description": "The tracking network's one stored risk score for a normalized address: `created_at` and `updated_at` are when the network first and last scored the address for any of its customers, and `address_input` is the input it keeps.", "properties": { "address_hash": { "type": "string" }, "address_input": { "type": "string" }, "address_normalized": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "reason": { "nullable": true, "type": "string" }, "risk_level": { "type": "string" }, "score": { "format": "int32", "type": "integer" }, "signal_address_type": { "format": "int32", "type": "integer" }, "signal_carrier_data": { "format": "int32", "type": "integer" }, "signal_confirmation_rate": { "format": "int32", "type": "integer" }, "signal_crime_index": { "format": "int32", "type": "integer" }, "signal_details": { "type": "object" }, "signal_dispute_history": { "format": "int32", "type": "integer" }, "signal_gps_proof": { "format": "int32", "type": "integer" }, "signal_risk_network": { "format": "int32", "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "organization_id", "address_hash", "address_normalized", "address_input", "score", "risk_level", "signal_dispute_history", "signal_address_type", "signal_crime_index", "signal_confirmation_rate", "signal_gps_proof", "signal_carrier_data", "signal_risk_network", "signal_details", "created_at", "updated_at" ], "type": "object" }, "Alert": { "description": "Alert notification", "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "message": { "nullable": true, "type": "string" }, "metadata": { "type": "object" }, "organization_id": { "format": "uuid", "type": "string" }, "read_at": { "format": "date-time", "nullable": true, "type": "string" }, "severity": { "type": "string" }, "tag_id": { "format": "uuid", "type": "string" }, "tag_serial": { "description": "The tag's printed ID, when known.", "nullable": true, "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "organization_id", "tag_id", "type", "severity", "title", "created_at", "metadata" ], "type": "object" }, "AlertListPage": { "description": "One page of alerts: `items` and `pagination`.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Alert" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "pagination" ], "type": "object" }, "AlertSeverity": { "description": "Alert severity", "enum": [ "info", "warning", "critical" ], "type": "string" }, "AlertSummary": { "description": "Alert summary counts (total, unread, critical unread)", "properties": { "critical_unread": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" }, "unread": { "format": "int64", "type": "integer" } }, "required": [ "total", "unread", "critical_unread" ], "type": "object" }, "ApiResponseAddressRiskScore": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AddressRiskScore" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseAlert": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Alert" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseAlertList": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AlertListPage" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseAlertSummary": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AlertSummary" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseBatchAssess": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/BatchAssessResponse" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseDispute": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Dispute" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseDisputeList": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DisputeListPage" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseDisputeStats": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/DisputeStatsResponse" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseGenerateEvidence": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/GenerateEvidenceResponse" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseMarkRead": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/MarkReadResponse" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseObject": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseRiskAssessment": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/RiskAssessmentResult" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseShipment": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Shipment" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseShipmentListPage": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/ShipmentListPage" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseShipmentWithPackages": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/ShipmentWithPackages" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseTag": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Tag" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseTagEvidence": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/TagEvidenceResponse" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseTagJourney": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/TagJourneyResponse" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseTagList": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/TagListPage" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseTagWithLastPing": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/TagWithLastPing" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseWebhookDeliveryList": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryListPage" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseWebhookSubscriptionCreated": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/CreateWebhookSubscriptionResponse" } ], "nullable": true }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ApiResponseWebhookSubscriptionList": { "description": "The response envelope: `success`, `data` (the payload, null on an error) and `error` (a message when `success` is false).", "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookSubscription" }, "nullable": true, "type": "array" }, "error": { "nullable": true, "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "ArchivedFilter": { "default": "exclude", "description": "`exclude` (the default) hides archived tags. `include` (archived tags too) and `only` (archived tags only) are not yet verified against the tracking network.", "enum": [ "exclude", "include", "only" ], "type": "string" }, "AssessAddressRequest": { "description": "Request to assess a single address", "example": { "city": "Austin", "state": "TX", "street": "123 Main St", "street2": "Apt 4", "zip": "78701" }, "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "street": { "type": "string" }, "street2": { "description": "Optional: unit/apt number.", "nullable": true, "type": "string" }, "zip": { "type": "string" } }, "required": [ "street", "city", "state", "zip" ], "type": "object" }, "BatchAssessRequest": { "description": "Request for batch assessment", "example": { "addresses": [ { "city": "Austin", "state": "TX", "street": "123 Main St", "street2": "Apt 4", "zip": "78701" }, { "city": "Dallas", "state": "TX", "street": "456 Warehouse Ave", "zip": "75201" } ] }, "properties": { "addresses": { "items": { "$ref": "#/components/schemas/AssessAddressRequest" }, "type": "array" } }, "required": [ "addresses" ], "type": "object" }, "BatchAssessResponse": { "description": "Batch assessment response", "properties": { "cached": { "description": "How many of `results` your organization had assessed before this call.", "minimum": 0, "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/RiskAssessmentResult" }, "type": "array" }, "total": { "minimum": 0, "type": "integer" } }, "required": [ "results", "total", "cached" ], "type": "object" }, "CreatePackageEntry": { "description": "A single package entry within a create-shipment request", "properties": { "child_tracking_number": { "description": "Per-box tracking number (child)", "nullable": true, "type": "string" }, "tag_identifier": { "description": "A tag assigned to your organization: its printed ID, BLE identifier or uuid.", "type": "string" } }, "required": [ "tag_identifier" ], "type": "object" }, "CreateShipmentRequest": { "description": "Request to create a new shipment with packages", "example": { "carrier": "fedex", "destination_address": "123 Main St, Austin TX 78701", "insurance": { "currency": "USD", "declared_value": "1250.00" }, "master_tracking_number": "123456789012", "order_id": "ORD-001", "origin_address": "456 Warehouse Ave, Dallas TX 75201", "packages": [ { "child_tracking_number": "CHILD-TRACK-001", "tag_identifier": "0938NYH" } ], "recipient_email": "jane@example.com", "recipient_name": "Jane Smith", "recipient_phone": "+15551234567", "service_level": "ground" }, "properties": { "carrier": { "type": "string" }, "destination_address": { "nullable": true, "type": "string" }, "destination_lat": { "format": "double", "nullable": true, "type": "number" }, "destination_lng": { "format": "double", "nullable": true, "type": "number" }, "insurance": { "allOf": [ { "$ref": "#/components/schemas/ShipmentInsuranceRequest" } ], "description": "Declares a value for the new shipment. Each rule refused answers 400: `declared_value` a decimal string with at most two decimals, greater than zero; `currency` equal to your organization's currency. `null` is refused on create.", "nullable": true }, "master_tracking_number": { "nullable": true, "type": "string" }, "order_id": { "nullable": true, "type": "string" }, "origin_address": { "nullable": true, "type": "string" }, "origin_lat": { "format": "double", "nullable": true, "type": "number" }, "origin_lng": { "format": "double", "nullable": true, "type": "number" }, "origin_location_id": { "deprecated": true, "description": "Not supported by SecreTag: a request that names it answers 400.", "format": "uuid", "nullable": true, "type": "string" }, "packages": { "description": "Packages to create: each names a tag and an optional child tracking number.", "items": { "$ref": "#/components/schemas/CreatePackageEntry" }, "type": "array" }, "recipient_email": { "nullable": true, "type": "string" }, "recipient_name": { "nullable": true, "type": "string" }, "recipient_phone": { "nullable": true, "type": "string" }, "service_level": { "description": "Service level (e.g., ground, express, priority, next_day, economy)", "nullable": true, "type": "string" } }, "required": [ "carrier", "packages" ], "type": "object" }, "CreateWebhookSubscriptionRequest": { "description": "Request to create a webhook subscription.", "example": { "event_types": [ "tag.state_changed", "tag.delivered", "shipment.created" ], "label": "My integration", "target_url": "https://your-server.com/webhooks/secretag" }, "properties": { "event_types": { "description": "The event types to receive; omit or `null` for every event.", "items": { "enum": [ "tag.state_changed", "tag.delivered", "tag.approaching", "tag.carrier_updated", "dispute.opened", "dispute.resolved", "dispute.evidence_submitted", "shipment.created", "shipment.delivered", "risk.high_score" ], "type": "string" }, "nullable": true, "type": "array" }, "label": { "nullable": true, "type": "string" }, "target_url": { "description": "An HTTPS URL on a public address.", "type": "string" } }, "required": [ "target_url" ], "type": "object" }, "CreateWebhookSubscriptionResponse": { "description": "The subscription just created, with its signing `secret` (returned only here).", "properties": { "created_at": { "format": "date-time", "type": "string" }, "event_types": { "description": "The event types the subscription takes; `null` for every event.", "items": { "enum": [ "tag.state_changed", "tag.delivered", "tag.approaching", "tag.carrier_updated", "dispute.opened", "dispute.resolved", "dispute.evidence_submitted", "shipment.created", "shipment.delivered", "risk.high_score" ], "type": "string" }, "nullable": true, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "is_active": { "type": "boolean" }, "label": { "nullable": true, "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "secret": { "description": "The signing secret, returned once in this response and never again. Verify each delivery's `X-SecreTag-Signature: sha256=` with it.", "nullable": true, "type": "string" }, "target_url": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "target_url", "is_active", "created_at", "organization_id", "updated_at" ], "type": "object" }, "Dispute": { "description": "Delivery dispute", "properties": { "customer_claim": { "nullable": true, "type": "string" }, "evidence_score": { "format": "int32", "nullable": true, "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "metadata": { "type": "object" }, "opened_at": { "format": "date-time", "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "resolution": { "nullable": true, "type": "string" }, "resolved_at": { "format": "date-time", "nullable": true, "type": "string" }, "resolved_by": { "format": "uuid", "nullable": true, "type": "string" }, "shopify_submission_status": { "nullable": true, "type": "string" }, "shopify_submitted_at": { "format": "date-time", "nullable": true, "type": "string" }, "status": { "type": "string" }, "tag_id": { "format": "uuid", "type": "string" }, "tag_serial": { "description": "The tag's printed ID, when known.", "nullable": true, "type": "string" }, "type": { "nullable": true, "type": "string" } }, "required": [ "id", "organization_id", "tag_id", "status", "opened_at", "metadata" ], "type": "object" }, "DisputeListPage": { "description": "One page of disputes: `items` and `pagination`.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Dispute" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "pagination" ], "type": "object" }, "DisputeStatsResponse": { "description": "Dispute counts and figures, computed by SecreTag for your organization (see `dispute_stats`).", "properties": { "amount_at_risk": { "description": "The sum of the declared values of your insured shipments in an open or investigating dispute, a number with two decimals in your organization's currency.", "format": "double", "type": "number" }, "avg_resolution_hours": { "description": "Mean hours from open to resolution, two decimals; null when no dispute is resolved.", "format": "double", "nullable": true, "type": "number" }, "evidence_generated": { "description": "Your disputes for which SecreTag recorded a successful `generate_evidence` call.", "format": "int64", "type": "integer" }, "investigating": { "format": "int64", "type": "integer" }, "open": { "format": "int64", "type": "integer" }, "resolved": { "format": "int64", "type": "integer" }, "shopify_submitted": { "description": "Your disputes that carry a `shopify_submitted_at`.", "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "total", "open", "investigating", "resolved", "evidence_generated", "shopify_submitted", "amount_at_risk" ], "type": "object" }, "ErrorResponse": { "description": "The envelope of every error answer: success false, data null, error a message.", "properties": { "data": { "enum": [ null ], "nullable": true }, "error": { "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "data", "error" ], "type": "object" }, "EvidenceLocationProofEntry": { "description": "A single BLE location report in the evidence package.", "properties": { "accuracy_m": { "format": "double", "nullable": true, "type": "number" }, "lat": { "format": "double", "type": "number" }, "lng": { "format": "double", "type": "number" }, "source": { "description": "Detection source. `\"network\"` = satellite/terrestrial network; `\"ble\"` = direct BLE.", "type": "string" }, "status": { "description": "Proximity to the destination. One of `\"at_destination\"`, `\"approaching\"` (< 1 km), or `\"in_transit\"`.", "type": "string" }, "tag_id": { "description": "Tag that produced this ping. Use with `tag_count` to group pings by tag in multi-box shipments.", "format": "uuid", "type": "string" }, "time": { "format": "date-time", "type": "string" } }, "required": [ "tag_id", "time", "lat", "lng", "source", "status" ], "type": "object" }, "ForceStateRequest": { "description": "Force a tag to a specific state.", "example": { "state": "in_transit" }, "properties": { "state": { "description": "One of: awaiting_first_ping, at_origin, in_transit, approaching, delivered,\ndelivery_verification, disputed_in_transit, completed", "type": "string" } }, "required": [ "state" ], "type": "object" }, "GenerateEvidenceResponse": { "description": "The result of `generate_evidence`.", "properties": { "evidence_pdf_key": { "description": "Where the tracking network stored the evidence PDF; download it with `get_evidence_pdf`.", "type": "string" }, "generated_at": { "description": "RFC 3339 timestamp of generation.", "type": "string" } }, "required": [ "evidence_pdf_key", "generated_at" ], "type": "object" }, "JourneyPoint": { "description": "Journey point for map display", "properties": { "accuracy_m": { "format": "double", "nullable": true, "type": "number" }, "lat": { "format": "double", "type": "number" }, "lng": { "format": "double", "type": "number" }, "source": { "type": "string" }, "time": { "format": "date-time", "type": "string" } }, "required": [ "time", "lat", "lng", "source" ], "type": "object" }, "JourneyStage": { "description": "How far through the mock journey to populate.", "enum": [ "started", "in_transit", "approaching", "complete" ], "type": "string" }, "LastPing": { "description": "Summary of last ping for a tag", "properties": { "lat": { "format": "double", "type": "number" }, "lng": { "format": "double", "type": "number" }, "rssi": { "description": "Radio signal strength (dBm) of the gateway that heard this ping, when reported.", "format": "int32", "nullable": true, "type": "integer" }, "source": { "type": "string" }, "time": { "format": "date-time", "type": "string" } }, "required": [ "time", "lat", "lng", "source" ], "type": "object" }, "MarkReadResponse": { "description": "An alert marked read.", "properties": { "id": { "format": "uuid", "type": "string" }, "read_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "read_at" ], "type": "object" }, "MockAlertRequest": { "example": { "alert_type": "delivery", "severity": "warning" }, "properties": { "alert_type": { "description": "Alert type. Defaults to `delivery`.\nOne of: geofence, delivery, dispute, system, package_separation, gps_carrier_mismatch", "type": "string" }, "severity": { "description": "Alert severity. Defaults to `warning`. One of: info, warning, critical", "type": "string" } }, "type": "object" }, "MockCarrierEventRequest": { "example": { "status": "in_transit" }, "properties": { "status": { "description": "Carrier status. One of: in_transit, out_for_delivery, delivered, exception", "type": "string" } }, "required": [ "status" ], "type": "object" }, "MockDisputeRequest": { "example": { "customer_claim": "Customer reports the package was not delivered.", "dispute_type": "not_delivered" }, "properties": { "customer_claim": { "description": "Customer's claim text. Defaults to a generic message. Max 1000 characters.", "type": "string" }, "dispute_type": { "description": "Dispute type. Defaults to `not_delivered`.\nOne of: not_delivered, damaged, wrong_location, other", "type": "string" } }, "type": "object" }, "MockJourneyRequest": { "example": { "stage": "complete" }, "properties": { "stage": { "$ref": "#/components/schemas/JourneyStage" } }, "type": "object" }, "MockRiskScoreRequest": { "example": { "risk_factors": [ "route_deviation", "dispute_history" ], "score": 85 }, "properties": { "risk_factors": { "description": "Risk factors to include in the webhook payload.\nDefaults to [\"route_deviation\", \"dispute_history\"].", "items": { "type": "string" }, "type": "array" }, "score": { "description": "Risk score, 0 to 100. Defaults to 85 (the high-risk threshold).", "format": "int32", "minimum": 0, "type": "integer" } }, "type": "object" }, "PaginationMeta": { "description": "Pagination metadata for list responses", "properties": { "limit": { "format": "int32", "minimum": 0, "type": "integer" }, "page": { "format": "int32", "minimum": 0, "type": "integer" }, "total": { "format": "int64", "type": "integer" }, "total_pages": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "page", "limit", "total", "total_pages" ], "type": "object" }, "ResolveDisputeRequest": { "description": "Request to resolve a dispute", "example": { "evidence_score": 85, "resolution": "Confirmed delivered: package located at rear entrance." }, "properties": { "evidence_score": { "format": "int32", "nullable": true, "type": "integer" }, "resolution": { "type": "string" } }, "required": [ "resolution" ], "type": "object" }, "RiskAssessmentResult": { "description": "Risk assessment result returned to the client", "properties": { "address_hash": { "type": "string" }, "address_input": { "type": "string" }, "reason": { "type": "string" }, "risk_level": { "type": "string" }, "score": { "format": "int32", "type": "integer" }, "signals": { "$ref": "#/components/schemas/RiskSignals" } }, "required": [ "address_hash", "address_input", "score", "risk_level", "signals", "reason" ], "type": "object" }, "RiskSignals": { "description": "The six risk signals behind one score.", "properties": { "address_type": { "$ref": "#/components/schemas/SignalDetail" }, "carrier_data": { "$ref": "#/components/schemas/SignalDetail" }, "crime_index": { "$ref": "#/components/schemas/SignalDetail" }, "disputes": { "$ref": "#/components/schemas/SignalDetail" }, "gps_proof": { "$ref": "#/components/schemas/SignalDetail" }, "risk_network": { "$ref": "#/components/schemas/SignalDetail" } }, "required": [ "address_type", "crime_index", "disputes", "gps_proof", "carrier_data", "risk_network" ], "type": "object" }, "SelfServeCarrierData": { "description": "Carrier fields of a tag activated outside a shipment (a self-serve tag).", "properties": { "carrier": { "nullable": true, "type": "string" }, "carrier_events": {}, "carrier_status": { "nullable": true, "type": "string" }, "expected_delivery": { "nullable": true, "type": "string" }, "tracking_number": { "nullable": true, "type": "string" } }, "type": "object" }, "Shipment": { "description": "A shipment: master-level tracking for one or more packages", "properties": { "carrier": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "destination_address": { "nullable": true, "type": "string" }, "destination_lat": { "format": "double", "nullable": true, "type": "number" }, "destination_lng": { "format": "double", "nullable": true, "type": "number" }, "id": { "format": "uuid", "type": "string" }, "insurance": { "allOf": [ { "$ref": "#/components/schemas/ShipmentInsurance" } ], "description": "The declared value SecreTag keeps for this shipment; null when none is declared. Present on every shipment SecreTag returns.", "nullable": true }, "master_status": { "nullable": true, "type": "string" }, "master_tracking_number": { "nullable": true, "type": "string" }, "order_id": { "nullable": true, "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "origin_address": { "nullable": true, "type": "string" }, "origin_lat": { "format": "double", "nullable": true, "type": "number" }, "origin_lng": { "format": "double", "nullable": true, "type": "number" }, "origin_location_id": { "format": "uuid", "nullable": true, "type": "string" }, "public_id": { "type": "string" }, "recipient_email": { "nullable": true, "type": "string" }, "recipient_name": { "nullable": true, "type": "string" }, "recipient_phone": { "nullable": true, "type": "string" }, "service_level": { "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "organization_id", "public_id", "carrier", "created_at", "updated_at", "insurance" ], "type": "object" }, "ShipmentInsurance": { "description": "A declared value SecreTag keeps for a shipment.", "properties": { "currency": { "description": "Three-letter currency code: your organization's currency.", "example": "USD", "pattern": "^[A-Z]{3}$", "type": "string" }, "declared_at": { "description": "When the value was declared.", "format": "date-time", "type": "string" }, "declared_value": { "description": "The declared value, a decimal string with two decimals.", "example": "1250.00", "pattern": "^\\d{1,13}\\.\\d{2}$", "type": "string" } }, "required": [ "declared_value", "currency", "declared_at" ], "type": "object" }, "ShipmentInsuranceRequest": { "description": "A declared value for a shipment.", "properties": { "currency": { "description": "Must equal your organization's currency.", "example": "USD", "pattern": "^[A-Z]{3}$", "type": "string" }, "declared_value": { "description": "A decimal string with at most two decimals and at most 13 digits before the point, greater than zero. A JSON number is refused.", "example": "1250.00", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "type": "string" } }, "required": [ "declared_value", "currency" ], "type": "object" }, "ShipmentListPage": { "description": "One page of your shipments: `items` and `pagination` are always present. Each item is a Shipment with its `insurance`; whether items also carry `packages` is not yet verified.", "properties": { "items": { "items": { "$ref": "#/components/schemas/Shipment" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "pagination" ], "type": "object" }, "ShipmentPackage": { "description": "A single package within a shipment (1:1 with a tag)", "properties": { "actual_delivery": { "format": "date-time", "nullable": true, "type": "string" }, "carrier_events": { "type": "object" }, "carrier_last_checked": { "format": "date-time", "nullable": true, "type": "string" }, "child_status": { "nullable": true, "type": "string" }, "child_tracking_number": { "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "estimated_delivery": { "format": "date", "nullable": true, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "sequence_number": { "format": "int32", "type": "integer" }, "shipment_id": { "format": "uuid", "type": "string" }, "tagBleIdentifier": { "nullable": true, "type": "string" }, "tagDestinationAddress": { "nullable": true, "type": "string" }, "tagLastSeen": { "format": "date-time", "nullable": true, "type": "string" }, "tagState": { "nullable": true, "type": "string" }, "tag_id": { "format": "uuid", "nullable": true, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "shipment_id", "sequence_number", "carrier_events", "created_at", "updated_at" ], "type": "object" }, "ShipmentWithPackages": { "allOf": [ { "$ref": "#/components/schemas/Shipment" }, { "properties": { "packages": { "items": { "$ref": "#/components/schemas/ShipmentPackage" }, "type": "array" } }, "required": [ "packages" ], "type": "object" } ], "description": "Shipment with all its packages (for API responses)" }, "SignalDetail": { "description": "A single signal's raw score and explanation", "properties": { "explanation": { "description": "Human-readable explanation", "type": "string" }, "raw_score": { "description": "Raw signal score 0-100 (before weighting)", "format": "int32", "type": "integer" }, "weight": { "description": "Weight applied (0.0 - 1.0)", "format": "double", "type": "number" }, "weighted_score": { "description": "Weighted contribution to final score", "format": "double", "type": "number" } }, "required": [ "raw_score", "weight", "weighted_score", "explanation" ], "type": "object" }, "Tag": { "description": "Tag (BLE beacon) attached to a package", "properties": { "archived_at": { "format": "date-time", "nullable": true, "type": "string" }, "auto_off_after_delivery": { "description": "Per-tag override of the organization's deactivate-after-delivery setting; null inherits the organization default.", "nullable": true, "type": "boolean" }, "auto_off_at": { "description": "The scheduled automatic switch-off time, when known.", "format": "date-time", "nullable": true, "type": "string" }, "auto_off_state": { "description": "`active`, `scheduled` or `off`: the tag's automatic switch-off state; null when not known.", "nullable": true, "type": "string" }, "ble_identifier": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "format": "date-time", "nullable": true, "type": "string" }, "destination_address": { "nullable": true, "type": "string" }, "destination_lat": { "format": "double", "nullable": true, "type": "number" }, "destination_lng": { "format": "double", "nullable": true, "type": "number" }, "geofence_radius_m": { "format": "int32", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "metadata": { "type": "object" }, "network_coverage_months": { "description": "The network coverage months sold for this tag's device, when known (read only).", "format": "int32", "nullable": true, "type": "integer" }, "network_device_id": { "nullable": true, "type": "string" }, "network_last_checked": { "format": "date-time", "nullable": true, "type": "string" }, "network_off_override_at": { "description": "An explicit network switch-off time set for this tag's device, or null (read only).", "format": "date-time", "nullable": true, "type": "string" }, "order_id": { "nullable": true, "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "origin_address": { "nullable": true, "type": "string" }, "origin_lat": { "format": "double", "nullable": true, "type": "number" }, "origin_lng": { "format": "double", "nullable": true, "type": "number" }, "origin_location_id": { "description": "The origin location the tag was created with, if any (read only).", "format": "uuid", "nullable": true, "type": "string" }, "recipient_email": { "nullable": true, "type": "string" }, "recipient_name": { "nullable": true, "type": "string" }, "recipient_phone": { "nullable": true, "type": "string" }, "shipment_package_id": { "format": "uuid", "nullable": true, "type": "string" }, "shipped_at": { "format": "date-time", "nullable": true, "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "organization_id", "ble_identifier", "state", "geofence_radius_m", "created_at", "metadata" ], "type": "object" }, "TagEvidenceResponse": { "description": "Everything the generated evidence PDF contains, so you can build your own representation without downloading the PDF.", "properties": { "carrier": { "nullable": true, "type": "string" }, "carrier_delivered_at": { "format": "date-time", "nullable": true, "type": "string" }, "carrier_events": { "description": "Carrier scan events array. Each entry has `timestamp`, `status`,\n`location`, and `description` string fields.", "nullable": true }, "carrier_status": { "nullable": true, "type": "string" }, "destination_address": { "nullable": true, "type": "string" }, "dispute": { "$ref": "#/components/schemas/Dispute" }, "dwell_time_secs": { "description": "Seconds the tag was stationary at the destination address.\nNull when fewer than 2 pings were recorded near the destination.", "format": "int64", "nullable": true, "type": "integer" }, "evidence_generated_at": { "description": "When the evidence PDF was generated.", "format": "date-time", "nullable": true, "type": "string" }, "location_proof": { "description": "Up to 50 most recent BLE location reports, oldest-first.", "items": { "$ref": "#/components/schemas/EvidenceLocationProofEntry" }, "type": "array" }, "origin_address": { "nullable": true, "type": "string" }, "pings_at_destination": { "description": "Pings detected within 150 m of the destination coordinates.", "format": "int64", "type": "integer" }, "tag_count": { "description": "Number of tags in the shipment (> 1 means multi-box).", "format": "int64", "type": "integer" }, "total_pings": { "description": "Total BLE location reports recorded across all tags in the shipment.", "format": "int64", "type": "integer" }, "tracking_number": { "nullable": true, "type": "string" } }, "required": [ "dispute", "total_pings", "pings_at_destination", "tag_count", "location_proof" ], "type": "object" }, "TagJourneyResponse": { "description": "Journey response for a tag", "properties": { "points": { "items": { "$ref": "#/components/schemas/JourneyPoint" }, "type": "array" }, "tag_id": { "format": "uuid", "type": "string" }, "total_points": { "format": "int64", "type": "integer" } }, "required": [ "tag_id", "points", "total_points" ], "type": "object" }, "TagListPage": { "description": "One page of tags: `items` and `pagination`.", "properties": { "items": { "items": { "$ref": "#/components/schemas/TagWithLastPing" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "pagination" ], "type": "object" }, "TagWithLastPing": { "allOf": [ { "$ref": "#/components/schemas/Tag" }, { "properties": { "last_ping": { "$ref": "#/components/schemas/LastPing" }, "ping_count": { "type": "integer" }, "recent_pings": { "items": { "$ref": "#/components/schemas/LastPing" }, "type": "array" }, "self_serve": { "$ref": "#/components/schemas/SelfServeCarrierData" } }, "required": [ "ping_count" ], "type": "object" } ] }, "TestWebhookRequest": { "description": "Send SecreTag's sample event of `event_type` to your matching active subscriptions.", "example": { "event_type": "tag.state_changed" }, "properties": { "event_type": { "description": "One of the ten event types.", "enum": [ "tag.state_changed", "tag.delivered", "tag.approaching", "tag.carrier_updated", "dispute.opened", "dispute.resolved", "dispute.evidence_submitted", "shipment.created", "shipment.delivered", "risk.high_score" ], "type": "string" } }, "required": [ "event_type" ], "type": "object" }, "UpdateShipmentRequest": { "description": "Request to update shipment metadata", "example": { "carrier": "fedex", "destination_address": "123 Main St, Austin TX 78701", "insurance": { "currency": "USD", "declared_value": "1250.00" }, "master_tracking_number": "123456789012", "order_id": "ORD-001", "origin_address": "456 Warehouse Ave, Dallas TX 75201", "recipient_email": "jane@example.com", "recipient_name": "Jane Smith", "recipient_phone": "+15551234567", "service_level": "ground" }, "properties": { "carrier": { "nullable": true, "type": "string" }, "destination_address": { "nullable": true, "type": "string" }, "destination_lat": { "format": "double", "nullable": true, "type": "number" }, "destination_lng": { "format": "double", "nullable": true, "type": "number" }, "insurance": { "allOf": [ { "$ref": "#/components/schemas/ShipmentInsuranceRequest" } ], "description": "Sets the declared value, replacing any earlier one. Each rule refused answers 400: `declared_value` a decimal string with at most two decimals, greater than zero; `currency` equal to your organization's currency. `null` clears it; omit it to leave it unchanged.", "nullable": true }, "master_tracking_number": { "nullable": true, "type": "string" }, "order_id": { "nullable": true, "type": "string" }, "origin_address": { "nullable": true, "type": "string" }, "origin_lat": { "format": "double", "nullable": true, "type": "number" }, "origin_lng": { "format": "double", "nullable": true, "type": "number" }, "recipient_email": { "nullable": true, "type": "string" }, "recipient_name": { "nullable": true, "type": "string" }, "recipient_phone": { "nullable": true, "type": "string" }, "service_level": { "description": "Service level (e.g., ground, express, priority, next_day, economy)", "nullable": true, "type": "string" } }, "type": "object" }, "UpdateTagRequest": { "description": "Request to update a tag", "example": { "destination_address": "123 Main St, Austin TX 78701", "order_id": "ORD-001", "origin_address": "456 Warehouse Ave, Dallas TX 75201", "recipient_email": "jane@example.com", "recipient_name": "Jane Smith", "recipient_phone": "+15551234567" }, "properties": { "auto_off_after_delivery": { "description": "Per-tag override of the deactivate-after-delivery setting: omit to leave it unchanged, `null` to inherit the organization default, `true` or `false` to force it.", "nullable": true, "type": "boolean" }, "destination_address": { "nullable": true, "type": "string" }, "destination_lat": { "format": "double", "nullable": true, "type": "number" }, "destination_lng": { "format": "double", "nullable": true, "type": "number" }, "geofence_radius_m": { "format": "int32", "nullable": true, "type": "integer" }, "metadata": { "nullable": true, "type": "object" }, "network_coverage_months": { "description": "Accepted and not acted on by this operation.", "format": "int32", "nullable": true, "type": "integer" }, "network_off_override_at": { "description": "Accepted and not acted on by this operation.", "format": "date-time", "nullable": true, "type": "string" }, "order_id": { "nullable": true, "type": "string" }, "origin_address": { "nullable": true, "type": "string" }, "origin_lat": { "format": "double", "nullable": true, "type": "number" }, "origin_lng": { "format": "double", "nullable": true, "type": "number" }, "recipient_email": { "nullable": true, "type": "string" }, "recipient_name": { "nullable": true, "type": "string" }, "recipient_phone": { "nullable": true, "type": "string" } }, "type": "object" }, "WebhookDelivery": { "description": "One relay of one event to one of your subscriptions (SecreTag's delivery log).", "properties": { "attempts": { "format": "int32", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "format": "date-time", "nullable": true, "type": "string" }, "event_id": { "description": "The event's id: the tracking network's event id, or `test_` for a `test_webhook` sample event.", "type": "string" }, "event_type": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "last_attempt_at": { "format": "date-time", "nullable": true, "type": "string" }, "last_error": { "nullable": true, "type": "string" }, "last_response_body": { "nullable": true, "type": "string" }, "last_status_code": { "format": "int32", "nullable": true, "type": "integer" }, "max_attempts": { "format": "int32", "type": "integer" }, "next_retry_at": { "format": "date-time", "nullable": true, "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "payload": { "description": "The event body SecreTag sent.", "type": "object" }, "status": { "description": "`pending`, `delivered`, `failed` (8 attempts without a 2xx) or `cancelled` (the subscription was deactivated first).", "type": "string" }, "subscription_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "subscription_id", "organization_id", "event_type", "event_id", "payload", "status", "attempts", "max_attempts", "created_at" ], "type": "object" }, "WebhookDeliveryListPage": { "description": "One page of a subscription's delivery log: `items` and `pagination`.", "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "pagination" ], "type": "object" }, "WebhookSubscription": { "description": "A webhook subscription.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "event_types": { "description": "The event types the subscription takes; `null` for every event.", "items": { "enum": [ "tag.state_changed", "tag.delivered", "tag.approaching", "tag.carrier_updated", "dispute.opened", "dispute.resolved", "dispute.evidence_submitted", "shipment.created", "shipment.delivered", "risk.high_score" ], "type": "string" }, "nullable": true, "type": "array" }, "id": { "format": "uuid", "type": "string" }, "is_active": { "type": "boolean" }, "label": { "nullable": true, "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "target_url": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "organization_id", "target_url", "is_active", "created_at", "updated_at" ], "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "description": "An organization API key issued by SecreTag support: `st_live_...` on api.secretag.co, `st_test_...` on sandbox-api.secretag.co.", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "contact": { "email": "support@secretag.co", "name": "SecreTag" }, "description": "Server-to-server REST API for SecreTag package tracking integrations.\n\n## Authentication\nEvery operation takes an organization-scoped API key in the `X-API-Key` header. Keys are issued by SecreTag support (support@secretag.co); there is no self-serve key page yet. A live key starts with `st_live_` and works only on `https://api.secretag.co`; a test key starts with `st_test_` and works only on `https://sandbox-api.secretag.co`. A missing, unknown or revoked key, or a key used on the other host, answers 401 `Invalid API key`.\n\n## Response envelope\nEvery JSON answer, success or error, is `{ \"success\": boolean, \"data\": , \"error\": }`. Two answers are not wrapped: `GET /v1/integrations/disputes/{id}/evidence/pdf` returns the PDF bytes (`application/pdf`) and `DELETE /v1/integrations/webhooks/{id}` returns 204 with no body.\n\n## Tenancy\nA caller sees only its own organization's tags and what belongs to them (their shipments, disputes and alerts, the address scores it requested and its own webhook subscriptions); any other id answers 404.\n\n## Limits and errors\n- Failed authentication: after 60 failed attempts in a minute from one IP address, further invalid keys answer 429 `Too many failed authentication attempts, try again in a minute`.\n- Organization rate limit: 600 requests per minute per organization; past it, 429 `Rate limit exceeded: 600 requests per minute`.\n- Request body: at most 1 MB; a larger body answers 413 `Request body too large (limit 1 MB)`. A JSON body that does not parse answers 400 `Malformed JSON`.\n- Every operation that reaches the tracking network (all but the webhook subscription operations and `test_webhook`) may answer 502 `Upstream unavailable` (the tracking network timed out, could not be reached or failed) and 503 `Upstream not configured` (the environment is not connected to the tracking network). Nothing is retried on the request path.\n\n## Lists\nThe four list operations (`list_tags`, `list_shipments`, `list_alerts`, `list_disputes`) accept only their documented filters; any other query parameter is ignored. `page` is 1-based (default 1) and `limit` is 1 to 200 (default 50); any other value answers 400. A filter that matches more than 5,000 items on the tracking network, or a list that takes more than 20 seconds to read, answers 503 `List too large, add filters`: narrow the filters and retry.\n\n## Declared value insurance\nA shipment can carry a declared value: send `\"insurance\": { \"declared_value\": \"1250.00\", \"currency\": \"USD\" }` on `create_shipment` or `update_shipment`. `declared_value` is a decimal string with at most two decimals, greater than zero; `currency` is your organization's currency (three letters, USD unless SecreTag support set another). SecreTag keeps it and returns `insurance` (`declared_value`, `currency`, `declared_at`) on every shipment, `null` when none is declared; `\"insurance\": null` on update clears it. No premium, policy or claim is attached in this version.\n\n## Webhooks\nWebhook subscriptions are SecreTag's own. SecreTag relays the events of your tags, shipments, disputes and alerts to each of your active subscriptions that takes the event (its `event_types` names it, or is null for every event), as a POST of the event's JSON body with these headers:\n- `X-SecreTag-Signature: sha256=`, keyed with the subscription's secret\n- `X-SecreTag-Event`: the event type\n- `X-SecreTag-Delivery`: the delivery id\n\nA delivery succeeds only on a 2xx answer. Otherwise it is retried, 8 attempts in all, after waits of 30 s, 2 min, 10 min, 30 min, 1 h, 3 h and 8 h, and then marked `failed`. `target_url` must be an HTTPS URL on a public address. Verify the signature over the exact bytes you received, with a constant-time comparison.\n\n## Testing in the sandbox\nThe sandbox operations (`/v1/integrations/sandbox/*`) run only on `sandbox-api.secretag.co`; on `api.secretag.co` they answer 403 `Not available in production, use sandbox-api.secretag.co`. Use them to simulate tag events and test your webhook receiver without live hardware.", "license": { "name": "Proprietary" }, "title": "SecreTag API", "version": "1.0.0" }, "openapi": "3.0.3", "paths": { "/v1/integrations/alerts": { "get": { "description": "Alerts raised on your tags while they were assigned to you. Filters: `type`, `severity`, `unread_only`, `read` and `tag_id`. Only the filters documented here are forwarded; any other query parameter is ignored. `page` is 1-based (default 1) and `limit` is 1 to 200 (default 50); any other value answers 400. `pagination` counts only your organization's items. A filter that matches more than 5,000 items on the tracking network, or a list that takes more than 20 seconds to read, answers 503 `List too large, add filters`: narrow the filters and retry.", "operationId": "list_alerts", "parameters": [ { "description": "Page number, 1-based. Default 1.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int32", "minimum": 1, "type": "integer" } }, { "description": "Items per page, 1 to 200. Default 50.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "format": "int32", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Alert type, for example `geofence`, `delivery`, `dispute`, `system`, `package_separation` or `gps_carrier_mismatch`.", "in": "query", "name": "type", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "`info`, `warning` or `critical`.", "in": "query", "name": "severity", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/AlertSeverity" } ], "nullable": true } }, { "description": "`true` for unread alerts only.", "in": "query", "name": "unread_only", "required": false, "schema": { "nullable": true, "type": "boolean" } }, { "description": "`false` for unread alerts, `true` for read ones; omit for all.", "in": "query", "name": "read", "required": false, "schema": { "nullable": true, "type": "boolean" } }, { "description": "A tag's uuid, printed ID or BLE identifier. A tag not assigned to your organization returns an empty page.", "in": "query", "name": "tag_id", "required": false, "schema": { "nullable": true, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseAlertList" } } }, "description": "Paginated list of alerts" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`page` or `limit` is not a positive integer, or `limit` is over 200" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured, or the list is too large: add filters (`List too large, add filters`)" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List your organization's alerts.", "tags": [ "Integrations" ] } }, "/v1/integrations/alerts/read-all": { "post": { "description": "Computed by SecreTag: each of your organization's unread alerts is marked read, one by one, and `marked_read` is how many were marked. Reading and updating share a 20 second deadline and the 5,000-item limit; a failure part way answers 502, the alerts already marked stay read, and a retry marks only what is still unread.", "operationId": "mark_all_alerts_read", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseObject" } } }, "description": "Your unread alerts marked read; `data` is `{ \"marked_read\": }`" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Mark all your unread alerts as read.", "tags": [ "Integrations" ] } }, "/v1/integrations/alerts/summary": { "get": { "description": "Computed by SecreTag from your organization's alerts: `total` is the number of your alerts, `unread` those without `read_at`, and `critical_unread` the unread ones of severity `critical`. Reading your alerts takes at most 20 seconds and 5,000 items on the tracking network; past either the answer is 502, never a partial count.", "operationId": "alert_summary", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseAlertSummary" } } }, "description": "Alert counts (total, unread, critical unread)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Alert counts for your organization.", "tags": [ "Integrations" ] } }, "/v1/integrations/alerts/{id}/read": { "patch": { "description": "Any id that is not one of your organization's alerts answers 404 and nothing is changed.", "operationId": "mark_alert_read", "parameters": [ { "description": "Alert id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseMarkRead" } } }, "description": "Alert marked read" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Alert not found, not your organization's, or already read" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Mark one of your alerts as read.", "tags": [ "Integrations" ] } }, "/v1/integrations/disputes": { "get": { "description": "Disputes opened on your tags while they were assigned to you. Filters: `status`, `type` and `tag_id`. Only the filters documented here are forwarded; any other query parameter is ignored. `page` is 1-based (default 1) and `limit` is 1 to 200 (default 50); any other value answers 400. `pagination` counts only your organization's items. A filter that matches more than 5,000 items on the tracking network, or a list that takes more than 20 seconds to read, answers 503 `List too large, add filters`: narrow the filters and retry.", "operationId": "list_disputes", "parameters": [ { "description": "Page number, 1-based. Default 1.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int32", "minimum": 1, "type": "integer" } }, { "description": "Items per page, 1 to 200. Default 50.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "format": "int32", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "`open`, `investigating` or `resolved`.", "in": "query", "name": "status", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "Dispute type: `not_delivered`, `damaged`, `wrong_location` or `other`.", "in": "query", "name": "type", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "A tag's uuid, printed ID or BLE identifier. A tag not assigned to your organization returns an empty page.", "in": "query", "name": "tag_id", "required": false, "schema": { "nullable": true, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDisputeList" } } }, "description": "Paginated list of disputes" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`page` or `limit` is not a positive integer, or `limit` is over 200" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured, or the list is too large: add filters (`List too large, add filters`)" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List your organization's disputes.", "tags": [ "Integrations" ] } }, "/v1/integrations/disputes/stats": { "get": { "description": "Computed by SecreTag from your organization's disputes, never forwarded:\n- `total`: your disputes. `open`, `investigating` and `resolved`: those with that status (a dispute with another status counts in `total` only).\n- `shopify_submitted`: your disputes that carry a `shopify_submitted_at`.\n- `avg_resolution_hours`: the mean of `resolved_at` minus `opened_at` in hours, rounded to two decimals, over your resolved disputes that carry both times; `null` when none is resolved.\n- `evidence_generated`: the number of your disputes for which SecreTag recorded a successful `generate_evidence` call through this API.\n- `amount_at_risk`: the sum of the declared values (`insurance.declared_value`) of your insured shipments that have an `open` or `investigating` dispute, as a number with two decimals, in your organization's currency. A dispute's shipment is your latest shipment carrying the dispute's tag created at or before `opened_at`; each shipment counts once, and a cleared or replaced declared value does not count.\n\nReading your disputes takes at most 20 seconds and 5,000 items on the tracking network; past either the answer is 502, never a partial figure.", "operationId": "dispute_stats", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDisputeStats" } } }, "description": "Dispute counts and figures for your organization" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Dispute statistics for your organization.", "tags": [ "Integrations" ] } }, "/v1/integrations/disputes/{id}": { "get": { "description": "Any id that is not one of your organization's disputes answers 404.", "operationId": "get_dispute", "parameters": [ { "description": "Dispute id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDispute" } } }, "description": "Dispute detail" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Dispute not found, or not your organization's" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one of your disputes.", "tags": [ "Integrations" ] } }, "/v1/integrations/disputes/{id}/evidence/generate": { "post": { "description": "The evidence report is produced by the tracking network; `evidence_pdf_key` names where it stored the PDF. Download it with `get_evidence_pdf`. A successful call counts toward `dispute_stats.evidence_generated`.", "operationId": "generate_evidence", "parameters": [ { "description": "Dispute id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseGenerateEvidence" } } }, "description": "Evidence PDF generated and stored" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Dispute or tag not found, or not your organization's" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured, or evidence storage is unavailable on the tracking network (its 503, passed through)" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Generate the evidence PDF for one of your disputes.", "tags": [ "Integrations" ] } }, "/v1/integrations/disputes/{id}/evidence/pdf": { "get": { "description": "Returns the PDF bytes as the tracking network rendered them, typed `application/pdf` and not wrapped in the envelope. Call `generate_evidence` first: until then this answers 404.", "operationId": "get_evidence_pdf", "parameters": [ { "description": "Dispute id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "Evidence PDF" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "No evidence PDF generated for this dispute, or the dispute is not your organization's" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured, or evidence storage is unavailable on the tracking network (its 503, passed through)" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Download the evidence PDF for one of your disputes.", "tags": [ "Integrations" ] } }, "/v1/integrations/disputes/{id}/resolve": { "post": { "description": "`resolution` is required free text; `evidence_score` is optional (0 to 100). An API key carries no user, so `resolved_by` stays null.", "operationId": "resolve_dispute", "parameters": [ { "description": "Dispute id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveDisputeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDispute" } } }, "description": "Dispute resolved" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Dispute not found, not your organization's, or already resolved" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Resolve one of your disputes.", "tags": [ "Integrations" ] } }, "/v1/integrations/sandbox/tags/{id}/alert": { "post": { "description": "Creates an alert on the tag so you can test your alert handling. Send `{}` for an alert of type `delivery` and severity `warning`. Valid `alert_type`: `geofence`, `delivery`, `dispute`, `system`, `package_separation`, `gps_carrier_mismatch`. Valid `severity`: `info`, `warning`, `critical`. The alert appears in `list_alerts`.", "operationId": "mock_alert", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockAlertRequest" } } }, "description": "Send `{}` for an alert of type `delivery` and severity `warning`.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseAlert" } } }, "description": "Alert created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid alert_type or severity, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Inject a fake alert on one of your sandbox tags.", "tags": [ "Sandbox" ] } }, "/v1/integrations/sandbox/tags/{id}/carrier-event": { "post": { "description": "The tag must already be linked to a shipment (through `create_shipment`); otherwise the answer is 400. Valid `status`: `in_transit`, `out_for_delivery`, `delivered`, `exception`.", "operationId": "mock_carrier_event", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockCarrierEventRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseObject" } } }, "description": "Carrier status updated on the tag's package; `data` is `{ tag_id, package_id, status }`" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid status, the tag is not linked to a shipment, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Inject a fake carrier status on the tag's shipment package.", "tags": [ "Sandbox" ] } }, "/v1/integrations/sandbox/tags/{id}/dispute": { "post": { "description": "Opens a dispute with status `open`. Send `{}` for a `not_delivered` dispute with a default claim. Valid `dispute_type`: `not_delivered`, `damaged`, `wrong_location`, `other`; `customer_claim` is at most 1000 characters. Use it to test the dispute flow: open, generate evidence, download the PDF, resolve.", "operationId": "mock_dispute", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockDisputeRequest" } } }, "description": "Send `{}` for a `not_delivered` dispute with a default claim.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDispute" } } }, "description": "Dispute created with status open" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid dispute_type, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Open a fake dispute on one of your sandbox tags.", "tags": [ "Sandbox" ] } }, "/v1/integrations/sandbox/tags/{id}/mock-journey": { "post": { "description": "Sets the tag's origin (Los Angeles, Arcadia) and destination (Dallas) coordinates and injects pings along the route. `stage` sets how far the journey goes: `started` (3 pings), `in_transit` (8), `approaching` (13) or `complete` (all 15, the default). Send `{}` for the complete journey.", "operationId": "mock_journey", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockJourneyRequest" } } }, "description": "Send `{}` for the complete journey.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseObject" } } }, "description": "Pings injected and origin and destination set; `data` is `{ tag_id, stage, inserted }`" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Inject a mock Los Angeles to Dallas ping route into one of your sandbox tags.", "tags": [ "Sandbox" ] } }, "/v1/integrations/sandbox/tags/{id}/reset": { "post": { "description": "Clears the tag's pings, recipient, addresses, order ID and metadata, deletes its linked shipment and packages, and sets its state to `awaiting_first_ping`. SecreTag also clears the declared value of the deleted shipment. No request body is needed. `data` is `{ tag_id, pings_deleted, shipment_deleted, state }`.", "operationId": "reset_tag", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseObject" } } }, "description": "Tag reset" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Reset one of your sandbox tags.", "tags": [ "Sandbox" ] } }, "/v1/integrations/sandbox/tags/{id}/risk-score": { "post": { "description": "Raises a `risk.high_score` event for the tag; SecreTag relays it to your subscriptions like any other event. Send `{}` for a score of 85 with the factors `route_deviation` and `dispute_history`; `score` must be 0 to 100. No risk score record is stored. `data` is `{ tag_id, score, risk_factors, subscriptions_enqueued }`, where `subscriptions_enqueued` is the tracking network's own count for SecreTag's relay (one subscription), not the number of your subscriptions.", "operationId": "mock_risk_score", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockRiskScoreRequest" } } }, "description": "Send `{}` for a score of 85 with the default risk factors.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseObject" } } }, "description": "risk.high_score event raised" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Score must be between 0 and 100, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Emit a risk.high_score event for one of your sandbox tags.", "tags": [ "Sandbox" ] } }, "/v1/integrations/sandbox/tags/{id}/state": { "post": { "description": "Sets the tag's lifecycle state directly, skipping the normal transitions. Valid `state`: `awaiting_first_ping`, `at_origin`, `in_transit`, `approaching`, `delivered`, `delivery_verification`, `disputed_in_transit`, `completed`. `data` is `{ tag_id, state }`.", "operationId": "force_state", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForceStateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseObject" } } }, "description": "State updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid state value, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Force one of your sandbox tags into a state.", "tags": [ "Sandbox" ] } }, "/v1/integrations/sandbox/webhooks/test": { "post": { "description": "SecreTag builds its own sample event of `event_type` for your organization (realistic sample objects carrying your `organization_id`, on your first assigned tag when you have one) and queues it to each of your active subscriptions that takes that event. `subscriptions_enqueued` is the number of your matching active subscriptions. The deliveries are signed and retried like real events and appear in `list_webhook_deliveries`. Nothing is sent to the tracking network. Event types: `tag.state_changed`, `tag.delivered`, `tag.approaching`, `tag.carrier_updated`, `dispute.opened`, `dispute.resolved`, `dispute.evidence_submitted`, `shipment.created`, `shipment.delivered`, `risk.high_score`.", "operationId": "test_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseObject" } } }, "description": "Sample event queued; `data` is `{ event_type, subscriptions_enqueued }`" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "event_type missing or not one of the ten event types, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Send a sample event to your webhook subscriptions.", "tags": [ "Sandbox" ] } }, "/v1/integrations/shipments": { "get": { "description": "Your organization's shipments, each with its `insurance` (null when none is declared). Filters: `q`, `carrier`, `package_id` and `state`. `data` is always `{ items, pagination }`. Only the filters documented here are forwarded; any other query parameter is ignored. `page` is 1-based (default 1) and `limit` is 1 to 200 (default 50); any other value answers 400. `pagination` counts only your organization's items. A filter that matches more than 5,000 items on the tracking network, or a list that takes more than 20 seconds to read, answers 503 `List too large, add filters`: narrow the filters and retry.", "operationId": "list_shipments", "parameters": [ { "description": "Free-text search across master tracking number, order ID, recipient\nname/email, carrier, and child (package) tracking numbers.", "in": "query", "name": "q", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "Filter by carrier (case-insensitive, e.g. \"fedex\", \"ups\", \"usps\").", "in": "query", "name": "carrier", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "Return only the shipment that contains this package ID.", "in": "query", "name": "package_id", "required": false, "schema": { "format": "uuid", "nullable": true, "type": "string" } }, { "description": "Filter to shipments that have at least one tag with this lifecycle state.", "in": "query", "name": "state", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "Page number, 1-based. Default 1.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int32", "minimum": 1, "type": "integer" } }, { "description": "Items per page, 1 to 200. Default 50.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "format": "int32", "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseShipmentListPage" } } }, "description": "One page of your shipments (`{ items, pagination }`, always present)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`page` or `limit` is not a positive integer, or `limit` is over 200" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured, or the list is too large: add filters (`List too large, add filters`)" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List your organization's shipments.", "tags": [ "Integrations" ] }, "post": { "description": "Creates a shipment and links your tags as its packages; it does not create tags. `carrier` and `packages` (at least one) are required; each `packages[].tag_identifier` is the printed ID, BLE identifier or uuid of a tag assigned to your organization. An unknown tag, or one that is not yours, answers 404 naming it, and a tag named twice answers 400, both before anything is sent. `origin_location_id` is not supported and answers 400. Add `insurance` to declare a value (see the field); `null` is refused on create. The 201 answer carries `insurance`. If the tracking network does not answer in time, SecreTag checks whether the shipment was created and answers 201 when it was, 502 otherwise.", "operationId": "create_shipment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseShipmentWithPackages" } } }, "description": "Shipment created with linked packages" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Validation error or invalid carrier, a tag named twice, `origin_location_id`, an invalid `insurance`, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A tag is not found, or not assigned to your organization" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A tag is already assigned to another shipment" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a shipment with one or more packages, linking tags already assigned to the caller's organization.", "tags": [ "Integrations" ] } }, "/v1/integrations/shipments/{id}": { "get": { "description": "Includes `insurance`. Any id that is not one of your organization's shipments answers 404.", "operationId": "get_shipment", "parameters": [ { "description": "Shipment id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseShipmentWithPackages" } } }, "description": "Shipment detail with packages" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Shipment not found, or not your organization's" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one of your shipments with its packages.", "tags": [ "Integrations" ] }, "patch": { "description": "Updates the tracking number, carrier, addresses or recipient fields. All fields are optional; omitted fields are left unchanged. `insurance` sets the declared value and `\"insurance\": null` clears it; a body with only `insurance` changes nothing on the tracking network. The answer carries `insurance`.", "operationId": "update_shipment", "parameters": [ { "description": "Shipment id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseShipment" } } }, "description": "Updated shipment" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Validation error, an invalid `insurance`, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Shipment not found, or not your organization's" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Update one of your shipments.", "tags": [ "Integrations" ] } }, "/v1/integrations/tags": { "get": { "description": "Your organization's tags with their last known location. Filters: `state`, `search`, `order_id` and `include_archived`. Only the filters documented here are forwarded; any other query parameter is ignored. `page` is 1-based (default 1) and `limit` is 1 to 200 (default 50); any other value answers 400. `pagination` counts only your organization's items. A filter that matches more than 5,000 items on the tracking network, or a list that takes more than 20 seconds to read, answers 503 `List too large, add filters`: narrow the filters and retry.", "operationId": "list_tags", "parameters": [ { "description": "Page number, 1-based. Default 1.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int32", "minimum": 1, "type": "integer" } }, { "description": "Items per page, 1 to 200. Default 50.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "format": "int32", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Lifecycle state: `awaiting_first_ping`, `at_origin`, `in_transit`, `approaching`, `delivered`, `delivery_verification`, `disputed_in_transit` or `completed`.", "in": "query", "name": "state", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "Free-text search across the tag's printed ID, recipient name and email, and order ID.", "in": "query", "name": "search", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "Exact order ID.", "in": "query", "name": "order_id", "required": false, "schema": { "nullable": true, "type": "string" } }, { "description": "Whether to include archived tags. Default `exclude` (archived tags hidden).", "in": "query", "name": "include_archived", "required": false, "schema": { "$ref": "#/components/schemas/ArchivedFilter" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTagList" } } }, "description": "Paginated list of tags with last-known location" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`page` or `limit` is not a positive integer, or `limit` is over 200" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured, or the list is too large: add filters (`List too large, add filters`)" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List your organization's tags.", "tags": [ "Integrations" ] } }, "/v1/integrations/tags/{id}": { "get": { "description": "The tag with `ping_count`, `last_ping` and `recent_pings`.", "operationId": "get_tag", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTagWithLastPing" } } }, "description": "Tag detail with its recent pings" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one of your tags.", "tags": [ "Integrations" ] }, "patch": { "description": "Updates the recipient, address, order or metadata fields. All fields are optional; omitted fields are left unchanged. If the tag is linked to a shipment, matching fields are mirrored to the shipment.", "operationId": "update_tag", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTag" } } }, "description": "Updated tag" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Validation error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Update one of your tags.", "tags": [ "Integrations" ] } }, "/v1/integrations/tags/{id}/disputes": { "get": { "description": "Disputes opened on the tag while it was assigned to you: a dispute opened before then is not listed. Only the filters documented here are forwarded; any other query parameter is ignored. `page` is 1-based (default 1) and `limit` is 1 to 200 (default 50); any other value answers 400. `pagination` counts only your organization's items. A filter that matches more than 5,000 items on the tracking network, or a list that takes more than 20 seconds to read, answers 503 `List too large, add filters`: narrow the filters and retry.", "operationId": "list_tag_disputes", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Page number, 1-based. Default 1.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int32", "minimum": 1, "type": "integer" } }, { "description": "Items per page, 1 to 200. Default 50.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "format": "int32", "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseDisputeList" } } }, "description": "Paginated list of disputes for the tag" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`page` or `limit` is not a positive integer, or `limit` is over 200" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured, or the list is too large: add filters (`List too large, add filters`)" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List the disputes of one of your tags.", "tags": [ "Integrations" ] } }, "/v1/integrations/tags/{id}/evidence": { "get": { "description": "Everything the evidence PDF of the tag's most recent dispute with generated evidence contains, as JSON: the dispute, delivery metrics, carrier data and location proof. Answers 404 when no evidence has been generated for the tag, and when the tag's evidence belongs to a dispute opened before the tag was assigned to you.", "operationId": "get_tag_evidence", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTagEvidence" } } }, "description": "Full evidence data for the tag's most recent dispute with a generated PDF" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found or not assigned to your organization, or no evidence has been generated for this tag" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get the evidence data of one of your tags.", "tags": [ "Integrations" ] } }, "/v1/integrations/tags/{id}/journey": { "get": { "description": "The tag's ping locations, in order. Not paginated.", "operationId": "get_journey", "parameters": [ { "description": "The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseTagJourney" } } }, "description": "Ping journey for the tag" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Tag not found, or not assigned to your organization" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get the ping journey of one of your tags.", "tags": [ "Integrations" ] } }, "/v1/integrations/webhooks": { "get": { "description": "SecreTag's own subscriptions for your organization in this environment, active ones first and newest first within each group, as a bare array (not paginated).", "operationId": "list_webhooks", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookSubscriptionList" } } }, "description": "Your webhook subscriptions" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List your webhook subscriptions.", "tags": [ "Integrations" ] }, "post": { "description": "`target_url` must be an HTTPS URL on a public address. `event_types` lists the events to receive; omit it or send `null` for every event. The ten event types: `tag.state_changed`, `tag.delivered`, `tag.approaching`, `tag.carrier_updated`, `dispute.opened`, `dispute.resolved`, `dispute.evidence_submitted`, `shipment.created`, `shipment.delivered`, `risk.high_score`. The signing `secret` is returned once, in this response only: store it. Every delivery carries `X-SecreTag-Signature: sha256=` keyed with that secret, with `X-SecreTag-Event` and `X-SecreTag-Delivery`. A delivery succeeds only on a 2xx answer and is retried up to 8 attempts in all (waits of 30 s, 2 min, 10 min, 30 min, 1 h, 3 h and 8 h).", "operationId": "create_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookSubscriptionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookSubscriptionCreated" } } }, "description": "Subscription created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "target_url missing, not HTTPS or not on a public address, an unknown event type, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a webhook subscription.", "tags": [ "Integrations" ] } }, "/v1/integrations/webhooks/{id}": { "delete": { "description": "The subscription stops receiving events and its pending deliveries are cancelled. Answers 204 with no body.", "operationId": "delete_webhook", "parameters": [ { "description": "Webhook subscription id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Subscription deactivated" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Subscription not found, or not your organization's" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Deactivate one of your webhook subscriptions.", "tags": [ "Integrations" ] } }, "/v1/integrations/webhooks/{id}/deliveries": { "get": { "description": "SecreTag's own delivery log for the subscription, newest first. `page` is 1-based (default 1) and `limit` is 1 to 200 (default 50); any other value answers 400.", "operationId": "list_webhook_deliveries", "parameters": [ { "description": "Webhook subscription id", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Page number, 1-based. Default 1.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "format": "int32", "minimum": 1, "type": "integer" } }, { "description": "Items per page, 1 to 200. Default 50.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "format": "int32", "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWebhookDeliveryList" } } }, "description": "One page of the subscription's delivery log" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`page` or `limit` is not a positive integer, or `limit` is over 200" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Subscription not found, or not your organization's" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List the deliveries of one of your webhook subscriptions.", "tags": [ "Integrations" ] } }, "/v1/risk/address/{hash}": { "get": { "description": "Answers 404 unless your organization assessed this address hash before, with `assess_address` or `assess_batch`. The score is the tracking network's one record for the address: `created_at` and `updated_at` are when the network first and last scored the address for any of its customers, and `address_input` is the input it keeps. The dispute-history signal of a score is computed by the tracking network over the history of every SecreTag customer.", "operationId": "get_address_score", "parameters": [ { "description": "Normalized address hash, as returned in `address_hash`", "in": "path", "name": "hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseAddressRiskScore" } } }, "description": "Cached risk score for the address" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "No score found for this address, or your organization has not assessed it" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a stored risk score by address hash.", "tags": [ "Risk" ] } }, "/v1/risk/assess": { "post": { "description": "Returns the address's risk score and its six signals; the `address_hash` is recorded for your organization, so `get_address_score` can read it later. The dispute-history signal of a score is computed by the tracking network over the history of every SecreTag customer.", "operationId": "assess_address", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessAddressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseRiskAssessment" } } }, "description": "Risk assessment result for the address" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid address, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Score one delivery address.", "tags": [ "Risk" ] } }, "/v1/risk/batch": { "post": { "description": "`addresses` must hold 1 to 100 addresses; anything else answers 400 before anything is sent. `cached` counts the results whose address hash your organization had assessed before this call. The dispute-history signal of a score is computed by the tracking network over the history of every SecreTag customer.", "operationId": "assess_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAssessRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseBatchAssess" } } }, "description": "Batch risk assessment results" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "`addresses must be an array of 1 to 100 addresses`, an invalid address, or a malformed JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing, unknown or revoked API key, or a key of the other environment (`Invalid API key`)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body too large (limit 1 MB)" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream unavailable: the tracking network timed out, could not be reached or failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upstream not configured" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Score up to 100 addresses.", "tags": [ "Risk" ] } } }, "servers": [ { "description": "Production", "url": "https://api.secretag.co" }, { "description": "Sandbox", "url": "https://sandbox-api.secretag.co" } ], "tags": [ { "description": "Server-to-server access to your tags, shipments, alerts, disputes and webhook subscriptions. There is no tag-creation operation: tags are hardware that SecreTag assigns to your organization.", "name": "Integrations" }, { "description": "Sandbox-only operations for integration testing: inject mock pings, alerts, disputes and carrier events, force a tag state, reset a tag and send sample webhook events, without live hardware. They run only on `sandbox-api.secretag.co`; on `api.secretag.co` they answer 403.", "name": "Sandbox" }, { "description": "Address risk scoring.", "name": "Risk" } ] }