SecreTag API

Version 1.0.0

Server-to-server REST API for SecreTag package tracking integrations.

On this page

Getting started

Ask SecreTag support for an API key at support@secretag.co. A test key starts with st_test_, a live key with st_live_.
Pick the host: https://sandbox-api.secretag.co with a test key while you build, https://api.secretag.co with a live key.

Make your first call, listing your tags. Replace API_KEY with your test key.

curl -X GET "https://sandbox-api.secretag.co/v1/integrations/tags" \
  -H "X-API-Key: API_KEY"

Read the answer: every JSON answer is the same response envelope, with your result in data when success is true and a message in error when it is false.

Authentication

Every 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.

Response envelope

Every JSON answer, success or error, is { "success": boolean, "data": <payload or null>, "error": <message or null> }. 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.

Tenancy

A 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.

Limits and errors

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.
Organization rate limit: 600 requests per minute per organization; past it, 429 Rate limit exceeded: 600 requests per minute.
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.
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.

Lists

The 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.

Declared value insurance

A 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.

Webhooks

Webhook 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:

X-SecreTag-Signature: sha256=<hex HMAC-SHA256 of the raw body>, keyed with the subscription's secret
X-SecreTag-Event: the event type
X-SecreTag-Delivery: the delivery id

A 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.

Verifying a delivery

Every delivery carries X-SecreTag-Signature: sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with your subscription's secret. Check it over the exact bytes you received, before any JSON parsing, with a constant-time comparison, and refuse the delivery when it does not match.

Ruby

In Ruby, with the standard library (in Rails, pass request.raw_post as the body):

require "openssl"

# header is the X-SecreTag-Signature value, raw_body the bytes you received.
def valid_signature?(secret, raw_body, header)
  expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, raw_body)
  header = header.to_s
  expected.bytesize == header.bytesize &&
    OpenSSL.fixed_length_secure_compare(expected, header)
end

Node.js

In Node.js, with the built-in crypto module (in Express, read the body with express.raw()):

const crypto = require("node:crypto");

// header is the X-SecreTag-Signature value, rawBody the bytes you received.
function validSignature(secret, rawBody, header) {
  const hex = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const expected = Buffer.from("sha256=" + hex);
  const given = Buffer.from(String(header ?? ""));
  return expected.length === given.length &&
    crypto.timingSafeEqual(expected, given);
}

Testing in the sandbox

The 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.

Integrations

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.

GET `/v1/integrations/alerts` List your organization's alerts.

Request, responses and example

Operation list_alerts

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.

Parameters of list_alerts

Query parameters:

Parameters of list_alerts
Name	In	Type	Required	Description
`page`	query	integer (int32)	No	Page number, 1-based. Default 1.
`limit`	query	integer (int32)	No	Items per page, 1 to 200. Default 50.
`type`	query	string, nullable	No	Alert type, for example `geofence`, `delivery`, `dispute`, `system`, `package_separation` or `gps_carrier_mismatch`.
`severity`	query	AlertSeverity, nullable	No	`info`, `warning` or `critical`.
`unread_only`	query	boolean, nullable	No	`true` for unread alerts only.
`read`	query	boolean, nullable	No	`false` for unread alerts, `true` for read ones; omit for all.
`tag_id`	query	string, nullable	No	A tag's uuid, printed ID or BLE identifier. A tag not assigned to your organization returns an empty page.

Responses of list_alerts

200 Paginated list of alerts

data: AlertListPage

Fields of data:

Response 200 fields of list_alerts
Field	Type	Required	Description
`items`	array of Alert	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

400 page or limit is not a positive integer, or limit is over 200
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured, or the list is too large: add filters (List too large, add filters)

Example request of list_alerts

curl -X GET "https://api.secretag.co/v1/integrations/alerts" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_

POST `/v1/integrations/alerts/read-all` Mark all your unread alerts as read.

Request, responses and example

Operation mark_all_alerts_read

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.

Responses of mark_all_alerts_read

200 Your unread alerts marked read; data is { "marked_read": <count> }

data: any
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of mark_all_alerts_read

curl -X POST "https://api.secretag.co/v1/integrations/alerts/read-all" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_

GET `/v1/integrations/alerts/summary` Alert counts for your organization.

Request, responses and example

Operation alert_summary

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.

Responses of alert_summary

200 Alert counts (total, unread, critical unread)

data: AlertSummary

Fields of data:

Response 200 fields of alert_summary
Field	Type	Required
`critical_unread`	integer (int64)	Yes
`total`	integer (int64)	Yes
`unread`	integer (int64)	Yes

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of alert_summary

curl -X GET "https://api.secretag.co/v1/integrations/alerts/summary" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_

PATCH `/v1/integrations/alerts/{id}/read` Mark one of your alerts as read.

Request, responses and example

Operation mark_alert_read

Any id that is not one of your organization's alerts answers 404 and nothing is changed.

Parameters of mark_alert_read

Path parameters:

Parameters of mark_alert_read
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Alert id

Responses of mark_alert_read

200 Alert marked read

data: MarkReadResponse

Fields of data:

Response 200 fields of mark_alert_read
Field	Type	Required	Description
`id`	string (uuid)	Yes
`read_at`	string (date-time)	Yes

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Alert not found, not your organization's, or already read
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of mark_alert_read

curl -X PATCH "https://api.secretag.co/v1/integrations/alerts/ID/read" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the alert id

GET `/v1/integrations/disputes` List your organization's disputes.

Request, responses and example

Operation list_disputes

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.

Parameters of list_disputes

Query parameters:

Parameters of list_disputes
Name	In	Type	Required	Description
`page`	query	integer (int32)	No	Page number, 1-based. Default 1.
`limit`	query	integer (int32)	No	Items per page, 1 to 200. Default 50.
`status`	query	string, nullable	No	`open`, `investigating` or `resolved`.
`type`	query	string, nullable	No	Dispute type: `not_delivered`, `damaged`, `wrong_location` or `other`.
`tag_id`	query	string, nullable	No	A tag's uuid, printed ID or BLE identifier. A tag not assigned to your organization returns an empty page.

Responses of list_disputes

200 Paginated list of disputes

data: DisputeListPage

Fields of data:

Response 200 fields of list_disputes
Field	Type	Required	Description
`items`	array of Dispute	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

400 page or limit is not a positive integer, or limit is over 200
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured, or the list is too large: add filters (List too large, add filters)

Example request of list_disputes

curl -X GET "https://api.secretag.co/v1/integrations/disputes" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_

GET `/v1/integrations/disputes/stats` Dispute statistics for your organization.

Request, responses and example

Operation dispute_stats

Computed by SecreTag from your organization's disputes, never forwarded:

total: your disputes. open, investigating and resolved: those with that status (a dispute with another status counts in total only).
shopify_submitted: your disputes that carry a shopify_submitted_at.
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.
evidence_generated: the number of your disputes for which SecreTag recorded a successful generate_evidence call through this API.
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.

Reading 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.

Responses of dispute_stats

200 Dispute counts and figures for your organization

data: DisputeStatsResponse

Fields of data:

Response 200 fields of dispute_stats
Field	Type	Required	Description
`amount_at_risk`	number (double)	Yes	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.
`avg_resolution_hours`	number (double), nullable	No	Mean hours from open to resolution, two decimals; null when no dispute is resolved.
`evidence_generated`	integer (int64)	Yes	Your disputes for which SecreTag recorded a successful `generate_evidence` call.
`investigating`	integer (int64)	Yes
`open`	integer (int64)	Yes
`resolved`	integer (int64)	Yes
`shopify_submitted`	integer (int64)	Yes	Your disputes that carry a `shopify_submitted_at`.
`total`	integer (int64)	Yes

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of dispute_stats

curl -X GET "https://api.secretag.co/v1/integrations/disputes/stats" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_

GET `/v1/integrations/disputes/{id}` Get one of your disputes.

Request, responses and example

Operation get_dispute

Any id that is not one of your organization's disputes answers 404.

Parameters of get_dispute

Path parameters:

Parameters of get_dispute
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Dispute id

Responses of get_dispute

200 Dispute detail

data: Dispute

Fields of data:

Response 200 fields of get_dispute
Field	Type	Required	Description
`customer_claim`	string, nullable	No
`evidence_score`	integer (int32), nullable	No
`id`	string (uuid)	Yes
`metadata`	object	Yes
`opened_at`	string (date-time)	Yes
`organization_id`	string (uuid)	Yes
`resolution`	string, nullable	No
`resolved_at`	string (date-time), nullable	No
`resolved_by`	string (uuid), nullable	No
`shopify_submission_status`	string, nullable	No
`shopify_submitted_at`	string (date-time), nullable	No
`status`	string	Yes
`tag_id`	string (uuid)	Yes
`tag_serial`	string, nullable	No	The tag's printed ID, when known.
`type`	string, nullable	No

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Dispute not found, or not your organization's
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of get_dispute

curl -X GET "https://api.secretag.co/v1/integrations/disputes/ID" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the dispute id

POST `/v1/integrations/disputes/{id}/evidence/generate` Generate the evidence PDF for one of your disputes.

Request, responses and example

Operation generate_evidence

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.

Parameters of generate_evidence

