Add a lane preference, optionally blocked

Adds a lane for this carrier by hand. Every other path that creates lane preferences is driven by freight that already moved — an offer, a truck list, a TMS sync — so before this endpoint a carrier could only be blocked on lanes they had already run, which inverts the point of a block. Omit both destination fields for an ‘<origin> -> Anywhere’ lane: a block on one of those spans every lane out of that origin, including lanes created later. Sending only one destination field is rejected as a typo rather than silently widening the block. Set dnu with a dnu_reason to block it on creation, in the same transaction. Find-or-create: an existing lane is reused, and a carrier that already has a row on that lane gets it edited rather than a second row stacked beside it. Admin-only.

Authentication: Bearer token required.

Adds a lane for this carrier by hand. Every other path that creates lane preferences is driven by freight that already moved — an offer, a truck list, a TMS sync — so before this endpoint a carrier could only be blocked on lanes they had already run, which inverts the point of a block. Omit both destination fields for an '<origin> -> Anywhere' lane: a block on one of those spans every lane out of that origin, including lanes created later. Sending only one destination field is rejected as a typo rather than silently widening the block. Set dnu with a dnu_reason to block it on creation, in the same transaction. Find-or-create: an existing lane is reused, and a carrier that already has a row on that lane gets it edited rather than a second row stacked beside it. Admin-only. **Authentication:** Bearer token required.

Authentication

AuthorizationBearer

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

Path parameters

carrier_idstringRequiredformat: "uuid"

Headers

Idempotency-KeystringOptional<=255 characters

A unique key (up to 255 printable ASCII characters, e.g. a UUID) that makes a retry of this request safe. Envoy stores the response for 24 hours; a retry with the same key and the same request returns it again with Idempotent-Replayed: true instead of running twice. The same key with a different request returns 422 idempotency_key_reused; while the first request is still running, 409 idempotency_key_in_progress. 5xx and 429 responses are not stored.

A unique key (up to 255 printable ASCII characters, e.g. a UUID) that makes a retry of this request safe. Envoy stores the response for 24 hours; a retry with the same key and the same request returns it again with `Idempotent-Replayed: true` instead of running twice. The same key with a different request returns 422 `idempotency_key_reused`; while the first request is still running, 409 `idempotency_key_in_progress`. 5xx and 429 responses are not stored.

Request

This endpoint expects an object.

origin_citystringRequired1-255 characters

origin_statestringRequired=2 characters

reasonenum or nullOptional

Allowed values for AuditLog.reason. DB-enforced via Postgres ENUM.

The set is intentionally shared across all entity_type contexts; the same code (service_quality, compliance, other) means different things depending on whether the audited row is a carrier or a lane preference. Disambiguating is the caller’s job — the frontend renders different human labels per context. Free-text justification lands on AuditLog.reason_note — required when OTHER is chosen, optional (but preserved) for any other code.

reason_notestring or nullOptional<=2000 characters

destination_citystring or nullOptional<=255 characters

destination_statestring or nullOptional=2 characters

dnubooleanOptionalDefaults to false

Block this lane on creation

dnu_reasonstring or nullOptional<=500 characters

Why the carrier is blocked here. Required when dnu is true.

Response

Successful Response

idstringformat: "uuid"

carrier_idstringformat: "uuid"

lane_idstringformat: "uuid"

is_activeboolean

preference_typestring

routing_guide_tierinteger or nullOptional

dnubooleanOptionalDefaults to false

dnu_reasonstring or nullOptional

dnu_set_atdatetime or nullOptional

updated_atdatetime or nullOptional

origin_citystring or nullOptional

origin_statestring or nullOptional

destination_citystring or nullOptional

destination_statestring or nullOptional

created_atdatetime or nullOptional

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

Authentication: Bearer token required.