Restrict a carrier on a specific lane

Mark this carrier as ineligible for the specified lane. Requires a human-readable reason; an audit-log row capturing the actor, reason, and timestamp is written in the same transaction. Idempotent: calling this endpoint when the preference is already restricted returns the current row unchanged and writes no audit entry. Admin-only — requires OWNER or ADMIN role on the organization.

Authentication: Bearer token required.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

carrier_idstringRequiredformat: "uuid"

preference_idstringRequiredformat: "uuid"

Headers

X-Organization-IDstring or nullOptional

Request

This endpoint expects an object.

reasonenumRequired

Constrained reason code; see AuditLogReason for the value set.

reason_notestring or nullOptional<=2000 characters

Response

Successful Response

idstringformat: "uuid"

carrier_idstringformat: "uuid"

lane_idstringformat: "uuid"

is_activeboolean

preference_typestring

updated_atdatetime or null

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

$	curl -X POST https://tryenvoy.ai/api/v1/carriers/carrier_id/lane-preferences/preference_id/restrict \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"reason": "pause_on_lane"
>	}'

1	{
2	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3	"carrier_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
4	"lane_id": "1c9e6679-7425-40de-944b-e07fc1f90ae8",
5	"is_active": false,
6	"preference_type": "restricted",
7	"updated_at": "2024-01-15T09:30:00Z"
8	}