Path parameters:

Parameters of generate_evidence
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Dispute id

Responses of generate_evidence

200 Evidence PDF generated and stored

data: GenerateEvidenceResponse

Fields of data:

Response 200 fields of generate_evidence
Field	Type	Required	Description
`evidence_pdf_key`	string	Yes	Where the tracking network stored the evidence PDF; download it with `get_evidence_pdf`.
`generated_at`	string	Yes	RFC 3339 timestamp of generation.

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Dispute or tag not found, or not your organization's
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured, or evidence storage is unavailable on the tracking network (its 503, passed through)

Example request of generate_evidence

curl -X POST "https://api.secretag.co/v1/integrations/disputes/ID/evidence/generate" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the dispute id

GET `/v1/integrations/disputes/{id}/evidence/pdf` Download the evidence PDF for one of your disputes.

Request, responses and example

Operation get_evidence_pdf

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.

Parameters of get_evidence_pdf

Path parameters:

Parameters of get_evidence_pdf
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Dispute id

Responses of get_evidence_pdf

200 Evidence PDF

Body: PDF bytes
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 No evidence PDF generated for this dispute, or the dispute is not your organization's
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured, or evidence storage is unavailable on the tracking network (its 503, passed through)

Example request of get_evidence_pdf

curl -X GET "https://api.secretag.co/v1/integrations/disputes/ID/evidence/pdf" \
  -H "X-API-Key: API_KEY" \
  -o evidence.pdf

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the dispute id

POST `/v1/integrations/disputes/{id}/resolve` Resolve one of your disputes.

Request, responses and example

Operation resolve_dispute

resolution is required free text; evidence_score is optional (0 to 100). An API key carries no user, so resolved_by stays null.

Parameters of resolve_dispute

Path parameters:

Parameters of resolve_dispute
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Dispute id

Request body of resolve_dispute

ResolveDisputeRequest, required

Fields of the request body:

Request fields of resolve_dispute
Field	Type	Required	Description
`evidence_score`	integer (int32), nullable	No
`resolution`	string	Yes

Responses of resolve_dispute

200 Dispute resolved

data: Dispute

Fields of data:

Response 200 fields of resolve_dispute
Field	Type	Required	Description
`customer_claim`	string, nullable	No
`evidence_score`	integer (int32), nullable	No
`id`	string (uuid)	Yes
`metadata`	object	Yes
`opened_at`	string (date-time)	Yes
`organization_id`	string (uuid)	Yes
`resolution`	string, nullable	No
`resolved_at`	string (date-time), nullable	No
`resolved_by`	string (uuid), nullable	No
`shopify_submission_status`	string, nullable	No
`shopify_submitted_at`	string (date-time), nullable	No
`status`	string	Yes
`tag_id`	string (uuid)	Yes
`tag_serial`	string, nullable	No	The tag's printed ID, when known.
`type`	string, nullable	No

400 Malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Dispute not found, not your organization's, or already resolved
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of resolve_dispute

curl -X POST "https://api.secretag.co/v1/integrations/disputes/ID/resolve" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "evidence_score": 85,
  "resolution": "Confirmed delivered: package located at rear entrance."
}'

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the dispute id

GET `/v1/integrations/shipments` List your organization's shipments.

Request, responses and example

Operation list_shipments

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.

Parameters of list_shipments

Query parameters:

Parameters of list_shipments
Name	In	Type	Required	Description
`q`	query	string, nullable	No	Free-text search across master tracking number, order ID, recipient name/email, carrier, and child (package) tracking numbers.
`carrier`	query	string, nullable	No	Filter by carrier (case-insensitive, e.g. "fedex", "ups", "usps").
`package_id`	query	string (uuid), nullable	No	Return only the shipment that contains this package ID.
`state`	query	string, nullable	No	Filter to shipments that have at least one tag with this lifecycle state.
`page`	query	integer (int32)	No	Page number, 1-based. Default 1.
`limit`	query	integer (int32)	No	Items per page, 1 to 200. Default 50.

Responses of list_shipments

200 One page of your shipments ({ items, pagination }, always present)

data: ShipmentListPage

Fields of data:

Response 200 fields of list_shipments
Field	Type	Required	Description
`items`	array of Shipment	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

400 page or limit is not a positive integer, or limit is over 200
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured, or the list is too large: add filters (List too large, add filters)

Example request of list_shipments

curl -X GET "https://api.secretag.co/v1/integrations/shipments" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_

POST `/v1/integrations/shipments` Create a shipment with one or more packages, linking tags already assigned to the caller's organization.

Request, responses and example

Operation create_shipment

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.

Request body of create_shipment

CreateShipmentRequest, required

Fields of the request body:

Request fields of create_shipment
Field	Type	Required	Description
`carrier`	string	Yes
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`insurance`	ShipmentInsuranceRequest, nullable	No	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.
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No	Not supported by SecreTag: a request that names it answers 400.
`packages`	array of CreatePackageEntry	Yes	Packages to create: each names a tag and an optional child tracking number.
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No	Service level (e.g., ground, express, priority, next_day, economy)

Responses of create_shipment

201 Shipment created with linked packages

data: ShipmentWithPackages

Fields of data:

Response 201 fields of create_shipment
Field	Type	Required	Description
`carrier`	string	Yes
`created_at`	string (date-time)	Yes
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`id`	string (uuid)	Yes
`insurance`	ShipmentInsurance, nullable	Yes	The declared value SecreTag keeps for this shipment; null when none is declared. Present on every shipment SecreTag returns.
`master_status`	string, nullable	No
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No
`public_id`	string	Yes
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No
`updated_at`	string (date-time)	Yes
`packages`	array of ShipmentPackage	Yes

400 Validation error or invalid carrier, a tag named twice, origin_location_id, an invalid insurance, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 A tag is not found, or not assigned to your organization
409 A tag is already assigned to another shipment
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of create_shipment

curl -X POST "https://api.secretag.co/v1/integrations/shipments" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Replace the following:

API_KEY: your live key, which starts with st_live_

GET `/v1/integrations/shipments/{id}` Get one of your shipments with its packages.

Request, responses and example

Operation get_shipment

Includes insurance. Any id that is not one of your organization's shipments answers 404.

Parameters of get_shipment

Path parameters:

Parameters of get_shipment
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Shipment id

Responses of get_shipment

200 Shipment detail with packages

data: ShipmentWithPackages

Fields of data:

Response 200 fields of get_shipment
Field	Type	Required	Description
`carrier`	string	Yes
`created_at`	string (date-time)	Yes
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`id`	string (uuid)	Yes
`insurance`	ShipmentInsurance, nullable	Yes	The declared value SecreTag keeps for this shipment; null when none is declared. Present on every shipment SecreTag returns.
`master_status`	string, nullable	No
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No
`public_id`	string	Yes
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No
`updated_at`	string (date-time)	Yes
`packages`	array of ShipmentPackage	Yes

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Shipment not found, or not your organization's
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of get_shipment

curl -X GET "https://api.secretag.co/v1/integrations/shipments/ID" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the shipment id

PATCH `/v1/integrations/shipments/{id}` Update one of your shipments.

Request, responses and example

Operation update_shipment

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.

Parameters of update_shipment

Path parameters:

Parameters of update_shipment
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Shipment id

Request body of update_shipment

UpdateShipmentRequest, required

Fields of the request body:

Request fields of update_shipment
Field	Type	Required	Description
`carrier`	string, nullable	No
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`insurance`	ShipmentInsuranceRequest, nullable	No	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.
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No	Service level (e.g., ground, express, priority, next_day, economy)

Responses of update_shipment

200 Updated shipment

data: Shipment

Fields of data:

Response 200 fields of update_shipment
Field	Type	Required	Description
`carrier`	string	Yes
`created_at`	string (date-time)	Yes
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`id`	string (uuid)	Yes
`insurance`	ShipmentInsurance, nullable	Yes	The declared value SecreTag keeps for this shipment; null when none is declared. Present on every shipment SecreTag returns.
`master_status`	string, nullable	No
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No
`public_id`	string	Yes
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No
`updated_at`	string (date-time)	Yes

400 Validation error, an invalid insurance, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Shipment not found, or not your organization's
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of update_shipment

curl -X PATCH "https://api.secretag.co/v1/integrations/shipments/ID" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the shipment id

GET `/v1/integrations/tags` List your organization's tags.

Request, responses and example

Operation list_tags

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.

Parameters of list_tags

Query parameters:

Parameters of list_tags
Name	In	Type	Required	Description
`page`	query	integer (int32)	No	Page number, 1-based. Default 1.
`limit`	query	integer (int32)	No	Items per page, 1 to 200. Default 50.
`state`	query	string, nullable	No	Lifecycle state: `awaiting_first_ping`, `at_origin`, `in_transit`, `approaching`, `delivered`, `delivery_verification`, `disputed_in_transit` or `completed`.
`search`	query	string, nullable	No	Free-text search across the tag's printed ID, recipient name and email, and order ID.
`order_id`	query	string, nullable	No	Exact order ID.
`include_archived`	query	ArchivedFilter	No	Whether to include archived tags. Default `exclude` (archived tags hidden).

Responses of list_tags

200 Paginated list of tags with last-known location

data: TagListPage

Fields of data:

Response 200 fields of list_tags
Field	Type	Required	Description
`items`	array of TagWithLastPing	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

400 page or limit is not a positive integer, or limit is over 200
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured, or the list is too large: add filters (List too large, add filters)

Example request of list_tags

curl -X GET "https://api.secretag.co/v1/integrations/tags" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_

GET `/v1/integrations/tags/{id}` Get one of your tags.

Request, responses and example

Operation get_tag

The tag with ping_count, last_ping and recent_pings.

Parameters of get_tag

Path parameters:

Parameters of get_tag
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Responses of get_tag

200 Tag detail with its recent pings

data: TagWithLastPing

Fields of data:

Response 200 fields of get_tag
Field	Type	Required	Description
`archived_at`	string (date-time), nullable	No
`auto_off_after_delivery`	boolean, nullable	No	Per-tag override of the organization's deactivate-after-delivery setting; null inherits the organization default.
`auto_off_at`	string (date-time), nullable	No	The scheduled automatic switch-off time, when known.
`auto_off_state`	string, nullable	No	`active`, `scheduled` or `off`: the tag's automatic switch-off state; null when not known.
`ble_identifier`	string	Yes
`created_at`	string (date-time)	Yes
`delivered_at`	string (date-time), nullable	No
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`geofence_radius_m`	integer (int32)	Yes
`id`	string (uuid)	Yes
`metadata`	object	Yes
`network_coverage_months`	integer (int32), nullable	No	The network coverage months sold for this tag's device, when known (read only).
`network_device_id`	string, nullable	No
`network_last_checked`	string (date-time), nullable	No
`network_off_override_at`	string (date-time), nullable	No	An explicit network switch-off time set for this tag's device, or null (read only).
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No	The origin location the tag was created with, if any (read only).
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`shipment_package_id`	string (uuid), nullable	No
`shipped_at`	string (date-time), nullable	No
`state`	string	Yes
`last_ping`	LastPing	No	Summary of last ping for a tag
`ping_count`	integer	Yes
`recent_pings`	array of LastPing	No
`self_serve`	SelfServeCarrierData	No	Carrier fields of a tag activated outside a shipment (a self-serve tag).

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Tag not found, or not assigned to your organization
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of get_tag

curl -X GET "https://api.secretag.co/v1/integrations/tags/ID" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

PATCH `/v1/integrations/tags/{id}` Update one of your tags.

Request, responses and example

Operation update_tag

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.

Parameters of update_tag

Path parameters:

Parameters of update_tag
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Request body of update_tag

UpdateTagRequest, required

Fields of the request body:

Request fields of update_tag
Field	Type	Required	Description
`auto_off_after_delivery`	boolean, nullable	No	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.
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`geofence_radius_m`	integer (int32), nullable	No
`metadata`	object, nullable	No
`network_coverage_months`	integer (int32), nullable	No	Accepted and not acted on by this operation.
`network_off_override_at`	string (date-time), nullable	No	Accepted and not acted on by this operation.
`order_id`	string, nullable	No
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No

Responses of update_tag

200 Updated tag

data: Tag

Fields of data:

Response 200 fields of update_tag
Field	Type	Required	Description
`archived_at`	string (date-time), nullable	No
`auto_off_after_delivery`	boolean, nullable	No	Per-tag override of the organization's deactivate-after-delivery setting; null inherits the organization default.
`auto_off_at`	string (date-time), nullable	No	The scheduled automatic switch-off time, when known.
`auto_off_state`	string, nullable	No	`active`, `scheduled` or `off`: the tag's automatic switch-off state; null when not known.
`ble_identifier`	string	Yes
`created_at`	string (date-time)	Yes
`delivered_at`	string (date-time), nullable	No
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`geofence_radius_m`	integer (int32)	Yes
`id`	string (uuid)	Yes
`metadata`	object	Yes
`network_coverage_months`	integer (int32), nullable	No	The network coverage months sold for this tag's device, when known (read only).
`network_device_id`	string, nullable	No
`network_last_checked`	string (date-time), nullable	No
`network_off_override_at`	string (date-time), nullable	No	An explicit network switch-off time set for this tag's device, or null (read only).
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No	The origin location the tag was created with, if any (read only).
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`shipment_package_id`	string (uuid), nullable	No
`shipped_at`	string (date-time), nullable	No
`state`	string	Yes

400 Malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Tag not found, or not assigned to your organization
413 Request body too large (limit 1 MB)
422 Validation error
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of update_tag

curl -X PATCH "https://api.secretag.co/v1/integrations/tags/ID" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

GET `/v1/integrations/tags/{id}/disputes` List the disputes of one of your tags.

Request, responses and example

Operation list_tag_disputes

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.

Parameters of list_tag_disputes

Path and query parameters:

Parameters of list_tag_disputes
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.
`page`	query	integer (int32)	No	Page number, 1-based. Default 1.
`limit`	query	integer (int32)	No	Items per page, 1 to 200. Default 50.

Responses of list_tag_disputes

200 Paginated list of disputes for the tag

data: DisputeListPage

Fields of data:

Response 200 fields of list_tag_disputes
Field	Type	Required	Description
`items`	array of Dispute	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

400 page or limit is not a positive integer, or limit is over 200
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Tag not found, or not assigned to your organization
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured, or the list is too large: add filters (List too large, add filters)

Example request of list_tag_disputes

curl -X GET "https://api.secretag.co/v1/integrations/tags/ID/disputes" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

GET `/v1/integrations/tags/{id}/evidence` Get the evidence data of one of your tags.

Request, responses and example

Operation get_tag_evidence

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.

Parameters of get_tag_evidence

Path parameters:

Parameters of get_tag_evidence
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Responses of get_tag_evidence

200 Full evidence data for the tag's most recent dispute with a generated PDF

data: TagEvidenceResponse

Fields of data:

Response 200 fields of get_tag_evidence
Field	Type	Required	Description
`carrier`	string, nullable	No
`carrier_delivered_at`	string (date-time), nullable	No
`carrier_events`	any	No	Carrier scan events array. Each entry has `timestamp`, `status`, `location`, and `description` string fields.
`carrier_status`	string, nullable	No
`destination_address`	string, nullable	No
`dispute`	Dispute	Yes	Delivery dispute
`dwell_time_secs`	integer (int64), nullable	No	Seconds the tag was stationary at the destination address. Null when fewer than 2 pings were recorded near the destination.
`evidence_generated_at`	string (date-time), nullable	No	When the evidence PDF was generated.
`location_proof`	array of EvidenceLocationProofEntry	Yes	Up to 50 most recent BLE location reports, oldest-first.
`origin_address`	string, nullable	No
`pings_at_destination`	integer (int64)	Yes	Pings detected within 150 m of the destination coordinates.
`tag_count`	integer (int64)	Yes	Number of tags in the shipment (> 1 means multi-box).
`total_pings`	integer (int64)	Yes	Total BLE location reports recorded across all tags in the shipment.
`tracking_number`	string, nullable	No

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Tag not found or not assigned to your organization, or no evidence has been generated for this tag
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of get_tag_evidence

curl -X GET "https://api.secretag.co/v1/integrations/tags/ID/evidence" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

GET `/v1/integrations/tags/{id}/journey` Get the ping journey of one of your tags.

Request, responses and example

Operation get_journey

The tag's ping locations, in order. Not paginated.

Parameters of get_journey

Path parameters:

Parameters of get_journey
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Responses of get_journey

200 Ping journey for the tag

data: TagJourneyResponse

Fields of data:

Response 200 fields of get_journey
Field	Type	Required
`points`	array of JourneyPoint	Yes
`tag_id`	string (uuid)	Yes
`total_points`	integer (int64)	Yes

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Tag not found, or not assigned to your organization
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of get_journey

curl -X GET "https://api.secretag.co/v1/integrations/tags/ID/journey" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

GET `/v1/integrations/webhooks` List your webhook subscriptions.

Request, responses and example

Operation list_webhooks

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).

Responses of list_webhooks

200 Your webhook subscriptions

data: array of WebhookSubscription

Fields of data:

Response 200 fields of list_webhooks
Field	Type	Required	Description
`created_at`	string (date-time)	Yes
`event_types`	array of string, one of tag.state_changed, tag.delivered, tag.approaching, tag.carrier_updated, dispute.opened, dispute.resolved, dispute.evidence_submitted, shipment.created, shipment.delivered, risk.high_score, nullable	No	The event types the subscription takes; `null` for every event.
`id`	string (uuid)	Yes
`is_active`	boolean	Yes
`label`	string, nullable	No
`organization_id`	string (uuid)	Yes
`target_url`	string	Yes
`updated_at`	string (date-time)	Yes

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address

Example request of list_webhooks

curl -X GET "https://api.secretag.co/v1/integrations/webhooks" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_

POST `/v1/integrations/webhooks` Create a webhook subscription.

Request, responses and example

Operation create_webhook

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=<hex HMAC-SHA256 of the raw body> 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).

Request body of create_webhook

CreateWebhookSubscriptionRequest, required

Fields of the request body:

Request fields of create_webhook
Field	Type	Required	Description
`event_types`	array of string, one of tag.state_changed, tag.delivered, tag.approaching, tag.carrier_updated, dispute.opened, dispute.resolved, dispute.evidence_submitted, shipment.created, shipment.delivered, risk.high_score, nullable	No	The event types to receive; omit or `null` for every event.
`label`	string, nullable	No
`target_url`	string	Yes	An HTTPS URL on a public address.

Responses of create_webhook

201 Subscription created

data: CreateWebhookSubscriptionResponse

Fields of data:

Response 201 fields of create_webhook
Field	Type	Required	Description
`created_at`	string (date-time)	Yes
`event_types`	array of string, one of tag.state_changed, tag.delivered, tag.approaching, tag.carrier_updated, dispute.opened, dispute.resolved, dispute.evidence_submitted, shipment.created, shipment.delivered, risk.high_score, nullable	No	The event types the subscription takes; `null` for every event.
`id`	string (uuid)	Yes
`is_active`	boolean	Yes
`label`	string, nullable	No
`organization_id`	string (uuid)	Yes
`secret`	string, nullable	No	The signing secret, returned once in this response and never again. Verify each delivery's `X-SecreTag-Signature: sha256=<hex HMAC-SHA256 of the raw body>` with it.
`target_url`	string	Yes
`updated_at`	string (date-time)	Yes

400 target_url missing, not HTTPS or not on a public address, an unknown event type, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address

Example request of create_webhook

curl -X POST "https://api.secretag.co/v1/integrations/webhooks" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "tag.state_changed",
    "tag.delivered",
    "shipment.created"
  ],
  "label": "My integration",
  "target_url": "https://your-server.com/webhooks/secretag"
}'

Replace the following:

API_KEY: your live key, which starts with st_live_

DELETE `/v1/integrations/webhooks/{id}` Deactivate one of your webhook subscriptions.

Request, responses and example

Operation delete_webhook

The subscription stops receiving events and its pending deliveries are cancelled. Answers 204 with no body.

Parameters of delete_webhook

Path parameters:

Parameters of delete_webhook
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Webhook subscription id

Responses of delete_webhook

204 Subscription deactivated
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Subscription not found, or not your organization's
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address

Example request of delete_webhook

curl -X DELETE "https://api.secretag.co/v1/integrations/webhooks/ID" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the webhook subscription id

GET `/v1/integrations/webhooks/{id}/deliveries` List the deliveries of one of your webhook subscriptions.

Request, responses and example

Operation list_webhook_deliveries

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.

Parameters of list_webhook_deliveries

Path and query parameters:

Parameters of list_webhook_deliveries
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	Webhook subscription id
`page`	query	integer (int32)	No	Page number, 1-based. Default 1.
`limit`	query	integer (int32)	No	Items per page, 1 to 200. Default 50.

Responses of list_webhook_deliveries

200 One page of the subscription's delivery log

data: WebhookDeliveryListPage

Fields of data:

Response 200 fields of list_webhook_deliveries
Field	Type	Required	Description
`items`	array of WebhookDelivery	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

400 page or limit is not a positive integer, or limit is over 200
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 Subscription not found, or not your organization's
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address

Example request of list_webhook_deliveries

curl -X GET "https://api.secretag.co/v1/integrations/webhooks/ID/deliveries" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
ID: the webhook subscription id

Sandbox

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.

POST `/v1/integrations/sandbox/tags/{id}/alert` Inject a fake alert on one of your sandbox tags.

Request, responses and example

Operation mock_alert

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.

Parameters of mock_alert

Path parameters:

Parameters of mock_alert
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Request body of mock_alert

MockAlertRequest, required

Fields of the request body:

Request fields of mock_alert
Field	Type	Required	Description
`alert_type`	string	No	Alert type. Defaults to `delivery`. One of: geofence, delivery, dispute, system, package_separation, gps_carrier_mismatch
`severity`	string	No	Alert severity. Defaults to `warning`. One of: info, warning, critical

Responses of mock_alert

200 Alert created

data: Alert

Fields of data:

Response 200 fields of mock_alert
Field	Type	Required	Description
`created_at`	string (date-time)	Yes
`id`	string (uuid)	Yes
`message`	string, nullable	No
`metadata`	object	Yes
`organization_id`	string (uuid)	Yes
`read_at`	string (date-time), nullable	No
`severity`	string	Yes
`tag_id`	string (uuid)	Yes
`tag_serial`	string, nullable	No	The tag's printed ID, when known.
`title`	string	Yes
`type`	string	Yes

400 Invalid alert_type or severity, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
403 Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)
404 Tag not found, or not assigned to your organization
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of mock_alert

curl -X POST "https://sandbox-api.secretag.co/v1/integrations/sandbox/tags/ID/alert" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "alert_type": "delivery",
  "severity": "warning"
}'

Replace the following:

API_KEY: your test key, which starts with st_test_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

POST `/v1/integrations/sandbox/tags/{id}/carrier-event` Inject a fake carrier status on the tag's shipment package.

Request, responses and example

Operation mock_carrier_event

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.

Parameters of mock_carrier_event

Path parameters:

Parameters of mock_carrier_event
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Request body of mock_carrier_event

MockCarrierEventRequest, required

Fields of the request body:

Request fields of mock_carrier_event
Field	Type	Required	Description
`status`	string	Yes	Carrier status. One of: in_transit, out_for_delivery, delivered, exception

Responses of mock_carrier_event

200 Carrier status updated on the tag's package; data is { tag_id, package_id, status }

data: any
400 Invalid status, the tag is not linked to a shipment, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
403 Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)
404 Tag not found, or not assigned to your organization
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of mock_carrier_event

curl -X POST "https://sandbox-api.secretag.co/v1/integrations/sandbox/tags/ID/carrier-event" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "in_transit"
}'

Replace the following:

API_KEY: your test key, which starts with st_test_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

POST `/v1/integrations/sandbox/tags/{id}/dispute` Open a fake dispute on one of your sandbox tags.

Request, responses and example

Operation mock_dispute

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.

Parameters of mock_dispute

Path parameters:

Parameters of mock_dispute
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Request body of mock_dispute

MockDisputeRequest, required

Fields of the request body:

Request fields of mock_dispute
Field	Type	Required	Description
`customer_claim`	string	No	Customer's claim text. Defaults to a generic message. Max 1000 characters.
`dispute_type`	string	No	Dispute type. Defaults to `not_delivered`. One of: not_delivered, damaged, wrong_location, other

Responses of mock_dispute

200 Dispute created with status open

data: Dispute

Fields of data:

Response 200 fields of mock_dispute
Field	Type	Required	Description
`customer_claim`	string, nullable	No
`evidence_score`	integer (int32), nullable	No
`id`	string (uuid)	Yes
`metadata`	object	Yes
`opened_at`	string (date-time)	Yes
`organization_id`	string (uuid)	Yes
`resolution`	string, nullable	No
`resolved_at`	string (date-time), nullable	No
`resolved_by`	string (uuid), nullable	No
`shopify_submission_status`	string, nullable	No
`shopify_submitted_at`	string (date-time), nullable	No
`status`	string	Yes
`tag_id`	string (uuid)	Yes
`tag_serial`	string, nullable	No	The tag's printed ID, when known.
`type`	string, nullable	No

400 Invalid dispute_type, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
403 Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)
404 Tag not found, or not assigned to your organization
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of mock_dispute

curl -X POST "https://sandbox-api.secretag.co/v1/integrations/sandbox/tags/ID/dispute" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_claim": "Customer reports the package was not delivered.",
  "dispute_type": "not_delivered"
}'

Replace the following:

API_KEY: your test key, which starts with st_test_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

POST `/v1/integrations/sandbox/tags/{id}/mock-journey` Inject a mock Los Angeles to Dallas ping route into one of your sandbox tags.

Request, responses and example

Operation mock_journey

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.

Parameters of mock_journey

Path parameters:

Parameters of mock_journey
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Request body of mock_journey

MockJourneyRequest, required

Fields of the request body:

Request fields of mock_journey
Field	Type	Required	Description
`stage`	JourneyStage	No	How far through the mock journey to populate.

Responses of mock_journey

200 Pings injected and origin and destination set; data is { tag_id, stage, inserted }

data: any
400 Malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
403 Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)
404 Tag not found, or not assigned to your organization
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of mock_journey

curl -X POST "https://sandbox-api.secretag.co/v1/integrations/sandbox/tags/ID/mock-journey" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "stage": "complete"
}'

Replace the following:

API_KEY: your test key, which starts with st_test_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

POST `/v1/integrations/sandbox/tags/{id}/reset` Reset one of your sandbox tags.

Request, responses and example

Operation reset_tag

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 }.

Parameters of reset_tag

Path parameters:

Parameters of reset_tag
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Responses of reset_tag

200 Tag reset

data: any
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
403 Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)
404 Tag not found, or not assigned to your organization
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of reset_tag

curl -X POST "https://sandbox-api.secretag.co/v1/integrations/sandbox/tags/ID/reset" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your test key, which starts with st_test_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

POST `/v1/integrations/sandbox/tags/{id}/risk-score` Emit a risk.high_score event for one of your sandbox tags.

Request, responses and example

Operation mock_risk_score

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.

Parameters of mock_risk_score

Path parameters:

Parameters of mock_risk_score
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Request body of mock_risk_score

MockRiskScoreRequest, required

Fields of the request body:

Request fields of mock_risk_score
Field	Type	Required	Description
`risk_factors`	array of string	No	Risk factors to include in the webhook payload. Defaults to ["route_deviation", "dispute_history"].
`score`	integer (int32)	No	Risk score, 0 to 100. Defaults to 85 (the high-risk threshold).

Responses of mock_risk_score

200 risk.high_score event raised

data: any
400 Score must be between 0 and 100, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
403 Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)
404 Tag not found, or not assigned to your organization
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of mock_risk_score

curl -X POST "https://sandbox-api.secretag.co/v1/integrations/sandbox/tags/ID/risk-score" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "risk_factors": [
    "route_deviation",
    "dispute_history"
  ],
  "score": 85
}'

Replace the following:

API_KEY: your test key, which starts with st_test_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

POST `/v1/integrations/sandbox/tags/{id}/state` Force one of your sandbox tags into a state.

Request, responses and example

Operation force_state

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 }.

Parameters of force_state

Path parameters:

Parameters of force_state
Name	In	Type	Required	Description
`id`	path	string	Yes	The tag's printed ID (for example `0938NYH`), BLE identifier or uuid. A tag not assigned to your organization answers 404.

Request body of force_state

ForceStateRequest, required

Fields of the request body:

Request fields of force_state
Field	Type	Required	Description
`state`	string	Yes	One of: awaiting_first_ping, at_origin, in_transit, approaching, delivered, delivery_verification, disputed_in_transit, completed

Responses of force_state

200 State updated

data: any
400 Invalid state value, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
403 Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)
404 Tag not found, or not assigned to your organization
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of force_state

curl -X POST "https://sandbox-api.secretag.co/v1/integrations/sandbox/tags/ID/state" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "state": "in_transit"
}'

Replace the following:

API_KEY: your test key, which starts with st_test_
ID: the tag's printed ID (for example 0938NYH), BLE identifier or uuid

POST `/v1/integrations/sandbox/webhooks/test` Send a sample event to your webhook subscriptions.

Request, responses and example

Operation test_webhook

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.

Request body of test_webhook

TestWebhookRequest, required

Fields of the request body:

Request fields of test_webhook
Field	Type	Required	Description
`event_type`	string, one of tag.state_changed, tag.delivered, tag.approaching, tag.carrier_updated, dispute.opened, dispute.resolved, dispute.evidence_submitted, shipment.created, shipment.delivered, risk.high_score	Yes	One of the ten event types.

Responses of test_webhook

200 Sample event queued; data is { event_type, subscriptions_enqueued }

data: any
400 event_type missing or not one of the ten event types, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
403 Not available in production, use sandbox-api.secretag.co (sandbox operations run only on the sandbox host)
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address

Example request of test_webhook

curl -X POST "https://sandbox-api.secretag.co/v1/integrations/sandbox/webhooks/test" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_type": "tag.state_changed"
}'

Replace the following:

API_KEY: your test key, which starts with st_test_

Risk

Address risk scoring.

GET `/v1/risk/address/{hash}` Get a stored risk score by address hash.

Request, responses and example

Operation get_address_score

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.

Parameters of get_address_score

Path parameters:

Parameters of get_address_score
Name	In	Type	Required	Description
`hash`	path	string	Yes	Normalized address hash, as returned in `address_hash`

Responses of get_address_score

200 Cached risk score for the address

data: AddressRiskScore

Fields of data:

Response 200 fields of get_address_score
Field	Type	Required
`address_hash`	string	Yes
`address_input`	string	Yes
`address_normalized`	string	Yes
`created_at`	string (date-time)	Yes
`id`	string (uuid)	Yes
`organization_id`	string (uuid)	Yes
`reason`	string, nullable	No
`risk_level`	string	Yes
`score`	integer (int32)	Yes
`signal_address_type`	integer (int32)	Yes
`signal_carrier_data`	integer (int32)	Yes
`signal_confirmation_rate`	integer (int32)	Yes
`signal_crime_index`	integer (int32)	Yes
`signal_details`	object	Yes
`signal_dispute_history`	integer (int32)	Yes
`signal_gps_proof`	integer (int32)	Yes
`signal_risk_network`	integer (int32)	Yes
`updated_at`	string (date-time)	Yes

401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
404 No score found for this address, or your organization has not assessed it
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of get_address_score

curl -X GET "https://api.secretag.co/v1/risk/address/HASH" \
  -H "X-API-Key: API_KEY"

Replace the following:

API_KEY: your live key, which starts with st_live_
HASH: the normalized address hash, as returned in address_hash

POST `/v1/risk/assess` Score one delivery address.

Request, responses and example

Operation assess_address

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.

Request body of assess_address

AssessAddressRequest, required

Fields of the request body:

Request fields of assess_address
Field	Type	Required	Description
`city`	string	Yes
`state`	string	Yes
`street`	string	Yes
`street2`	string, nullable	No	Optional: unit/apt number.
`zip`	string	Yes

Responses of assess_address

200 Risk assessment result for the address

data: RiskAssessmentResult

Fields of data:

Response 200 fields of assess_address
Field	Type	Required	Description
`address_hash`	string	Yes
`address_input`	string	Yes
`reason`	string	Yes
`risk_level`	string	Yes
`score`	integer (int32)	Yes
`signals`	RiskSignals	Yes	The six risk signals behind one score.

400 Invalid address, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of assess_address

curl -X POST "https://api.secretag.co/v1/risk/assess" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "city": "Austin",
  "state": "TX",
  "street": "123 Main St",
  "street2": "Apt 4",
  "zip": "78701"
}'

Replace the following:

API_KEY: your live key, which starts with st_live_

POST `/v1/risk/batch` Score up to 100 addresses.

Request, responses and example

Operation assess_batch

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.

Request body of assess_batch

BatchAssessRequest, required

Fields of the request body:

Request fields of assess_batch
Field	Type	Required	Description
`addresses`	array of AssessAddressRequest	Yes

Responses of assess_batch

200 Batch risk assessment results

data: BatchAssessResponse

Fields of data:

Response 200 fields of assess_batch
Field	Type	Required	Description
`cached`	integer	Yes	How many of `results` your organization had assessed before this call.
`results`	array of RiskAssessmentResult	Yes
`total`	integer	Yes

400 addresses must be an array of 1 to 100 addresses, an invalid address, or a malformed JSON body
401 Missing, unknown or revoked API key, or a key of the other environment (Invalid API key)
413 Request body too large (limit 1 MB)
429 Rate limit exceeded: more than 600 requests per minute for your organization, or more than 60 failed authentications per minute from your IP address
502 Upstream unavailable: the tracking network timed out, could not be reached or failed
503 Upstream not configured

Example request of assess_batch

curl -X POST "https://api.secretag.co/v1/risk/batch" \
  -H "X-API-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "addresses": [
    {
      "city": "Austin",
      "state": "TX",
      "street": "123 Main St",
      "street2": "Apt 4",
      "zip": "78701"
    },
    {
      "city": "Dallas",
      "state": "TX",
      "street": "456 Warehouse Ave",
      "zip": "75201"
    }
  ]
}'

Replace the following:

API_KEY: your live key, which starts with st_live_

Schemas

AddressRiskScore object

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.

Fields of AddressRiskScore
Field	Type	Required
`address_hash`	string	Yes
`address_input`	string	Yes
`address_normalized`	string	Yes
`created_at`	string (date-time)	Yes
`id`	string (uuid)	Yes
`organization_id`	string (uuid)	Yes
`reason`	string, nullable	No
`risk_level`	string	Yes
`score`	integer (int32)	Yes
`signal_address_type`	integer (int32)	Yes
`signal_carrier_data`	integer (int32)	Yes
`signal_confirmation_rate`	integer (int32)	Yes
`signal_crime_index`	integer (int32)	Yes
`signal_details`	object	Yes
`signal_dispute_history`	integer (int32)	Yes
`signal_gps_proof`	integer (int32)	Yes
`signal_risk_network`	integer (int32)	Yes
`updated_at`	string (date-time)	Yes

Alert object

Alert notification

Fields of Alert
Field	Type	Required	Description
`created_at`	string (date-time)	Yes
`id`	string (uuid)	Yes
`message`	string, nullable	No
`metadata`	object	Yes
`organization_id`	string (uuid)	Yes
`read_at`	string (date-time), nullable	No
`severity`	string	Yes
`tag_id`	string (uuid)	Yes
`tag_serial`	string, nullable	No	The tag's printed ID, when known.
`title`	string	Yes
`type`	string	Yes

AlertListPage object

One page of alerts: items and pagination.

Fields of AlertListPage
Field	Type	Required	Description
`items`	array of Alert	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

AlertSeverity string, one of info, warning, critical

Alert severity

Values:

info
warning
critical

AlertSummary object

Alert summary counts (total, unread, critical unread)

Fields of AlertSummary
Field	Type	Required
`critical_unread`	integer (int64)	Yes
`total`	integer (int64)	Yes
`unread`	integer (int64)	Yes

ArchivedFilter string, one of exclude, include, only

exclude (the default) hides archived tags. include (archived tags too) and only (archived tags only) are not yet verified against the tracking network.

Values:

exclude
include
only

AssessAddressRequest object

Request to assess a single address

Fields of AssessAddressRequest
Field	Type	Required	Description
`city`	string	Yes
`state`	string	Yes
`street`	string	Yes
`street2`	string, nullable	No	Optional: unit/apt number.
`zip`	string	Yes

BatchAssessRequest object

Request for batch assessment

Fields of BatchAssessRequest
Field	Type	Required	Description
`addresses`	array of AssessAddressRequest	Yes

BatchAssessResponse object

Batch assessment response

Fields of BatchAssessResponse
Field	Type	Required	Description
`cached`	integer	Yes	How many of `results` your organization had assessed before this call.
`results`	array of RiskAssessmentResult	Yes
`total`	integer	Yes

CreatePackageEntry object

A single package entry within a create-shipment request

Fields of CreatePackageEntry
Field	Type	Required	Description
`child_tracking_number`	string, nullable	No	Per-box tracking number (child)
`tag_identifier`	string	Yes	A tag assigned to your organization: its printed ID, BLE identifier or uuid.

CreateShipmentRequest object

Request to create a new shipment with packages

Fields of CreateShipmentRequest
Field	Type	Required	Description
`carrier`	string	Yes
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`insurance`	ShipmentInsuranceRequest, nullable	No	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.
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No	Not supported by SecreTag: a request that names it answers 400.
`packages`	array of CreatePackageEntry	Yes	Packages to create: each names a tag and an optional child tracking number.
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No	Service level (e.g., ground, express, priority, next_day, economy)

CreateWebhookSubscriptionRequest object

Request to create a webhook subscription.

Fields of CreateWebhookSubscriptionRequest
Field	Type	Required	Description
`event_types`	array of string, one of tag.state_changed, tag.delivered, tag.approaching, tag.carrier_updated, dispute.opened, dispute.resolved, dispute.evidence_submitted, shipment.created, shipment.delivered, risk.high_score, nullable	No	The event types to receive; omit or `null` for every event.
`label`	string, nullable	No
`target_url`	string	Yes	An HTTPS URL on a public address.

CreateWebhookSubscriptionResponse object

The subscription just created, with its signing secret (returned only here).

Fields of CreateWebhookSubscriptionResponse
Field	Type	Required	Description
`created_at`	string (date-time)	Yes
`event_types`	array of string, one of tag.state_changed, tag.delivered, tag.approaching, tag.carrier_updated, dispute.opened, dispute.resolved, dispute.evidence_submitted, shipment.created, shipment.delivered, risk.high_score, nullable	No	The event types the subscription takes; `null` for every event.
`id`	string (uuid)	Yes
`is_active`	boolean	Yes
`label`	string, nullable	No
`organization_id`	string (uuid)	Yes
`secret`	string, nullable	No	The signing secret, returned once in this response and never again. Verify each delivery's `X-SecreTag-Signature: sha256=<hex HMAC-SHA256 of the raw body>` with it.
`target_url`	string	Yes
`updated_at`	string (date-time)	Yes

Dispute object

Delivery dispute

Fields of Dispute
Field	Type	Required	Description
`customer_claim`	string, nullable	No
`evidence_score`	integer (int32), nullable	No
`id`	string (uuid)	Yes
`metadata`	object	Yes
`opened_at`	string (date-time)	Yes
`organization_id`	string (uuid)	Yes
`resolution`	string, nullable	No
`resolved_at`	string (date-time), nullable	No
`resolved_by`	string (uuid), nullable	No
`shopify_submission_status`	string, nullable	No
`shopify_submitted_at`	string (date-time), nullable	No
`status`	string	Yes
`tag_id`	string (uuid)	Yes
`tag_serial`	string, nullable	No	The tag's printed ID, when known.
`type`	string, nullable	No

DisputeListPage object

One page of disputes: items and pagination.

Fields of DisputeListPage
Field	Type	Required	Description
`items`	array of Dispute	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

DisputeStatsResponse object

Dispute counts and figures, computed by SecreTag for your organization (see dispute_stats).

Fields of DisputeStatsResponse
Field	Type	Required	Description
`amount_at_risk`	number (double)	Yes	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.
`avg_resolution_hours`	number (double), nullable	No	Mean hours from open to resolution, two decimals; null when no dispute is resolved.
`evidence_generated`	integer (int64)	Yes	Your disputes for which SecreTag recorded a successful `generate_evidence` call.
`investigating`	integer (int64)	Yes
`open`	integer (int64)	Yes
`resolved`	integer (int64)	Yes
`shopify_submitted`	integer (int64)	Yes	Your disputes that carry a `shopify_submitted_at`.
`total`	integer (int64)	Yes

ErrorResponse object

The envelope of every error answer: success false, data null, error a message.

Fields of ErrorResponse
Field	Type	Required
`data`	null	Yes
`error`	string	Yes
`success`	boolean, one of false	Yes

EvidenceLocationProofEntry object

A single BLE location report in the evidence package.

Fields of EvidenceLocationProofEntry
Field	Type	Required	Description
`accuracy_m`	number (double), nullable	No
`lat`	number (double)	Yes
`lng`	number (double)	Yes
`source`	string	Yes	Detection source. `"network"` = satellite/terrestrial network; `"ble"` = direct BLE.
`status`	string	Yes	Proximity to the destination. One of `"at_destination"`, `"approaching"` (< 1 km), or `"in_transit"`.
`tag_id`	string (uuid)	Yes	Tag that produced this ping. Use with `tag_count` to group pings by tag in multi-box shipments.
`time`	string (date-time)	Yes

ForceStateRequest object

Force a tag to a specific state.

Fields of ForceStateRequest
Field	Type	Required	Description
`state`	string	Yes	One of: awaiting_first_ping, at_origin, in_transit, approaching, delivered, delivery_verification, disputed_in_transit, completed

GenerateEvidenceResponse object

The result of generate_evidence.

Fields of GenerateEvidenceResponse
Field	Type	Required	Description
`evidence_pdf_key`	string	Yes	Where the tracking network stored the evidence PDF; download it with `get_evidence_pdf`.
`generated_at`	string	Yes	RFC 3339 timestamp of generation.

JourneyPoint object

Journey point for map display

Fields of JourneyPoint
Field	Type	Required
`accuracy_m`	number (double), nullable	No
`lat`	number (double)	Yes
`lng`	number (double)	Yes
`source`	string	Yes
`time`	string (date-time)	Yes

JourneyStage string, one of started, in_transit, approaching, complete

How far through the mock journey to populate.

Values:

started
in_transit
approaching
complete

LastPing object

Summary of last ping for a tag

Fields of LastPing
Field	Type	Required	Description
`lat`	number (double)	Yes
`lng`	number (double)	Yes
`rssi`	integer (int32), nullable	No	Radio signal strength (dBm) of the gateway that heard this ping, when reported.
`source`	string	Yes
`time`	string (date-time)	Yes

MarkReadResponse object

An alert marked read.

Fields of MarkReadResponse
Field	Type	Required	Description
`id`	string (uuid)	Yes
`read_at`	string (date-time)	Yes

MockAlertRequest object

Fields of MockAlertRequest
Field	Type	Required	Description
`alert_type`	string	No	Alert type. Defaults to `delivery`. One of: geofence, delivery, dispute, system, package_separation, gps_carrier_mismatch
`severity`	string	No	Alert severity. Defaults to `warning`. One of: info, warning, critical

MockCarrierEventRequest object

Fields of MockCarrierEventRequest
Field	Type	Required	Description
`status`	string	Yes	Carrier status. One of: in_transit, out_for_delivery, delivered, exception

MockDisputeRequest object

Fields of MockDisputeRequest
Field	Type	Required	Description
`customer_claim`	string	No	Customer's claim text. Defaults to a generic message. Max 1000 characters.
`dispute_type`	string	No	Dispute type. Defaults to `not_delivered`. One of: not_delivered, damaged, wrong_location, other

MockJourneyRequest object

Fields of MockJourneyRequest
Field	Type	Required	Description
`stage`	JourneyStage	No	How far through the mock journey to populate.

MockRiskScoreRequest object

Fields of MockRiskScoreRequest
Field	Type	Required	Description
`risk_factors`	array of string	No	Risk factors to include in the webhook payload. Defaults to ["route_deviation", "dispute_history"].
`score`	integer (int32)	No	Risk score, 0 to 100. Defaults to 85 (the high-risk threshold).

PaginationMeta object

Pagination metadata for list responses

Fields of PaginationMeta
Field	Type	Required
`limit`	integer (int32)	Yes
`page`	integer (int32)	Yes
`total`	integer (int64)	Yes
`total_pages`	integer (int32)	Yes

ResolveDisputeRequest object

Request to resolve a dispute

Fields of ResolveDisputeRequest
Field	Type	Required	Description
`evidence_score`	integer (int32), nullable	No
`resolution`	string	Yes

RiskAssessmentResult object

Risk assessment result returned to the client

Fields of RiskAssessmentResult
Field	Type	Required	Description
`address_hash`	string	Yes
`address_input`	string	Yes
`reason`	string	Yes
`risk_level`	string	Yes
`score`	integer (int32)	Yes
`signals`	RiskSignals	Yes	The six risk signals behind one score.

RiskSignals object

The six risk signals behind one score.

Fields of RiskSignals
Field	Type	Required	Description
`address_type`	SignalDetail	Yes	A single signal's raw score and explanation
`carrier_data`	SignalDetail	Yes	A single signal's raw score and explanation
`crime_index`	SignalDetail	Yes	A single signal's raw score and explanation
`disputes`	SignalDetail	Yes	A single signal's raw score and explanation
`gps_proof`	SignalDetail	Yes	A single signal's raw score and explanation
`risk_network`	SignalDetail	Yes	A single signal's raw score and explanation

SelfServeCarrierData object

Carrier fields of a tag activated outside a shipment (a self-serve tag).

Fields of SelfServeCarrierData
Field	Type	Required
`carrier`	string, nullable	No
`carrier_events`	any	No
`carrier_status`	string, nullable	No
`expected_delivery`	string, nullable	No
`tracking_number`	string, nullable	No

Shipment object

A shipment: master-level tracking for one or more packages

Fields of Shipment
Field	Type	Required	Description
`carrier`	string	Yes
`created_at`	string (date-time)	Yes
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`id`	string (uuid)	Yes
`insurance`	ShipmentInsurance, nullable	Yes	The declared value SecreTag keeps for this shipment; null when none is declared. Present on every shipment SecreTag returns.
`master_status`	string, nullable	No
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No
`public_id`	string	Yes
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No
`updated_at`	string (date-time)	Yes

ShipmentInsurance object

A declared value SecreTag keeps for a shipment.

Fields of ShipmentInsurance
Field	Type	Required	Description
`currency`	string	Yes	Three-letter currency code: your organization's currency.
`declared_at`	string (date-time)	Yes	When the value was declared.
`declared_value`	string	Yes	The declared value, a decimal string with two decimals.

ShipmentInsuranceRequest object

A declared value for a shipment.

Fields of ShipmentInsuranceRequest
Field	Type	Required	Description
`currency`	string	Yes	Must equal your organization's currency.
`declared_value`	string	Yes	A decimal string with at most two decimals and at most 13 digits before the point, greater than zero. A JSON number is refused.

ShipmentListPage object

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.

Fields of ShipmentListPage
Field	Type	Required	Description
`items`	array of Shipment	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

ShipmentPackage object

A single package within a shipment (1:1 with a tag)

Fields of ShipmentPackage
Field	Type	Required
`actual_delivery`	string (date-time), nullable	No
`carrier_events`	object	Yes
`carrier_last_checked`	string (date-time), nullable	No
`child_status`	string, nullable	No
`child_tracking_number`	string, nullable	No
`created_at`	string (date-time)	Yes
`estimated_delivery`	string (date), nullable	No
`id`	string (uuid)	Yes
`sequence_number`	integer (int32)	Yes
`shipment_id`	string (uuid)	Yes
`tagBleIdentifier`	string, nullable	No
`tagDestinationAddress`	string, nullable	No
`tagLastSeen`	string (date-time), nullable	No
`tagState`	string, nullable	No
`tag_id`	string (uuid), nullable	No
`updated_at`	string (date-time)	Yes

ShipmentWithPackages object

Shipment with all its packages (for API responses)

Fields of ShipmentWithPackages
Field	Type	Required	Description
`carrier`	string	Yes
`created_at`	string (date-time)	Yes
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`id`	string (uuid)	Yes
`insurance`	ShipmentInsurance, nullable	Yes	The declared value SecreTag keeps for this shipment; null when none is declared. Present on every shipment SecreTag returns.
`master_status`	string, nullable	No
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No
`public_id`	string	Yes
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No
`updated_at`	string (date-time)	Yes
`packages`	array of ShipmentPackage	Yes

SignalDetail object

A single signal's raw score and explanation

Fields of SignalDetail
Field	Type	Required	Description
`explanation`	string	Yes	Human-readable explanation
`raw_score`	integer (int32)	Yes	Raw signal score 0-100 (before weighting)
`weight`	number (double)	Yes	Weight applied (0.0 - 1.0)
`weighted_score`	number (double)	Yes	Weighted contribution to final score

Tag object

Tag (BLE beacon) attached to a package

Fields of Tag
Field	Type	Required	Description
`archived_at`	string (date-time), nullable	No
`auto_off_after_delivery`	boolean, nullable	No	Per-tag override of the organization's deactivate-after-delivery setting; null inherits the organization default.
`auto_off_at`	string (date-time), nullable	No	The scheduled automatic switch-off time, when known.
`auto_off_state`	string, nullable	No	`active`, `scheduled` or `off`: the tag's automatic switch-off state; null when not known.
`ble_identifier`	string	Yes
`created_at`	string (date-time)	Yes
`delivered_at`	string (date-time), nullable	No
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`geofence_radius_m`	integer (int32)	Yes
`id`	string (uuid)	Yes
`metadata`	object	Yes
`network_coverage_months`	integer (int32), nullable	No	The network coverage months sold for this tag's device, when known (read only).
`network_device_id`	string, nullable	No
`network_last_checked`	string (date-time), nullable	No
`network_off_override_at`	string (date-time), nullable	No	An explicit network switch-off time set for this tag's device, or null (read only).
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No	The origin location the tag was created with, if any (read only).
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`shipment_package_id`	string (uuid), nullable	No
`shipped_at`	string (date-time), nullable	No
`state`	string	Yes

TagEvidenceResponse object

Everything the generated evidence PDF contains, so you can build your own representation without downloading the PDF.

Fields of TagEvidenceResponse
Field	Type	Required	Description
`carrier`	string, nullable	No
`carrier_delivered_at`	string (date-time), nullable	No
`carrier_events`	any	No	Carrier scan events array. Each entry has `timestamp`, `status`, `location`, and `description` string fields.
`carrier_status`	string, nullable	No
`destination_address`	string, nullable	No
`dispute`	Dispute	Yes	Delivery dispute
`dwell_time_secs`	integer (int64), nullable	No	Seconds the tag was stationary at the destination address. Null when fewer than 2 pings were recorded near the destination.
`evidence_generated_at`	string (date-time), nullable	No	When the evidence PDF was generated.
`location_proof`	array of EvidenceLocationProofEntry	Yes	Up to 50 most recent BLE location reports, oldest-first.
`origin_address`	string, nullable	No
`pings_at_destination`	integer (int64)	Yes	Pings detected within 150 m of the destination coordinates.
`tag_count`	integer (int64)	Yes	Number of tags in the shipment (> 1 means multi-box).
`total_pings`	integer (int64)	Yes	Total BLE location reports recorded across all tags in the shipment.
`tracking_number`	string, nullable	No

TagJourneyResponse object

Journey response for a tag

Fields of TagJourneyResponse
Field	Type	Required
`points`	array of JourneyPoint	Yes
`tag_id`	string (uuid)	Yes
`total_points`	integer (int64)	Yes

TagListPage object

One page of tags: items and pagination.

Fields of TagListPage
Field	Type	Required	Description
`items`	array of TagWithLastPing	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

TagWithLastPing object

Fields of TagWithLastPing
Field	Type	Required	Description
`archived_at`	string (date-time), nullable	No
`auto_off_after_delivery`	boolean, nullable	No	Per-tag override of the organization's deactivate-after-delivery setting; null inherits the organization default.
`auto_off_at`	string (date-time), nullable	No	The scheduled automatic switch-off time, when known.
`auto_off_state`	string, nullable	No	`active`, `scheduled` or `off`: the tag's automatic switch-off state; null when not known.
`ble_identifier`	string	Yes
`created_at`	string (date-time)	Yes
`delivered_at`	string (date-time), nullable	No
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`geofence_radius_m`	integer (int32)	Yes
`id`	string (uuid)	Yes
`metadata`	object	Yes
`network_coverage_months`	integer (int32), nullable	No	The network coverage months sold for this tag's device, when known (read only).
`network_device_id`	string, nullable	No
`network_last_checked`	string (date-time), nullable	No
`network_off_override_at`	string (date-time), nullable	No	An explicit network switch-off time set for this tag's device, or null (read only).
`order_id`	string, nullable	No
`organization_id`	string (uuid)	Yes
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`origin_location_id`	string (uuid), nullable	No	The origin location the tag was created with, if any (read only).
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`shipment_package_id`	string (uuid), nullable	No
`shipped_at`	string (date-time), nullable	No
`state`	string	Yes
`last_ping`	LastPing	No	Summary of last ping for a tag
`ping_count`	integer	Yes
`recent_pings`	array of LastPing	No
`self_serve`	SelfServeCarrierData	No	Carrier fields of a tag activated outside a shipment (a self-serve tag).

TestWebhookRequest object

Send SecreTag's sample event of event_type to your matching active subscriptions.

Fields of TestWebhookRequest
Field	Type	Required	Description
`event_type`	string, one of tag.state_changed, tag.delivered, tag.approaching, tag.carrier_updated, dispute.opened, dispute.resolved, dispute.evidence_submitted, shipment.created, shipment.delivered, risk.high_score	Yes	One of the ten event types.

UpdateShipmentRequest object

Request to update shipment metadata

Fields of UpdateShipmentRequest
Field	Type	Required	Description
`carrier`	string, nullable	No
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`insurance`	ShipmentInsuranceRequest, nullable	No	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.
`master_tracking_number`	string, nullable	No
`order_id`	string, nullable	No
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No
`service_level`	string, nullable	No	Service level (e.g., ground, express, priority, next_day, economy)

UpdateTagRequest object

Request to update a tag

Fields of UpdateTagRequest
Field	Type	Required	Description
`auto_off_after_delivery`	boolean, nullable	No	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.
`destination_address`	string, nullable	No
`destination_lat`	number (double), nullable	No
`destination_lng`	number (double), nullable	No
`geofence_radius_m`	integer (int32), nullable	No
`metadata`	object, nullable	No
`network_coverage_months`	integer (int32), nullable	No	Accepted and not acted on by this operation.
`network_off_override_at`	string (date-time), nullable	No	Accepted and not acted on by this operation.
`order_id`	string, nullable	No
`origin_address`	string, nullable	No
`origin_lat`	number (double), nullable	No
`origin_lng`	number (double), nullable	No
`recipient_email`	string, nullable	No
`recipient_name`	string, nullable	No
`recipient_phone`	string, nullable	No

WebhookDelivery object

One relay of one event to one of your subscriptions (SecreTag's delivery log).

Fields of WebhookDelivery
Field	Type	Required	Description
`attempts`	integer (int32)	Yes
`created_at`	string (date-time)	Yes
`delivered_at`	string (date-time), nullable	No
`event_id`	string	Yes	The event's id: the tracking network's event id, or `test_<uuid>` for a `test_webhook` sample event.
`event_type`	string	Yes
`id`	string (uuid)	Yes
`last_attempt_at`	string (date-time), nullable	No
`last_error`	string, nullable	No
`last_response_body`	string, nullable	No
`last_status_code`	integer (int32), nullable	No
`max_attempts`	integer (int32)	Yes
`next_retry_at`	string (date-time), nullable	No
`organization_id`	string (uuid)	Yes
`payload`	object	Yes	The event body SecreTag sent.
`status`	string	Yes	`pending`, `delivered`, `failed` (8 attempts without a 2xx) or `cancelled` (the subscription was deactivated first).
`subscription_id`	string (uuid)	Yes

WebhookDeliveryListPage object

One page of a subscription's delivery log: items and pagination.

Fields of WebhookDeliveryListPage
Field	Type	Required	Description
`items`	array of WebhookDelivery	Yes
`pagination`	PaginationMeta	Yes	Pagination metadata for list responses

WebhookSubscription object

A webhook subscription.

Fields of WebhookSubscription
Field	Type	Required	Description
`created_at`	string (date-time)	Yes
`event_types`	array of string, one of tag.state_changed, tag.delivered, tag.approaching, tag.carrier_updated, dispute.opened, dispute.resolved, dispute.evidence_submitted, shipment.created, shipment.delivered, risk.high_score, nullable	No	The event types the subscription takes; `null` for every event.
`id`	string (uuid)	Yes
`is_active`	boolean	Yes
`label`	string, nullable	No
`organization_id`	string (uuid)	Yes
`target_url`	string	Yes
`updated_at`	string (date-time)	Yes

SecreTag API

Getting started

Authentication

Response envelope

Tenancy

Limits and errors

Lists

Declared value insurance

Webhooks

Verifying a delivery

Ruby

Node.js

Testing in the sandbox

Integrations

GET /v1/integrations/alerts List your organization's alerts.

Parameters of list_alerts

Responses of list_alerts

Example request of list_alerts

POST /v1/integrations/alerts/read-all Mark all your unread alerts as read.

Responses of mark_all_alerts_read

Example request of mark_all_alerts_read

GET /v1/integrations/alerts/summary Alert counts for your organization.

Responses of alert_summary

Example request of alert_summary

PATCH /v1/integrations/alerts/{id}/read Mark one of your alerts as read.

Parameters of mark_alert_read

Responses of mark_alert_read

Example request of mark_alert_read

GET /v1/integrations/disputes List your organization's disputes.

Parameters of list_disputes

Responses of list_disputes

Example request of list_disputes

GET /v1/integrations/disputes/stats Dispute statistics for your organization.

Responses of dispute_stats

Example request of dispute_stats

GET /v1/integrations/disputes/{id} Get one of your disputes.

Parameters of get_dispute

Responses of get_dispute

Example request of get_dispute

POST /v1/integrations/disputes/{id}/evidence/generate Generate the evidence PDF for one of your disputes.

Parameters of generate_evidence

Responses of generate_evidence

Example request of generate_evidence

GET /v1/integrations/disputes/{id}/evidence/pdf Download the evidence PDF for one of your disputes.

Parameters of get_evidence_pdf

Responses of get_evidence_pdf

Example request of get_evidence_pdf

POST /v1/integrations/disputes/{id}/resolve Resolve one of your disputes.

Parameters of resolve_dispute

Request body of resolve_dispute

Responses of resolve_dispute

Example request of resolve_dispute

GET /v1/integrations/shipments List your organization's shipments.

Parameters of list_shipments

Responses of list_shipments

Example request of list_shipments

POST /v1/integrations/shipments Create a shipment with one or more packages, linking tags already assigned to the caller's organization.

Request body of create_shipment

Responses of create_shipment

Example request of create_shipment

GET /v1/integrations/shipments/{id} Get one of your shipments with its packages.

Parameters of get_shipment

Responses of get_shipment

Example request of get_shipment

PATCH /v1/integrations/shipments/{id} Update one of your shipments.

Parameters of update_shipment

Request body of update_shipment

Responses of update_shipment

Example request of update_shipment

GET /v1/integrations/tags List your organization's tags.

Parameters of list_tags

Responses of list_tags

Example request of list_tags

GET /v1/integrations/tags/{id} Get one of your tags.

Parameters of get_tag

Responses of get_tag

Example request of get_tag

PATCH /v1/integrations/tags/{id} Update one of your tags.

Parameters of update_tag

Request body of update_tag

GET `/v1/integrations/alerts` List your organization's alerts.

POST `/v1/integrations/alerts/read-all` Mark all your unread alerts as read.

GET `/v1/integrations/alerts/summary` Alert counts for your organization.

PATCH `/v1/integrations/alerts/{id}/read` Mark one of your alerts as read.

GET `/v1/integrations/disputes` List your organization's disputes.

GET `/v1/integrations/disputes/stats` Dispute statistics for your organization.

GET `/v1/integrations/disputes/{id}` Get one of your disputes.

POST `/v1/integrations/disputes/{id}/evidence/generate` Generate the evidence PDF for one of your disputes.

GET `/v1/integrations/disputes/{id}/evidence/pdf` Download the evidence PDF for one of your disputes.

POST `/v1/integrations/disputes/{id}/resolve` Resolve one of your disputes.

GET `/v1/integrations/shipments` List your organization's shipments.

POST `/v1/integrations/shipments` Create a shipment with one or more packages, linking tags already assigned to the caller's organization.

GET `/v1/integrations/shipments/{id}` Get one of your shipments with its packages.

PATCH `/v1/integrations/shipments/{id}` Update one of your shipments.

GET `/v1/integrations/tags` List your organization's tags.

GET `/v1/integrations/tags/{id}` Get one of your tags.

PATCH `/v1/integrations/tags/{id}` Update one of your tags.

GET `/v1/integrations/tags/{id}/disputes` List the disputes of one of your tags.

GET `/v1/integrations/tags/{id}/evidence` Get the evidence data of one of your tags.

GET `/v1/integrations/tags/{id}/journey` Get the ping journey of one of your tags.

GET `/v1/integrations/webhooks` List your webhook subscriptions.

POST `/v1/integrations/webhooks` Create a webhook subscription.

DELETE `/v1/integrations/webhooks/{id}` Deactivate one of your webhook subscriptions.

GET `/v1/integrations/webhooks/{id}/deliveries` List the deliveries of one of your webhook subscriptions.

POST `/v1/integrations/sandbox/tags/{id}/alert` Inject a fake alert on one of your sandbox tags.

POST `/v1/integrations/sandbox/tags/{id}/carrier-event` Inject a fake carrier status on the tag's shipment package.

POST `/v1/integrations/sandbox/tags/{id}/dispute` Open a fake dispute on one of your sandbox tags.

POST `/v1/integrations/sandbox/tags/{id}/mock-journey` Inject a mock Los Angeles to Dallas ping route into one of your sandbox tags.

POST `/v1/integrations/sandbox/tags/{id}/reset` Reset one of your sandbox tags.

POST `/v1/integrations/sandbox/tags/{id}/risk-score` Emit a risk.high_score event for one of your sandbox tags.

POST `/v1/integrations/sandbox/tags/{id}/state` Force one of your sandbox tags into a state.

POST `/v1/integrations/sandbox/webhooks/test` Send a sample event to your webhook subscriptions.

GET `/v1/risk/address/{hash}` Get a stored risk score by address hash.