# ARK API



> REST API for authorized ARK TMS scripts and integrations.



[Developer portal](/developer) | [API docs for agents](/developer/api.md) | [OpenAPI 3.1](/api/v1/openapi.json) | [MCP docs](/developer/mcp)



## API quickstart

The ARK API is in production preview. Access must be enabled for your organization, and an authorized ARK user must issue a restricted API token. The token is shown once. Store it in a secret manager or an environment variable, never in browser code or source control.

### Base URL

```text
https://arktms.com/api/v1
```

### Make your first request

Set the token in your shell, then request the effective identity and access context:

```bash
export ARK_API_TOKEN="your-token"

curl https://arktms.com/api/v1/me \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

A successful response includes `ok: true`, an API version, a request ID, and the connected actor's effective scopes, permissions, visible teams, and available operations. Keep the request ID when contacting support.

### Check available operations

Use `GET /api/v1/me` before building a workflow. The result reflects the intersection of the current user, organization, team visibility, token restrictions, and rollout tier. A route documented here can still return `missing_scope`, `missing_permission`, or `team_access_denied` for a credential that lacks access.

The reference on this page contains the operations currently enabled for external access. Unavailable and internal operations are intentionally absent.

## Authentication and scopes

REST API requests use an ARK API token in the standard bearer header:

```http
Authorization: Bearer your-token
```

API tokens are for server-side scripts and integrations. Do not send an OAuth MCP access token to REST routes, and do not expose an API token in a browser, mobile application, prompt, or client-side bundle.

Effective access is always the intersection of:

```text
current user permissions
AND organization membership
AND visible teams and entities
AND token scopes and restrictions
AND operation policy
AND enabled external-access tier
```

A scope never grants more access than the connected user already has. Team-limited tokens cannot reach records outside their configured teams. Token-specific row limits and rate limits can further reduce access.

Use the narrowest scopes required by the integration. The generated endpoint reference lists every required scope and ARK permission using canonical operation metadata.

### Server-to-server automation

API tokens support dashboards, scheduled jobs, and other server-side integrations, but they are currently user-delegated credentials. A token is scoped to one organization and remains bound to its issuing user; it stops working if that user is deactivated or no longer belongs to the organization.

ARK does not currently issue organization service principals or OAuth client-credentials grants. Use a restricted API token with a durable owner for current integrations. MCP OAuth remains user-delegated and is intended for interactive AI clients, not unattended server-to-server authentication.

## API concepts

### Responses and request IDs

Successful API calls use a versioned JSON envelope with `ok`, `api_version`, `request_id`, and `data`. Error responses use `ok: false` and a stable error `code`. Every response also returns `X-ARK-Request-Id`; log it with the request outcome.

Use error codes for control flow. Message text is for people and may become more specific without a version change.

### Pagination

List and search endpoints that support pagination expose `limit` and `cursor` parameters in their generated reference. Pass the returned cursor to the next request. Do not construct, inspect, or persist assumptions about cursor internals.

Page sizes are also constrained by the API token's `maxRowsPerRequest` policy. A request above that credential cap is rejected instead of silently widening access.

### Data boundaries

Published resource shapes are external API contracts, not copies of ARK database tables. The public OpenAPI document includes only components reachable from available operations and omits unused internal schemas.

`GET /api/v1/carriers` searches carrier records belonging to the authenticated organization, uses cursor pagination, and returns at most 100 rows per request before any lower token policy is applied. It does not provide a bulk export of the FMCSA source dataset. Carrier risk endpoints return curated, record-specific safety context through their documented response contracts.

### Preview availability

The reference publishes the complete external preview contract so integrations can be designed and tested before general availability. Runtime access is still the intersection of organization enrollment, the credential's scopes, ARK permissions, and team visibility. Operations marked `x-ark-access-tier: full` in OpenAPI require expanded-preview enrollment; the core preview remains available to the initial cohort.

### Idempotency

Every external mutation marked as idempotent in the reference requires an `Idempotency-Key` header:

```http
Idempotency-Key: a-stable-key-for-this-exact-attempt
```

Keys may be at most 200 characters and cannot contain control characters. Reuse a key only when retrying the exact same operation and payload. Reusing it with different input returns `idempotency_key_conflict`. ARK stores terminal outcomes so a retry can return the original result without repeating the write.

REST writes execute directly after authentication, authorization, validation, and idempotency checks. The server-backed human approval workflow described in the MCP guide does not apply to API-token requests.

### Rate limits

API tokens default to 600 requests per minute. API and MCP traffic also shares an organization budget that defaults to 3000 requests per minute. Organization or credential policy can set lower or higher limits.

Authenticated responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. A `429 rate_limit_exceeded` response also includes `Retry-After`. Production limits are distributed across application instances.

### Errors

Common stable codes include `unauthorized`, `missing_scope`, `missing_permission`, `team_access_denied`, `validation_failed`, `not_found`, `conflict`, `idempotency_key_required`, `idempotency_key_conflict`, `rate_limit_exceeded`, `external_access_disabled`, and `operation_not_available`.

Treat `401` as an invalid or expired credential, `403` as insufficient scope or access, `404` as an unavailable or invisible resource, `409` as a state or idempotency conflict, and `429` as a signal to wait for `Retry-After` before retrying.

## Broker workflows

Available workflows use normal ARK permissions and team visibility.

### Triage the work queue

Call `GET /api/v1/work-queue` to summarize operational work visible to the connected user. Follow returned identifiers with specific read endpoints instead of downloading broad record sets.

### Find and inspect a load

Use `GET /api/v1/loads` to search by load number, reference, status, or team. Then call `GET /api/v1/loads/{loadId}` and related stop, dispatch-note, tracking, bid, or billing-readiness endpoints for the selected load.

### Review a carrier before assignment

Search carriers, then call `GET /api/v1/carriers/{carrierId}/risk-card`. The risk card summarizes available safety, authority, insurance, identity, onboarding, and internal eligibility signals. It does not make the booking decision.

### Create and cover a load

Resolve customer, team, and locations first. Create the load with `POST /api/v1/loads`, then assign a carrier with `POST /api/v1/loads/{loadId}/assign-carrier`. Each write needs its own idempotency key. Use the generated request field tables and examples below; required fields come directly from OpenAPI.

### Record dispatch context

Use `POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/notes` for broker-visible call, exception, and follow-up context. This is an idempotent write and requires a unique key for the exact note attempt.



## API reference



This reference contains the complete external preview contract generated from OpenAPI. Actual access is limited by organization rollout, token scopes, ARK permissions, and team visibility; internal operations are not published.



### GET /api/v1/agent-sessions

`ark.list_agent_sessions`

Lists MCP and hosted-agent sessions for the connected user.

| Requirement | Value |
| --- | --- |
| Scopes | `agents:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | AgentSessionStatus | No | - | - |
| `query.include_inactive` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/agent-sessions' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Agent sessions

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.sessions` | array<AgentSession> | Yes | - | - |
| `data.sessions[]` | AgentSession | Yes | - | - |
| `data.sessions[].id` | string | Yes | - | format: uuid |
| `data.sessions[].organizationId` | string | Yes | - | format: uuid |
| `data.sessions[].userId` | string | Yes | - | format: uuid |
| `data.sessions[].actorType` | string | Yes | - | one of: web_user, api_token, oauth_mcp, internal_agent |
| `data.sessions[].source` | string | Yes | - | one of: web, api, mcp, agent |
| `data.sessions[].status` | AgentSessionStatus | Yes | - | one of: active, completed, stopped, expired, failed |
| `data.sessions[].title` | string \| null | Yes | - | - |
| `data.sessions[].goal` | string \| null | Yes | - | - |
| `data.sessions[].clientName` | string \| null | Yes | - | - |
| `data.sessions[].clientSessionId` | string \| null | Yes | - | - |
| `data.sessions[].maxToolCalls` | integer \| null | Yes | - | min: 1 |
| `data.sessions[].toolCallsUsed` | integer | Yes | - | min: 0 |
| `data.sessions[].startedAt` | string | Yes | - | format: date-time |
| `data.sessions[].lastSeenAt` | string | Yes | - | format: date-time |
| `data.sessions[].stoppedAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].expiresAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].createdAt` | string | Yes | - | format: date-time |
| `data.sessions[].metadata` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/agent-sessions

`ark.start_agent_session`

Creates an MCP or hosted-agent session record for run tracking, budgets, approval linkage, and audit attribution.

| Requirement | Value |
| --- | --- |
| Scopes | `agents:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `title` | string | No | - | min length: 1; max length: 160 |
| `goal` | string | No | - | min length: 1; max length: 2000 |
| `clientName` | string | No | - | min length: 1; max length: 160 |
| `clientSessionId` | string | No | - | min length: 1; max length: 200 |
| `maxToolCalls` | integer | No | - | min: 1; max: 10000 |
| `expiresInMinutes` | integer | No | - | default: 480; min: 5; max: 43200 |
| `metadata` | object | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/agent-sessions' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Started agent session

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.session` | AgentSession | Yes | - | - |
| `data.session.id` | string | Yes | - | format: uuid |
| `data.session.organizationId` | string | Yes | - | format: uuid |
| `data.session.userId` | string | Yes | - | format: uuid |
| `data.session.actorType` | string | Yes | - | one of: web_user, api_token, oauth_mcp, internal_agent |
| `data.session.source` | string | Yes | - | one of: web, api, mcp, agent |
| `data.session.status` | AgentSessionStatus | Yes | - | one of: active, completed, stopped, expired, failed |
| `data.session.title` | string \| null | Yes | - | - |
| `data.session.goal` | string \| null | Yes | - | - |
| `data.session.clientName` | string \| null | Yes | - | - |
| `data.session.clientSessionId` | string \| null | Yes | - | - |
| `data.session.maxToolCalls` | integer \| null | Yes | - | min: 1 |
| `data.session.toolCallsUsed` | integer | Yes | - | min: 0 |
| `data.session.startedAt` | string | Yes | - | format: date-time |
| `data.session.lastSeenAt` | string | Yes | - | format: date-time |
| `data.session.stoppedAt` | string \| null | Yes | - | format: date-time |
| `data.session.expiresAt` | string \| null | Yes | - | format: date-time |
| `data.session.createdAt` | string | Yes | - | format: date-time |
| `data.session.metadata` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/agent-sessions/{sessionId}/stop

`ark.stop_agent_session`

Stops an active MCP or hosted-agent session for the connected user.

| Requirement | Value |
| --- | --- |
| Scopes | `agents:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.sessionId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `reason` | string | No | - | min length: 1; max length: 1000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/agent-sessions/<sessionId>/stop' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Stopped agent session

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.session` | AgentSession | Yes | - | - |
| `data.session.id` | string | Yes | - | format: uuid |
| `data.session.organizationId` | string | Yes | - | format: uuid |
| `data.session.userId` | string | Yes | - | format: uuid |
| `data.session.actorType` | string | Yes | - | one of: web_user, api_token, oauth_mcp, internal_agent |
| `data.session.source` | string | Yes | - | one of: web, api, mcp, agent |
| `data.session.status` | AgentSessionStatus | Yes | - | one of: active, completed, stopped, expired, failed |
| `data.session.title` | string \| null | Yes | - | - |
| `data.session.goal` | string \| null | Yes | - | - |
| `data.session.clientName` | string \| null | Yes | - | - |
| `data.session.clientSessionId` | string \| null | Yes | - | - |
| `data.session.maxToolCalls` | integer \| null | Yes | - | min: 1 |
| `data.session.toolCallsUsed` | integer | Yes | - | min: 0 |
| `data.session.startedAt` | string | Yes | - | format: date-time |
| `data.session.lastSeenAt` | string | Yes | - | format: date-time |
| `data.session.stoppedAt` | string \| null | Yes | - | format: date-time |
| `data.session.expiresAt` | string \| null | Yes | - | format: date-time |
| `data.session.createdAt` | string | Yes | - | format: date-time |
| `data.session.metadata` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/approvals

`ark.list_approval_requests`

Lists pending or resolved MCP and hosted-agent action requests for the connected user.

| Requirement | Value |
| --- | --- |
| Scopes | `agents:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | AgentActionRequestStatus | No | - | - |
| `query.session_id` | string | No | - | format: uuid |
| `query.include_resolved` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/approvals' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Approval requests

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.actionRequests` | array<AgentActionRequest> | Yes | - | - |
| `data.actionRequests[]` | AgentActionRequest | Yes | - | - |
| `data.actionRequests[].id` | string | Yes | - | format: uuid |
| `data.actionRequests[].organizationId` | string | Yes | - | format: uuid |
| `data.actionRequests[].sessionId` | string \| null | Yes | - | format: uuid |
| `data.actionRequests[].requestedByUserId` | string | Yes | - | format: uuid |
| `data.actionRequests[].requestedForUserId` | string | Yes | - | format: uuid |
| `data.actionRequests[].operationId` | string | Yes | - | - |
| `data.actionRequests[].toolName` | string \| null | Yes | - | - |
| `data.actionRequests[].approvalPolicy` | AgentActionApprovalPolicy | Yes | - | one of: draft_only, ask_before_write, ask_before_send, admin_only |
| `data.actionRequests[].riskClass` | AgentActionRiskClass | Yes | - | one of: write, send, payment, destructive, admin, provider_call |
| `data.actionRequests[].status` | AgentActionRequestStatus | Yes | - | one of: pending, approved, rejected, expired, cancelled |
| `data.actionRequests[].title` | string | Yes | - | - |
| `data.actionRequests[].summary` | string \| null | Yes | - | - |
| `data.actionRequests[].input` | object | Yes | - | - |
| `data.actionRequests[].preview` | object | Yes | - | - |
| `data.actionRequests[].idempotencyKey` | string \| null | Yes | - | - |
| `data.actionRequests[].requestId` | string \| null | Yes | - | - |
| `data.actionRequests[].requestedAt` | string | Yes | - | format: date-time |
| `data.actionRequests[].expiresAt` | string | Yes | - | format: date-time |
| `data.actionRequests[].resolvedAt` | string \| null | Yes | - | format: date-time |
| `data.actionRequests[].resolvedByUserId` | string \| null | Yes | - | format: uuid |
| `data.actionRequests[].resolutionReason` | string \| null | Yes | - | - |
| `data.actionRequests[].createdAt` | string | Yes | - | format: date-time |
| `data.actionRequests[].metadata` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/audit/events

`ark.search_audit_events`

Searches the permissioned ARK audit timeline by view, domain, subject, actor, event, provider, trace, team, date range, or text query.

| Requirement | Value |
| --- | --- |
| Scopes | `audit:read` |
| ARK permissions | `canViewAuditTimeline` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.view` | AuditView | No | - | - |
| `query.domainView` | AuditDomainView | No | - | - |
| `query.q` | string | No | - | min length: 1; max length: 200 |
| `query.from` | string | No | - | format: date-time |
| `query.to` | string | No | - | format: date-time |
| `query.subjectType` | string | No | - | max length: 100 |
| `query.subjectId` | string | No | - | max length: 200 |
| `query.actorUserId` | string | No | - | format: uuid |
| `query.actorType` | string | No | - | max length: 100 |
| `query.eventKey` | string | No | - | max length: 200 |
| `query.eventFamily` | string | No | - | max length: 100 |
| `query.visibilityClass` | string | No | - | one of: business, security, admin, operational |
| `query.source` | string | No | - | max length: 100 |
| `query.provider` | string | No | - | max length: 100 |
| `query.correlationId` | string | No | - | max length: 200 |
| `query.transactionId` | string | No | - | - |
| `query.idempotencyKey` | string | No | - | max length: 200 |
| `query.requestId` | string | No | - | max length: 200 |
| `query.teamId` | string | No | - | format: uuid |
| `query.cursorOccurredAt` | string | No | - | format: date-time |
| `query.cursorId` | string | No | - | format: uuid |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/audit/events' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Audit events

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.view` | AuditView | Yes | - | one of: activity, security, payments, integrations, exports, diagnostics; default: "activity" |
| `data.domainView` | AuditDomainView \| null | Yes | - | - |
| `data.rows` | array<AuditTimelineRow> | Yes | - | - |
| `data.rows[]` | AuditTimelineRow | Yes | - | - |
| `data.rows[].id` | string | Yes | - | format: uuid |
| `data.rows[].occurredAt` | string | Yes | - | format: date-time |
| `data.rows[].eventKey` | string | Yes | - | - |
| `data.rows[].eventFamily` | string | Yes | - | - |
| `data.rows[].visibilityClass` | string | Yes | - | one of: business, security, admin, operational |
| `data.rows[].summary` | string | Yes | - | - |
| `data.rows[].actor` | AuditActor | Yes | - | - |
| `data.rows[].actor.type` | string | Yes | - | - |
| `data.rows[].actor.userId` | string \| null | No | - | format: uuid |
| `data.rows[].actor.label` | string | Yes | - | - |
| `data.rows[].actor.provider` | string \| null | No | - | - |
| `data.rows[].source` | string | Yes | - | - |
| `data.rows[].provider` | string \| null | No | - | - |
| `data.rows[].externalIdDisplay` | string \| null | No | - | - |
| `data.rows[].primarySubject` | AuditSubjectChip | Yes | - | - |
| `data.rows[].primarySubject.subjectType` | string | Yes | - | - |
| `data.rows[].primarySubject.canonicalId` | string \| null | No | - | - |
| `data.rows[].primarySubject.displayId` | string \| null | No | - | - |
| `data.rows[].primarySubject.subjectId` | string \| null | No | - | - |
| `data.rows[].primarySubject.relationship` | string | Yes | - | - |
| `data.rows[].primarySubject.label` | string | Yes | - | - |
| `data.rows[].primarySubject.href` | string \| null | No | - | - |
| `data.rows[].primarySubject.permissionState` | string | Yes | - | one of: allowed, restricted, omitted |
| `data.rows[].primarySubject.isPrimary` | boolean | No | - | - |
| `data.rows[].relatedSubjects` | array<AuditSubjectChip> | Yes | - | - |
| `data.rows[].relatedSubjects[]` | AuditSubjectChip | Yes | - | - |
| `data.rows[].relatedSubjects[].subjectType` | string | Yes | - | - |
| `data.rows[].relatedSubjects[].canonicalId` | string \| null | No | - | - |
| `data.rows[].relatedSubjects[].displayId` | string \| null | No | - | - |
| `data.rows[].relatedSubjects[].subjectId` | string \| null | No | - | - |
| `data.rows[].relatedSubjects[].relationship` | string | Yes | - | - |
| `data.rows[].relatedSubjects[].label` | string | Yes | - | - |
| `data.rows[].relatedSubjects[].href` | string \| null | No | - | - |
| `data.rows[].relatedSubjects[].permissionState` | string | Yes | - | one of: allowed, restricted, omitted |
| `data.rows[].relatedSubjects[].isPrimary` | boolean | No | - | - |
| `data.rows[].changeCount` | integer | Yes | - | - |
| `data.rows[].hasRedactedChanges` | boolean | Yes | - | - |
| `data.rows[].hasEvidenceLink` | boolean | Yes | - | - |
| `data.rows[].domainFacts` | object | No | - | - |
| `data.rows[].indicators` | object | No | - | - |
| `data.rows[].restrictedSubjectCount` | integer | Yes | - | - |
| `data.rows[].cursor` | AuditCursor | Yes | - | - |
| `data.rows[].cursor.occurredAt` | string | Yes | - | format: date-time |
| `data.rows[].cursor.id` | string | Yes | - | format: uuid |
| `data.nextCursor` | AuditCursor \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/audit/events/{eventId}

`ark.get_audit_event`

Returns permissioned audit event detail, including requested changes, traces, evidence, or sanitized facts.

| Requirement | Value |
| --- | --- |
| Scopes | `audit:read` |
| ARK permissions | `canViewAuditTimeline` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.eventId` | string | Yes | - | format: uuid |
| `query.occurredAt` | string | Yes | - | format: date-time |
| `query.view` | AuditView | No | - | - |
| `query.domainView` | AuditDomainView | No | - | - |
| `query.sections` | array<AuditDetailSection> | No | Comma-separated or repeated detail sections to return. | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/audit/events/<eventId>?occurredAt=<occurredAt>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Audit event detail

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.view` | AuditView | Yes | - | one of: activity, security, payments, integrations, exports, diagnostics; default: "activity" |
| `data.domainView` | AuditDomainView \| null | Yes | - | - |
| `data.detail` | AuditEventDetail | Yes | - | - |
| `data.detail.event` | object | Yes | - | - |
| `data.detail.event.id` | string | Yes | - | format: uuid |
| `data.detail.event.occurredAt` | string | Yes | - | format: date-time |
| `data.detail.event.statementAt` | string | No | - | format: date-time |
| `data.detail.event.eventKey` | string | Yes | - | - |
| `data.detail.event.eventFamily` | string | Yes | - | - |
| `data.detail.event.operation` | string \| null | No | - | - |
| `data.detail.event.visibilityClass` | string | Yes | - | - |
| `data.detail.event.organizationId` | string | Yes | - | - |
| `data.detail.event.teamId` | string \| null | No | - | - |
| `data.detail.event.tableSchema` | string \| null | No | - | - |
| `data.detail.event.tableName` | string \| null | No | - | - |
| `data.detail.event.recordId` | string \| null | No | - | - |
| `data.detail.event.actor` | AuditActor | Yes | - | - |
| `data.detail.event.actor.type` | string | Yes | - | - |
| `data.detail.event.actor.userId` | string \| null | No | - | format: uuid |
| `data.detail.event.actor.label` | string | Yes | - | - |
| `data.detail.event.actor.provider` | string \| null | No | - | - |
| `data.detail.event.source` | string | Yes | - | - |
| `data.detail.event.appRoute` | string \| null | No | - | - |
| `data.detail.event.provider` | string \| null | No | - | - |
| `data.detail.event.externalIdDisplay` | string \| null | No | - | - |
| `data.detail.event.retentionClass` | string \| null | No | - | - |
| `data.detail.event.schemaVersion` | integer \| null | No | - | - |
| `data.detail.summary` | string \| null | No | - | - |
| `data.detail.subjects` | array<AuditSubjectChip> | Yes | - | - |
| `data.detail.subjects[]` | AuditSubjectChip | Yes | - | - |
| `data.detail.subjects[].subjectType` | string | Yes | - | - |
| `data.detail.subjects[].canonicalId` | string \| null | No | - | - |
| `data.detail.subjects[].displayId` | string \| null | No | - | - |
| `data.detail.subjects[].subjectId` | string \| null | No | - | - |
| `data.detail.subjects[].relationship` | string | Yes | - | - |
| `data.detail.subjects[].label` | string | Yes | - | - |
| `data.detail.subjects[].href` | string \| null | No | - | - |
| `data.detail.subjects[].permissionState` | string | Yes | - | one of: allowed, restricted, omitted |
| `data.detail.subjects[].isPrimary` | boolean | No | - | - |
| `data.detail.changes` | array<AuditRenderedChange> | No | - | - |
| `data.detail.changes[]` | AuditRenderedChange | No | - | - |
| `data.detail.changes[].fieldKey` | string | No | - | - |
| `data.detail.changes[].label` | string | No | - | - |
| `data.detail.changes[].valuePolicy` | string | No | - | one of: plain, masked, presence_only, hash_only, redacted, ignored |
| `data.detail.changes[].sensitivity` | string | No | - | - |
| `data.detail.changes[].oldDisplay` | string \| null | No | - | - |
| `data.detail.changes[].newDisplay` | string \| null | No | - | - |
| `data.detail.changes[].derivedLabel` | string \| null | No | - | - |
| `data.detail.changes[].numericDelta` | number \| null | No | - | - |
| `data.detail.changes[].currency` | string \| null | No | - | - |
| `data.detail.changes[].copyable` | boolean | No | - | - |
| `data.detail.metadata` | object | No | - | - |
| `data.detail.traces` | array<object> | No | - | - |
| `data.detail.traces[]` | object | No | - | - |
| `data.detail.traces[].traceType` | string | No | - | - |
| `data.detail.traces[].label` | string | No | - | - |
| `data.detail.traces[].matchBasis` | string | No | - | - |
| `data.detail.traces[].confidence` | string | No | - | one of: exact, strong, contextual |
| `data.detail.traces[].restrictedEventCount` | integer | No | - | min: 0 |
| `data.detail.traces[].events` | array<AuditTraceEvent> | No | - | - |
| `data.detail.traces[].events[]` | AuditTraceEvent | No | - | - |
| `data.detail.traces[].events[].id` | string | No | - | format: uuid |
| `data.detail.traces[].events[].occurredAt` | string | No | - | format: date-time |
| `data.detail.traces[].events[].eventKey` | string | No | - | - |
| `data.detail.traces[].events[].summary` | string | No | - | - |
| `data.detail.traces[].events[].actorLabel` | string \| null | No | - | - |
| `data.detail.traces[].events[].source` | string \| null | No | - | - |
| `data.detail.evidence` | array<object> | No | - | - |
| `data.detail.evidence[]` | object | No | - | - |
| `data.detail.evidence[].evidenceType` | string | No | - | - |
| `data.detail.evidence[].label` | string | No | - | - |
| `data.detail.evidence[].provider` | string \| null | No | - | - |
| `data.detail.evidence[].occurredAt` | string \| null | No | - | - |
| `data.detail.evidence[].href` | string \| null | No | - | - |
| `data.detail.evidence[].permissionState` | string | No | - | one of: allowed, restricted, omitted |
| `data.detail.evidence[].availabilityState` | string | No | - | - |
| `data.detail.sanitizedFacts` | unknown | No | Permissioned sanitized domain facts for detail views. | - |
| `data.detail.domainFacts` | AuditDomainFacts | No | Sanitized, permissioned audit domain facts keyed by business domain. | - |
| `data.detail.restrictedSubjectCount` | integer | No | - | min: 0 |
| `data.detail.restrictedEvidenceCount` | integer | No | - | min: 0 |
| `data.detail.permissions` | object | Yes | - | - |
| `data.detail.permissions.canExport` | boolean | Yes | - | - |
| `data.detail.permissions.canViewSecurity` | boolean | Yes | - | - |
| `data.detail.permissions.canOpenEvidence` | boolean | Yes | - | - |
| `data.detail.permissions.canViewSanitizedFacts` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### GET /api/v1/audit/exports

`ark.list_audit_exports`

Lists recent audit export requests visible to the connected user.

| Requirement | Value |
| --- | --- |
| Scopes | `audit:export` |
| ARK permissions | `canViewAuditTimeline`, `canExportAuditLog` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/audit/exports' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Audit export requests

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.rows` | array<AuditExportRequestItem> | Yes | - | - |
| `data.rows[]` | AuditExportRequestItem | Yes | - | - |
| `data.rows[].id` | string | Yes | - | format: uuid |
| `data.rows[].requestedAt` | string | Yes | - | format: date-time |
| `data.rows[].status` | AuditExportStatus | Yes | - | one of: queued, completed, failed, expired, denied |
| `data.rows[].reason` | string | Yes | - | - |
| `data.rows[].filters` | object | Yes | - | - |
| `data.rows[].rowCount` | integer \| null | No | - | - |
| `data.rows[].errorCategory` | string \| null | No | - | - |
| `data.rows[].completedAt` | string \| null | No | - | - |
| `data.rows[].expiresAt` | string \| null | No | - | - |
| `data.rows[].downloadedAt` | string \| null | No | - | - |
| `data.rows[].canDownload` | boolean | Yes | - | - |
| `data.rows[].requestedBy` | object | Yes | - | - |
| `data.rows[].requestedBy.userId` | string \| null | No | - | - |
| `data.rows[].requestedBy.label` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/audit/exports

`ark.request_audit_export`

Creates a permissioned audit export request for a bounded date range and selected audit filters.

| Requirement | Value |
| --- | --- |
| Scopes | `audit:export` |
| ARK permissions | `canViewAuditTimeline`, `canExportAuditLog` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `reason` | string | Yes | - | min length: 1; max length: 500 |
| `view` | AuditView | No | - | one of: activity, security, payments, integrations, exports, diagnostics; default: "activity" |
| `domainView` | AuditDomainView | No | - | one of: load.case_file, load.spot_quote_funnel, load.carrier_award, load.dispatch_exceptions, load.load_board, load.tracking, carrier.trust, carrier.onboarding, carrier.payment_risk, carrier.compliance_documents, carrier.provider_monitoring, carrier.rejections_dnu, finance.payment_ledger, finance.ap_settlement, finance.ar_invoice_payment, finance.nacha, finance.quickbooks, finance.pay_holds, finance.report_snapshots, integration.edi_trace, integration.tracking_visibility, integration.settings, evidence.documents, evidence.pod_review, customer.account, customer.locations, people.activity, admin.security, admin.org_config, admin.internal_tools, audit.exports, audit.operations |
| `q` | string | No | - | min length: 1; max length: 200 |
| `from` | string | Yes | - | format: date-time |
| `to` | string | Yes | - | format: date-time |
| `subjectType` | string | No | - | max length: 100 |
| `subjectId` | string | No | - | max length: 200 |
| `actorUserId` | string | No | - | format: uuid |
| `actorType` | string | No | - | max length: 100 |
| `eventKey` | string | No | - | max length: 200 |
| `eventFamily` | string | No | - | max length: 100 |
| `visibilityClass` | string | No | - | one of: business, security, admin, operational |
| `source` | string | No | - | max length: 100 |
| `provider` | string | No | - | max length: 100 |
| `correlationId` | string | No | - | max length: 200 |
| `transactionId` | string | No | - | - |
| `idempotencyKey` | string | No | - | max length: 200 |
| `requestId` | string | No | - | max length: 200 |
| `teamId` | string | No | - | format: uuid |
| `format` | string | No | - | one of: json, csv; default: "json" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/audit/exports' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "<reason>",
  "from": "2026-07-16T14:00:00Z",
  "to": "2026-07-16T14:00:00Z"
}'
```

#### Success response shape

Audit export request queued

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.exportId` | string | Yes | - | format: uuid |
| `data.status` | unknown | Yes | - | - |
| `data.format` | string | Yes | - | one of: json, csv |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/audit/exports/{exportId}/download-url

`ark.get_audit_export_download_url`

Creates a short-lived signed download URL for a completed audit export and records the audit export download event.

| Requirement | Value |
| --- | --- |
| Scopes | `audit:export` |
| ARK permissions | `canViewAuditTimeline`, `canExportAuditLog` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.exportId` | string | Yes | - | format: uuid |
| `query.expiresInSeconds` | integer | No | - | default: 300; min: 60; max: 3600 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/audit/exports/<exportId>/download-url' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Signed audit export download URL

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | AuditExportDownloadUrlResult | Yes | - | - |
| `data.exportId` | string | Yes | - | format: uuid |
| `data.status` | string | Yes | - | one of: downloaded |
| `data.signedUrl` | string | Yes | - | format: uri |
| `data.expiresInSeconds` | integer | Yes | - | min: 60; max: 3600 |
| `data.expiresAt` | string | Yes | - | format: date-time |
| `data.filename` | string | Yes | - | - |
| `data.contentType` | string | Yes | - | - |
| `data.rowCount` | integer \| null | Yes | - | min: 0 |
| `data.downloadedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/audit/facets

`ark.get_audit_facets`

Returns permissioned audit filter facets and event counts for a selected view, domain, date range, and current filters.

| Requirement | Value |
| --- | --- |
| Scopes | `audit:read` |
| ARK permissions | `canViewAuditTimeline` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.view` | AuditView | No | - | - |
| `query.domainView` | AuditDomainView | No | - | - |
| `query.q` | string | No | - | min length: 1; max length: 200 |
| `query.from` | string | No | - | format: date-time |
| `query.to` | string | No | - | format: date-time |
| `query.subjectType` | string | No | - | max length: 100 |
| `query.subjectId` | string | No | - | max length: 200 |
| `query.actorUserId` | string | No | - | format: uuid |
| `query.actorType` | string | No | - | max length: 100 |
| `query.eventKey` | string | No | - | max length: 200 |
| `query.eventFamily` | string | No | - | max length: 100 |
| `query.visibilityClass` | string | No | - | one of: business, security, admin, operational |
| `query.source` | string | No | - | max length: 100 |
| `query.provider` | string | No | - | max length: 100 |
| `query.correlationId` | string | No | - | max length: 200 |
| `query.transactionId` | string | No | - | - |
| `query.idempotencyKey` | string | No | - | max length: 200 |
| `query.requestId` | string | No | - | max length: 200 |
| `query.teamId` | string | No | - | format: uuid |
| `query.facetIds` | array<AuditFacetId> | No | Comma-separated audit facet IDs to count. Omit for the default audit facets. | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/audit/facets' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Audit facets

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.view` | AuditView | Yes | - | one of: activity, security, payments, integrations, exports, diagnostics; default: "activity" |
| `data.domainView` | AuditDomainView \| null | Yes | - | - |
| `data.facetIds` | array<AuditFacetId> \| null | Yes | - | - |
| `data.facets` | array<AuditFacet> | Yes | - | - |
| `data.facets[]` | AuditFacet | Yes | - | - |
| `data.facets[].facetId` | AuditFacetId | Yes | - | one of: summary, visibility_class, workflow_stage, event_family, event_key, provider, source, subject_type, actor_type, indicators, carrier_approval_status, insurance_result, safety_rating, payment_destination_status, award_source, alternate_carrier_count |
| `data.facets[].value` | string | Yes | - | - |
| `data.facets[].label` | string | Yes | - | - |
| `data.facets[].eventCount` | integer | Yes | - | min: 0 |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/audit/groups/{groupId}

`ark.get_audit_group`

Expands one grouped audit timeline item into permissioned source events using the same filters.

| Requirement | Value |
| --- | --- |
| Scopes | `audit:read` |
| ARK permissions | `canViewAuditTimeline` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.groupId` | string | Yes | - | min length: 1; max length: 200 |
| `query.view` | AuditView | No | - | - |
| `query.domainView` | AuditDomainView | No | - | - |
| `query.q` | string | No | - | min length: 1; max length: 200 |
| `query.from` | string | No | - | format: date-time |
| `query.to` | string | No | - | format: date-time |
| `query.subjectType` | string | No | - | max length: 100 |
| `query.subjectId` | string | No | - | max length: 200 |
| `query.actorUserId` | string | No | - | format: uuid |
| `query.actorType` | string | No | - | max length: 100 |
| `query.eventKey` | string | No | - | max length: 200 |
| `query.eventFamily` | string | No | - | max length: 100 |
| `query.visibilityClass` | string | No | - | one of: business, security, admin, operational |
| `query.source` | string | No | - | max length: 100 |
| `query.provider` | string | No | - | max length: 100 |
| `query.correlationId` | string | No | - | max length: 200 |
| `query.transactionId` | string | No | - | - |
| `query.idempotencyKey` | string | No | - | max length: 200 |
| `query.requestId` | string | No | - | max length: 200 |
| `query.teamId` | string | No | - | format: uuid |
| `query.limit` | integer | No | - | default: 100; min: 1; max: 250 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/audit/groups/<groupId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Audit group source events

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.projectionVersion` | unknown | Yes | - | - |
| `data.groupId` | string | Yes | - | - |
| `data.rows` | array<AuditEventProjection> | Yes | - | - |
| `data.rows[]` | AuditEventProjection | Yes | - | - |
| `data.rows[].id` | string | Yes | - | format: uuid |
| `data.rows[].occurredAt` | string | Yes | - | format: date-time |
| `data.rows[].eventKey` | string | Yes | - | - |
| `data.rows[].eventFamily` | string | Yes | - | - |
| `data.rows[].visibilityClass` | string | Yes | - | one of: business, security, admin, operational |
| `data.rows[].summary` | string | Yes | - | - |
| `data.rows[].actor` | AuditActor | Yes | - | - |
| `data.rows[].actor.type` | string | Yes | - | - |
| `data.rows[].actor.userId` | string \| null | No | - | format: uuid |
| `data.rows[].actor.label` | string | Yes | - | - |
| `data.rows[].actor.provider` | string \| null | No | - | - |
| `data.rows[].source` | string | Yes | - | - |
| `data.rows[].provider` | string \| null | No | - | - |
| `data.rows[].externalIdDisplay` | string \| null | No | - | - |
| `data.rows[].primarySubject` | AuditSubjectChip | Yes | - | - |
| `data.rows[].primarySubject.subjectType` | string | Yes | - | - |
| `data.rows[].primarySubject.canonicalId` | string \| null | No | - | - |
| `data.rows[].primarySubject.displayId` | string \| null | No | - | - |
| `data.rows[].primarySubject.subjectId` | string \| null | No | - | - |
| `data.rows[].primarySubject.relationship` | string | Yes | - | - |
| `data.rows[].primarySubject.label` | string | Yes | - | - |
| `data.rows[].primarySubject.href` | string \| null | No | - | - |
| `data.rows[].primarySubject.permissionState` | string | Yes | - | one of: allowed, restricted, omitted |
| `data.rows[].primarySubject.isPrimary` | boolean | No | - | - |
| `data.rows[].relatedSubjects` | array<AuditSubjectChip> | Yes | - | - |
| `data.rows[].relatedSubjects[]` | AuditSubjectChip | Yes | - | - |
| `data.rows[].relatedSubjects[].subjectType` | string | Yes | - | - |
| `data.rows[].relatedSubjects[].canonicalId` | string \| null | No | - | - |
| `data.rows[].relatedSubjects[].displayId` | string \| null | No | - | - |
| `data.rows[].relatedSubjects[].subjectId` | string \| null | No | - | - |
| `data.rows[].relatedSubjects[].relationship` | string | Yes | - | - |
| `data.rows[].relatedSubjects[].label` | string | Yes | - | - |
| `data.rows[].relatedSubjects[].href` | string \| null | No | - | - |
| `data.rows[].relatedSubjects[].permissionState` | string | Yes | - | one of: allowed, restricted, omitted |
| `data.rows[].relatedSubjects[].isPrimary` | boolean | No | - | - |
| `data.rows[].changeCount` | integer | Yes | - | - |
| `data.rows[].hasRedactedChanges` | boolean | Yes | - | - |
| `data.rows[].hasEvidenceLink` | boolean | Yes | - | - |
| `data.rows[].domainFacts` | object | No | - | - |
| `data.rows[].indicators` | object | No | - | - |
| `data.rows[].restrictedSubjectCount` | integer | Yes | - | - |
| `data.rows[].cursor` | AuditCursor | Yes | - | - |
| `data.rows[].cursor.occurredAt` | string | Yes | - | format: date-time |
| `data.rows[].cursor.id` | string | Yes | - | format: uuid |
| `data.rows[].kind` | unknown | Yes | - | - |
| `data.rows[].projectionVersion` | unknown | Yes | - | - |
| `data.rows[].eventId` | string | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/audit/timeline

`ark.get_audit_timeline`

Returns the permissioned grouped audit timeline projection for a selected view, domain, date range, and current filters.

| Requirement | Value |
| --- | --- |
| Scopes | `audit:read` |
| ARK permissions | `canViewAuditTimeline` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.view` | AuditView | No | - | - |
| `query.domainView` | AuditDomainView | No | - | - |
| `query.q` | string | No | - | min length: 1; max length: 200 |
| `query.from` | string | No | - | format: date-time |
| `query.to` | string | No | - | format: date-time |
| `query.subjectType` | string | No | - | max length: 100 |
| `query.subjectId` | string | No | - | max length: 200 |
| `query.actorUserId` | string | No | - | format: uuid |
| `query.actorType` | string | No | - | max length: 100 |
| `query.eventKey` | string | No | - | max length: 200 |
| `query.eventFamily` | string | No | - | max length: 100 |
| `query.visibilityClass` | string | No | - | one of: business, security, admin, operational |
| `query.source` | string | No | - | max length: 100 |
| `query.provider` | string | No | - | max length: 100 |
| `query.correlationId` | string | No | - | max length: 200 |
| `query.transactionId` | string | No | - | - |
| `query.idempotencyKey` | string | No | - | max length: 200 |
| `query.requestId` | string | No | - | max length: 200 |
| `query.teamId` | string | No | - | format: uuid |
| `query.cursorOccurredAt` | string | No | - | format: date-time |
| `query.cursorId` | string | No | - | format: uuid |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/audit/timeline' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Audit timeline

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | AuditTimelineData | Yes | - | - |
| `data.projectionVersion` | unknown | Yes | - | - |
| `data.view` | object | Yes | - | - |
| `data.filters` | object | Yes | - | - |
| `data.rows` | array<AuditTimelineItem> | Yes | - | - |
| `data.rows[]` | AuditTimelineItem | Yes | - | - |
| `data.facets` | array<AuditFacet> | No | - | - |
| `data.facets[]` | AuditFacet | No | - | - |
| `data.facets[].facetId` | AuditFacetId | No | - | one of: summary, visibility_class, workflow_stage, event_family, event_key, provider, source, subject_type, actor_type, indicators, carrier_approval_status, insurance_result, safety_rating, payment_destination_status, award_source, alternate_carrier_count |
| `data.facets[].value` | string | No | - | - |
| `data.facets[].label` | string | No | - | - |
| `data.facets[].eventCount` | integer | No | - | min: 0 |
| `data.rangeSummary` | AuditRangeSummary | No | - | - |
| `data.rangeSummary.total` | integer | No | - | min: 0 |
| `data.rangeSummary.byVisibility` | object | No | - | - |
| `data.rangeSummary.redacted` | integer | No | - | min: 0 |
| `data.rangeSummary.evidence` | integer | No | - | min: 0 |
| `data.rangeSummary.restricted` | integer | No | - | min: 0 |
| `data.pageInfo` | object | Yes | - | - |
| `data.pageInfo.nextCursor` | AuditCursor | No | - | - |
| `data.pageInfo.nextCursor.occurredAt` | string | No | - | format: date-time |
| `data.pageInfo.nextCursor.id` | string | No | - | format: uuid |
| `data.pageInfo.hasNextPage` | boolean | Yes | - | - |
| `data.pageInfo.newerCursor` | AuditCursor | No | - | - |
| `data.pageInfo.newerCursor.occurredAt` | string | No | - | format: date-time |
| `data.pageInfo.newerCursor.id` | string | No | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/billing/carrier-ach-files

`ark.list_carrier_ach_files`

Lists visible carrier ACH/NACHA batches for reconciliation with status, effective-date, file-name, and batch-number filters.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | string | No | - | one of: GENERATED, UPLOADED, PROCESSED, REJECTED |
| `query.date_from` | string | No | - | - |
| `query.date_to` | string | No | - | - |
| `query.search` | string | No | File-name or batch-number search. | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/carrier-ach-files' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier ACH files

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.files` | array<CarrierAchFileSummary> | Yes | - | - |
| `data.files[]` | CarrierAchFileSummary | Yes | - | - |
| `data.files[].nachaFileId` | string | Yes | - | format: uuid |
| `data.files[].batchNumber` | integer | Yes | - | - |
| `data.files[].fileName` | string | Yes | - | - |
| `data.files[].effectiveDate` | string | Yes | - | format: date |
| `data.files[].totalAmount` | string | Yes | Decimal total amount as a string. | - |
| `data.files[].entryCount` | integer | Yes | - | - |
| `data.files[].status` | string | Yes | - | - |
| `data.files[].createdAt` | string | Yes | - | format: date-time |
| `data.files[].createdByName` | string | Yes | - | - |
| `data.pagination` | CarrierAchFileOffsetPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/billing/carrier-ach-files/{nachaFileId}

`ark.get_carrier_ach_file`

Returns a visible carrier ACH/NACHA batch with entries and linked carrier payments for reconciliation.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.nachaFileId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/carrier-ach-files/<nachaFileId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier ACH file

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | GetCarrierAchFileResult | Yes | - | - |
| `data.nachaFileId` | string | Yes | - | format: uuid |
| `data.batchNumber` | integer | Yes | - | - |
| `data.fileName` | string | Yes | - | - |
| `data.effectiveDate` | string | Yes | - | format: date |
| `data.totalAmount` | string | Yes | Decimal total amount as a string. | - |
| `data.entryCount` | integer | Yes | - | - |
| `data.status` | string | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.createdByName` | string | Yes | - | - |
| `data.csvData` | array<unknown> \| object \| null | Yes | Stored reconciliation CSV metadata for the batch. | - |
| `data.entries` | array<CarrierAchFileEntry> | Yes | - | - |
| `data.entries[]` | CarrierAchFileEntry | Yes | - | - |
| `data.entries[].nachaFileEntryId` | string | Yes | - | format: uuid |
| `data.entries[].entryType` | string | Yes | - | - |
| `data.entries[].traceSequence` | string | Yes | - | - |
| `data.entries[].settlementNumber` | integer \| null | Yes | - | - |
| `data.entries[].referenceNumber` | string \| null | Yes | - | - |
| `data.entries[].amount` | string | Yes | Decimal amount as a string. | - |
| `data.entries[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.entries[].carrierName` | string \| null | Yes | - | - |
| `data.entries[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.entries[].factoringName` | string \| null | Yes | - | - |
| `data.entries[].bankRoutingMasked` | string \| null | Yes | - | - |
| `data.entries[].bankAccountMasked` | string \| null | Yes | - | - |
| `data.entries[].addendaText` | string \| null | Yes | - | - |
| `data.payments` | array<CarrierAchFilePayment> | Yes | - | - |
| `data.payments[]` | CarrierAchFilePayment | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | - |
| `data.payments[].dispatchId` | string | Yes | - | - |
| `data.payments[].loadNumber` | number \| null | Yes | - | - |
| `data.payments[].settlementNumber` | integer \| null | Yes | - | - |
| `data.payments[].referenceNumber` | string \| null | Yes | - | - |
| `data.payments[].invoiceNumber` | integer \| null | Yes | - | - |
| `data.payments[].invoiceVersion` | integer \| null | Yes | - | - |
| `data.payments[].vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.payments[].docNumber` | string \| null | Yes | - | - |
| `data.payments[].amount` | string | Yes | Decimal amount as a string. | - |
| `data.payments[].carrierId` | string | Yes | - | format: uuid |
| `data.payments[].carrierName` | string \| null | Yes | - | - |
| `data.payments[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.payments[].factoringName` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/billing/carrier-ach-files/{nachaFileId}

`ark.update_carrier_ach_file_status`

Updates the status of a visible carrier ACH/NACHA batch after bank upload, processing, or rejection.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.nachaFileId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `status` | string | Yes | - | one of: GENERATED, UPLOADED, PROCESSED, REJECTED |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/billing/carrier-ach-files/<nachaFileId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "GENERATED"
}'
```

#### Success response shape

Updated carrier ACH file status

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateCarrierAchFileStatusResult | Yes | - | - |
| `data.nachaFileId` | string | Yes | - | format: uuid |
| `data.batchNumber` | integer | Yes | - | - |
| `data.previousStatus` | string | Yes | - | - |
| `data.status` | string | Yes | - | one of: GENERATED, UPLOADED, PROCESSED, REJECTED |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/billing/carrier-ach-files/generate

`ark.generate_carrier_ach_file`

Generates a NACHA ACH file from selected ready carrier payments, assigns settlement numbers, records the batch, and links payments to ACH entries.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierPaymentIds` | array<string> | Yes | READY carrier payment IDs to include in the ACH/NACHA batch. | min items: 1; max items: 250 |
| `carrierPaymentIds[]` | string | Yes | - | format: uuid |
| `effectiveDate` | string | Yes | ACH effective date in YYYY-MM-DD format. | - |
| `includeFileContent` | boolean | No | When true, return the raw NACHA file and reconciliation CSV in the initial response. These include sensitive bank payment data and are redacted from idempotent replays. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/carrier-ach-files/generate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "carrierPaymentIds": [
    "<carrierPaymentIds>"
  ],
  "effectiveDate": "<effectiveDate>"
}'
```

#### Success response shape

Generated carrier ACH file

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | GenerateCarrierAchFileResult | Yes | - | - |
| `data.nachaFileId` | string | Yes | - | format: uuid |
| `data.batchNumber` | integer | Yes | - | - |
| `data.fileName` | string | Yes | - | - |
| `data.effectiveDate` | string | Yes | - | format: date |
| `data.paymentCount` | integer | Yes | - | - |
| `data.entryCount` | integer | Yes | - | - |
| `data.totalAmount` | string | Yes | Decimal total amount as a string. | - |
| `data.settlementNumbers` | array<integer> | Yes | - | - |
| `data.settlementNumbers[]` | integer | Yes | - | - |
| `data.payments` | array<GenerateCarrierAchFilePayment> | Yes | - | - |
| `data.payments[]` | GenerateCarrierAchFilePayment | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | format: uuid |
| `data.payments[].dispatchId` | string | Yes | - | format: uuid |
| `data.payments[].loadNumber` | number \| null | Yes | - | - |
| `data.payments[].settlementNumber` | integer | Yes | - | - |
| `data.payments[].referenceNumber` | string | Yes | - | - |
| `data.payments[].amount` | string | Yes | Decimal amount as a string. | - |
| `data.payments[].recipientType` | string | Yes | - | one of: carrier, factoring |
| `data.payments[].recipientId` | string | Yes | - | format: uuid |
| `data.payments[].recipientName` | string | Yes | - | - |
| `data.includesSensitiveFileContent` | boolean | Yes | - | - |
| `data.nachaFileText` | string | No | Raw NACHA file body. Present only when includeFileContent is true. | - |
| `data.reconciliationCsv` | string | No | Reconciliation CSV. Present only when includeFileContent is true. | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/billing/carrier-ach-files/regenerate

`ark.regenerate_carrier_ach_file`

Regenerates a carrier ACH/NACHA file from existing pending settlement numbers, updates their effective paid date, and returns optional file content without creating a duplicate ACH batch record.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `settlementNumbers` | array<integer> | Yes | Existing visible PENDING carrier settlement numbers to regenerate. | min items: 1; max items: 50 |
| `settlementNumbers[]` | integer | Yes | - | min: 1 |
| `effectiveDate` | string | Yes | ACH effective date in YYYY-MM-DD format. | - |
| `includeFileContent` | boolean | No | When true, return the raw NACHA file and reconciliation CSV in the initial response. These include sensitive bank payment data and are redacted from idempotent replays. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/carrier-ach-files/regenerate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "settlementNumbers": [
    1
  ],
  "effectiveDate": "<effectiveDate>"
}'
```

#### Success response shape

Regenerated carrier ACH file

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RegenerateCarrierAchFileResult | Yes | - | - |
| `data.fileName` | string | Yes | - | - |
| `data.effectiveDate` | string | Yes | - | format: date |
| `data.paymentCount` | integer | Yes | - | - |
| `data.entryCount` | integer | Yes | - | - |
| `data.totalAmount` | string | Yes | Decimal total amount as a string. | - |
| `data.settlementNumbers` | array<integer> | Yes | - | - |
| `data.settlementNumbers[]` | integer | Yes | - | - |
| `data.sourceNachaFileIds` | array<string> | Yes | Existing ACH batch record IDs already linked to the settlement payments, if any. | - |
| `data.sourceNachaFileIds[]` | string | Yes | - | format: uuid |
| `data.payments` | array<GenerateCarrierAchFilePayment> | Yes | - | - |
| `data.payments[]` | GenerateCarrierAchFilePayment | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | format: uuid |
| `data.payments[].dispatchId` | string | Yes | - | format: uuid |
| `data.payments[].loadNumber` | number \| null | Yes | - | - |
| `data.payments[].settlementNumber` | integer | Yes | - | - |
| `data.payments[].referenceNumber` | string | Yes | - | - |
| `data.payments[].amount` | string | Yes | Decimal amount as a string. | - |
| `data.payments[].recipientType` | string | Yes | - | one of: carrier, factoring |
| `data.payments[].recipientId` | string | Yes | - | format: uuid |
| `data.payments[].recipientName` | string | Yes | - | - |
| `data.includesSensitiveFileContent` | boolean | Yes | - | - |
| `data.nachaFileText` | string | No | Raw NACHA file body. Present only when includeFileContent is true. | - |
| `data.reconciliationCsv` | string | No | Reconciliation CSV. Present only when includeFileContent is true. | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### GET /api/v1/billing/carrier-payments

`ark.list_carrier_payments`

Lists visible carrier payable rows with billing, POD, hold, settlement, and NACHA metadata for AP workflows.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | string | No | - | one of: DELIVERED, READY, PENDING, PAID |
| `query.carrier_id` | string | No | - | format: uuid |
| `query.customer_id` | string | No | - | format: uuid |
| `query.factoring_id` | string | No | - | format: uuid |
| `query.payment_method` | string | No | - | max length: 50 |
| `query.pay_hold` | string | No | - | one of: all, yes, no; default: "all" |
| `query.has_billing_info` | string | No | - | one of: all, yes, no; default: "all" |
| `query.has_pod` | string | No | - | one of: all, yes, no; default: "all" |
| `query.due_date_from` | string | No | - | - |
| `query.due_date_to` | string | No | - | - |
| `query.paid_date_from` | string | No | - | - |
| `query.paid_date_to` | string | No | - | - |
| `query.search` | string | No | Search across load number, carrier, customer, factoring company, invoice, settlement, reference, vendor invoice, and document number. | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/carrier-payments' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier payments

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.payments` | array<CarrierPaymentListItem> | Yes | - | - |
| `data.payments[]` | CarrierPaymentListItem | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | - |
| `data.payments[].dispatchId` | string | Yes | - | - |
| `data.payments[].loadNumber` | number \| null | Yes | - | - |
| `data.payments[].status` | string \| null | Yes | - | - |
| `data.payments[].invoiceNumber` | integer \| null | Yes | - | - |
| `data.payments[].invoiceVersion` | integer \| null | Yes | - | - |
| `data.payments[].docNumber` | string \| null | Yes | - | - |
| `data.payments[].vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.payments[].referenceNumber` | string \| null | Yes | - | - |
| `data.payments[].settlementNumber` | integer \| null | Yes | - | - |
| `data.payments[].amount` | string | Yes | Decimal carrier payment amount as a string. | - |
| `data.payments[].currency` | string | Yes | - | - |
| `data.payments[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.payments[].paidDate` | string \| null | Yes | - | format: date |
| `data.payments[].carrierId` | string | Yes | - | format: uuid |
| `data.payments[].carrierName` | string \| null | Yes | - | - |
| `data.payments[].customerId` | string \| null | Yes | - | format: uuid |
| `data.payments[].customerName` | string \| null | Yes | - | - |
| `data.payments[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.payments[].factoringName` | string \| null | Yes | - | - |
| `data.payments[].paymentMethod` | string \| null | Yes | - | - |
| `data.payments[].onHold` | boolean | Yes | - | - |
| `data.payments[].hasBillingInfo` | boolean | Yes | - | - |
| `data.payments[].hasPod` | boolean | Yes | - | - |
| `data.payments[].packetFileId` | string \| null | Yes | - | format: uuid |
| `data.payments[].nachaFileId` | string \| null | Yes | - | format: uuid |
| `data.payments[].nachaBatchNumber` | integer \| null | Yes | - | - |
| `data.pagination` | CarrierPaymentListPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/billing/carrier-payments/back-to-delivered

`ark.move_carrier_payments_back_to_delivered`

Moves selected ready carrier payments back to DELIVERED, releases dispatch pay assignments, and removes local QuickBooks carrier bill mappings.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `payments` | array<CarrierPaymentIdItem> | Yes | - | min items: 1; max items: 100 |
| `payments[]` | CarrierPaymentIdItem | Yes | - | - |
| `payments[].carrierPaymentId` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/carrier-payments/back-to-delivered' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "payments": [
    {
      "carrierPaymentId": "<carrierPaymentId>"
    }
  ]
}'
```

#### Success response shape

Moved carrier payments back to delivered

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | MoveCarrierPaymentsBackToDeliveredResult | Yes | - | - |
| `data.updatedCount` | integer | Yes | - | - |
| `data.payments` | array<CarrierPaymentWorkflowItem> | Yes | - | - |
| `data.payments[]` | CarrierPaymentWorkflowItem | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | format: uuid |
| `data.payments[].dispatchId` | string | Yes | - | format: uuid |
| `data.payments[].loadNumber` | string | Yes | - | - |
| `data.payments[].status` | string | Yes | - | - |
| `data.payments[].vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.payments[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.dispatchPayRowsReleased` | integer | Yes | - | - |
| `data.quickBooksMappingsDeleted` | integer | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/billing/carrier-payments/ready

`ark.mark_carrier_payments_ready`

Moves selected delivered carrier payments to READY in one AP workflow after validating hold, billing info, POD readiness, and optional vendor invoice numbers.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `payments` | array<object> | Yes | - | min items: 1; max items: 100 |
| `payments[]` | object | Yes | - | - |
| `payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `payments[].vendorInvoiceNumber` | string \| null | No | - | max length: 100 |
| `queueQuickBooksSync` | boolean | No | - | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/carrier-payments/ready' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "payments": [
    {
      "carrierPaymentId": "<carrierPaymentId>"
    }
  ]
}'
```

#### Success response shape

Marked carrier payments ready

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | MarkCarrierPaymentsReadyResult | Yes | - | - |
| `data.updatedCount` | integer | Yes | - | - |
| `data.payments` | array<MarkCarrierPaymentsReadyResultItem> | Yes | - | - |
| `data.payments[]` | MarkCarrierPaymentsReadyResultItem | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | format: uuid |
| `data.payments[].dispatchId` | string | Yes | - | format: uuid |
| `data.payments[].loadNumber` | string | Yes | - | - |
| `data.payments[].status` | string | Yes | - | - |
| `data.payments[].vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.payments[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.payments[].paymentAmount` | string | Yes | - | - |
| `data.payments[].hasBillingInfo` | boolean | Yes | - | - |
| `data.payments[].hasPod` | boolean | Yes | - | - |
| `data.quickBooksSync` | QuickBooksSyncSummary | Yes | - | - |
| `data.quickBooksSync.requested` | boolean | Yes | - | - |
| `data.quickBooksSync.queued` | boolean | Yes | - | - |
| `data.quickBooksSync.status` | string \| null | Yes | - | - |
| `data.quickBooksSync.jobId` | string \| null | Yes | - | format: uuid |
| `data.quickBooksSync.error` | string \| null | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/billing/carrier-payments/record

`ark.record_carrier_payments`

Records selected ready or invoiced carrier payments as paid in one AP workflow, with optional QuickBooks bill payment sync.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierPaymentIds` | array<string> | Yes | Visible READY or INVOICED carrier payment IDs to mark PAID. | min items: 1; max items: 100 |
| `carrierPaymentIds[]` | string | Yes | - | format: uuid |
| `referenceNumber` | string \| null | No | Optional payment reference number applied to every selected payment. | max length: 100 |
| `paidDate` | string | Yes | Payment date in YYYY-MM-DD format. | - |
| `queueQuickBooksSync` | boolean | No | - | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/carrier-payments/record' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "carrierPaymentIds": [
    "<carrierPaymentIds>"
  ],
  "paidDate": "<paidDate>"
}'
```

#### Success response shape

Recorded carrier payments

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RecordCarrierPaymentsResult | Yes | - | - |
| `data.carrierPaymentIds` | array<string> | Yes | - | - |
| `data.carrierPaymentIds[]` | string | Yes | - | format: uuid |
| `data.paidDate` | string | Yes | - | format: date |
| `data.referenceNumber` | string \| null | Yes | - | - |
| `data.updatedCount` | integer | Yes | - | - |
| `data.payments` | array<CarrierPaymentWorkflowItem & object> | Yes | - | - |
| `data.payments[]` | CarrierPaymentWorkflowItem & object | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | format: uuid |
| `data.payments[].dispatchId` | string | Yes | - | format: uuid |
| `data.payments[].loadNumber` | string | Yes | - | - |
| `data.payments[].status` | string | Yes | - | - |
| `data.payments[].vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.payments[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.payments[].paidDate` | string | Yes | - | format: date |
| `data.payments[].referenceNumber` | string \| null | Yes | - | - |
| `data.payments[].paymentAmount` | string \| null | Yes | - | - |
| `data.payments[].settlementNumber` | integer \| null | Yes | - | - |
| `data.payments[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.payments[].currency` | string | Yes | - | - |
| `data.quickBooksSync` | QuickBooksSyncSummary | Yes | - | - |
| `data.quickBooksSync.requested` | boolean | Yes | - | - |
| `data.quickBooksSync.queued` | boolean | Yes | - | - |
| `data.quickBooksSync.status` | string \| null | Yes | - | - |
| `data.quickBooksSync.jobId` | string \| null | Yes | - | format: uuid |
| `data.quickBooksSync.error` | string \| null | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### PATCH /api/v1/billing/carrier-payments/vendor-invoice-numbers

`ark.update_carrier_vendor_invoice_numbers`

Updates vendor invoice numbers for selected delivered or ready carrier payments in one billing-grid workflow.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `payments` | array<object> | Yes | - | min items: 1; max items: 100 |
| `payments[]` | object | Yes | - | - |
| `payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `payments[].vendorInvoiceNumber` | string \| null | Yes | Vendor invoice number to save. Use null or an empty string to clear it. | max length: 100 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/billing/carrier-payments/vendor-invoice-numbers' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "payments": [
    {
      "carrierPaymentId": "<carrierPaymentId>",
      "vendorInvoiceNumber": "<vendorInvoiceNumber>"
    }
  ]
}'
```

#### Success response shape

Updated carrier vendor invoice numbers

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateCarrierVendorInvoiceNumbersResult | Yes | - | - |
| `data.updatedCount` | integer | Yes | - | - |
| `data.payments` | array<CarrierPaymentWorkflowItem> | Yes | - | - |
| `data.payments[]` | CarrierPaymentWorkflowItem | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | format: uuid |
| `data.payments[].dispatchId` | string | Yes | - | format: uuid |
| `data.payments[].loadNumber` | string | Yes | - | - |
| `data.payments[].status` | string | Yes | - | - |
| `data.payments[].vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.payments[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/billing/carrier-remittance-emails/preflight

`ark.preflight_carrier_remittance_email`

Checks grouped carrier or factoring remittance recipients before sending AP remittance email.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `value` | PreflightCarrierRemittanceEmailRequest | Yes | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/carrier-remittance-emails/preflight' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "remittanceType": "payment",
  "carrierPaymentIds": [
    "<carrierPaymentIds>"
  ]
}'
```

#### Success response shape

Carrier remittance email preflight

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |

#### Errors

_No operation-specific error responses._

### POST /api/v1/billing/carrier-remittance-emails/send

`ark.send_carrier_remittance_email`

Sends carrier or factoring remittance emails for selected visible carrier payments or settlement numbers using grouped AP remittance details.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `value` | SendCarrierRemittanceEmailRequest | Yes | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/carrier-remittance-emails/send' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "remittanceType": "payment",
  "carrierPaymentIds": [
    "<carrierPaymentIds>"
  ],
  "paymentDate": "<paymentDate>"
}'
```

#### Success response shape

Sent carrier remittance email

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SendCarrierRemittanceEmailResult | Yes | - | - |
| `data.remittanceType` | string | Yes | - | one of: payment, settlement |
| `data.requestedCount` | integer | Yes | - | min: 1 |
| `data.carrierPaymentCount` | integer | Yes | - | min: 1 |
| `data.sentGroupCount` | integer | Yes | - | min: 0 |
| `data.paymentDate` | string | Yes | - | - |
| `data.sentAt` | string | Yes | - | format: date-time |
| `data.groups` | array<CarrierRemittanceEmailGroup> | Yes | - | - |
| `data.groups[]` | CarrierRemittanceEmailGroup | Yes | - | - |
| `data.groups[].recipientKind` | string | Yes | - | one of: carrier, factoring |
| `data.groups[].recipientEmail` | string | Yes | - | format: email |
| `data.groups[].recipientName` | string | Yes | - | - |
| `data.groups[].carrierId` | string | Yes | - | format: uuid |
| `data.groups[].carrierName` | string | Yes | - | - |
| `data.groups[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.groups[].factoringName` | string \| null | Yes | - | - |
| `data.groups[].currencyCode` | string \| null | Yes | - | - |
| `data.groups[].totalAmount` | number | Yes | - | - |
| `data.groups[].loadCount` | integer | Yes | - | min: 0 |
| `data.groups[].achGroups` | array<CarrierRemittanceEmailAchGroup> | Yes | - | - |
| `data.groups[].achGroups[]` | CarrierRemittanceEmailAchGroup | Yes | - | - |
| `data.groups[].achGroups[].id` | string | Yes | - | - |
| `data.groups[].achGroups[].label` | string | Yes | - | - |
| `data.groups[].achGroups[].type` | string | Yes | - | one of: payment, settlement |
| `data.groups[].achGroups[].paymentId` | string \| null | Yes | - | format: uuid |
| `data.groups[].achGroups[].settlementNumber` | integer \| null | Yes | - | min: 1 |
| `data.groups[].achGroups[].currencyCode` | string \| null | Yes | - | - |
| `data.groups[].achGroups[].totalAmount` | number | Yes | - | - |
| `data.groups[].achGroups[].loadCount` | integer | Yes | - | min: 0 |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### GET /api/v1/billing/carrier-settlements

`ark.list_carrier_settlements`

Lists visible carrier settlement groups with AP recipient, due date, paid date, amount, and NACHA metadata.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | string | No | - | one of: PENDING, PAID |
| `query.carrier_id` | string | No | - | format: uuid |
| `query.customer_id` | string | No | - | format: uuid |
| `query.factoring_id` | string | No | - | format: uuid |
| `query.payment_method` | string | No | - | max length: 50 |
| `query.due_date_from` | string | No | - | - |
| `query.due_date_to` | string | No | - | - |
| `query.paid_date_from` | string | No | - | - |
| `query.paid_date_to` | string | No | - | - |
| `query.nacha_file_id` | string | No | - | format: uuid |
| `query.nacha_batch_number` | integer | No | - | min: 1 |
| `query.search` | string | No | Search across settlement number, load number, carrier, customer, factoring company, invoice, reference, vendor invoice, document number, and NACHA batch. | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/carrier-settlements' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier settlements

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.settlements` | array<CarrierSettlementListItem> | Yes | - | - |
| `data.settlements[]` | CarrierSettlementListItem | Yes | - | - |
| `data.settlements[].settlementNumber` | integer | Yes | - | - |
| `data.settlements[].status` | string \| null | Yes | - | - |
| `data.settlements[].loadCount` | integer | Yes | - | - |
| `data.settlements[].paymentCount` | integer | Yes | - | - |
| `data.settlements[].totalAmount` | string | Yes | Decimal settlement total amount as a string. | - |
| `data.settlements[].currency` | string | Yes | - | - |
| `data.settlements[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.settlements[].paidDate` | string \| null | Yes | - | format: date |
| `data.settlements[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.settlements[].carrierName` | string \| null | Yes | - | - |
| `data.settlements[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.settlements[].factoringName` | string \| null | Yes | - | - |
| `data.settlements[].paymentMethod` | string \| null | Yes | - | - |
| `data.settlements[].vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.settlements[].nachaFileId` | string \| null | Yes | - | format: uuid |
| `data.settlements[].nachaBatchNumber` | integer \| null | Yes | - | - |
| `data.pagination` | CarrierSettlementListPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/billing/carrier-settlements/{settlementNumber}

`ark.get_carrier_settlement`

Returns one visible carrier settlement group with the payment rows needed to review or confirm AP settlement actions.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.settlementNumber` | integer | Yes | - | min: 1 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/carrier-settlements/<settlementNumber>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier settlement

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.settlement` | CarrierSettlementListItem | Yes | - | - |
| `data.settlement.settlementNumber` | integer | Yes | - | - |
| `data.settlement.status` | string \| null | Yes | - | - |
| `data.settlement.loadCount` | integer | Yes | - | - |
| `data.settlement.paymentCount` | integer | Yes | - | - |
| `data.settlement.totalAmount` | string | Yes | Decimal settlement total amount as a string. | - |
| `data.settlement.currency` | string | Yes | - | - |
| `data.settlement.dueDate` | string \| null | Yes | - | format: date-time |
| `data.settlement.paidDate` | string \| null | Yes | - | format: date |
| `data.settlement.carrierId` | string \| null | Yes | - | format: uuid |
| `data.settlement.carrierName` | string \| null | Yes | - | - |
| `data.settlement.factoringId` | string \| null | Yes | - | format: uuid |
| `data.settlement.factoringName` | string \| null | Yes | - | - |
| `data.settlement.paymentMethod` | string \| null | Yes | - | - |
| `data.settlement.vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.settlement.nachaFileId` | string \| null | Yes | - | format: uuid |
| `data.settlement.nachaBatchNumber` | integer \| null | Yes | - | - |
| `data.payments` | array<CarrierSettlementPaymentDetail> | Yes | - | - |
| `data.payments[]` | CarrierSettlementPaymentDetail | Yes | - | - |
| `data.payments[].carrierPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | - |
| `data.payments[].dispatchId` | string | Yes | - | - |
| `data.payments[].loadNumber` | number \| null | Yes | - | - |
| `data.payments[].customerId` | string \| null | Yes | - | format: uuid |
| `data.payments[].customerName` | string \| null | Yes | - | - |
| `data.payments[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.payments[].carrierName` | string \| null | Yes | - | - |
| `data.payments[].status` | string \| null | Yes | - | - |
| `data.payments[].invoiceNumber` | integer \| null | Yes | - | - |
| `data.payments[].invoiceVersion` | integer \| null | Yes | - | - |
| `data.payments[].docNumber` | string \| null | Yes | - | - |
| `data.payments[].vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.payments[].referenceNumber` | string \| null | Yes | - | - |
| `data.payments[].amount` | string | Yes | Decimal carrier payment amount as a string. | - |
| `data.payments[].currency` | string | Yes | - | - |
| `data.payments[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.payments[].paidDate` | string \| null | Yes | - | format: date |
| `data.payments[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.payments[].factoringName` | string \| null | Yes | - | - |
| `data.payments[].paymentMethod` | string \| null | Yes | - | - |
| `data.payments[].packetFileId` | string \| null | Yes | - | format: uuid |
| `data.payments[].nachaFileId` | string \| null | Yes | - | format: uuid |
| `data.payments[].nachaBatchNumber` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/billing/carrier-settlements/record

`ark.record_carrier_settlement_payment`

Records one or more pending carrier settlements as paid across the visible loads in those settlements.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `settlementNumbers` | array<integer> | Yes | Pending carrier settlement numbers to record as paid. | min items: 1; max items: 50 |
| `settlementNumbers[]` | integer | Yes | - | min: 1 |
| `referenceNumber` | string \| null | No | Optional payment reference number. | max length: 100 |
| `paidDate` | string | Yes | Payment date in YYYY-MM-DD format. | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/carrier-settlements/record' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "settlementNumbers": [
    1
  ],
  "paidDate": "<paidDate>"
}'
```

#### Success response shape

Recorded carrier settlement payment

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RecordCarrierSettlementPaymentResult | Yes | - | - |
| `data.settlementNumbers` | array<integer> | Yes | - | - |
| `data.settlementNumbers[]` | integer | Yes | - | - |
| `data.paidDate` | string | Yes | - | format: date |
| `data.referenceNumber` | string \| null | Yes | - | - |
| `data.paymentsUpdated` | integer | Yes | - | - |
| `data.settlements` | array<CarrierSettlementRecordSummary> | Yes | - | - |
| `data.settlements[]` | CarrierSettlementRecordSummary | Yes | - | - |
| `data.settlements[].settlementNumber` | integer | Yes | - | - |
| `data.settlements[].paymentCount` | integer | Yes | - | - |
| `data.settlements[].totalAmount` | string | Yes | - | - |
| `data.settlements[].currency` | string | Yes | - | - |
| `data.settlements[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.settlements[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.settlements[].carrierName` | string \| null | Yes | - | - |
| `data.settlements[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.settlements[].factoringName` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### GET /api/v1/billing/customer-payments

`ark.list_customer_payments`

Lists visible customer billing rows with invoice, payment, hold, POD, remit profile, and carrier payment context for AR workflows.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | string | No | - | one of: DELIVERED, READY, INVOICED, FACTORED, PAID |
| `query.customer_id` | string | No | - | format: uuid |
| `query.pay_hold` | string | No | - | one of: all, yes, no; default: "all" |
| `query.has_pod` | string | No | - | one of: all, yes, no; default: "all" |
| `query.delivery_date_from` | string | No | - | - |
| `query.delivery_date_to` | string | No | - | - |
| `query.invoiced_date_from` | string | No | - | - |
| `query.invoiced_date_to` | string | No | - | - |
| `query.paid_date_from` | string | No | - | - |
| `query.paid_date_to` | string | No | - | - |
| `query.search` | string | No | Search across load number, customer, invoice, reference, document number, remit profile, pickup number, PO, BOL, origin, and destination. | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/customer-payments' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Customer payments

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.payments` | array<CustomerPaymentListItem> | Yes | - | - |
| `data.payments[]` | CustomerPaymentListItem | Yes | - | - |
| `data.payments[].customerPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | - |
| `data.payments[].loadNumber` | number \| null | Yes | - | - |
| `data.payments[].status` | string \| null | Yes | - | - |
| `data.payments[].invoiceNumber` | integer \| null | Yes | - | - |
| `data.payments[].invoiceVersion` | integer \| null | Yes | - | - |
| `data.payments[].docNumber` | string \| null | Yes | - | - |
| `data.payments[].amount` | string | Yes | Decimal customer payment amount as a string. | - |
| `data.payments[].currency` | string | Yes | - | - |
| `data.payments[].totalCustomerPay` | string | Yes | Decimal unassigned customer charge total as a string. | - |
| `data.payments[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.payments[].invoicedDate` | string \| null | Yes | - | format: date-time |
| `data.payments[].paidDate` | string \| null | Yes | - | format: date |
| `data.payments[].dueDate` | string \| null | Yes | - | format: date-time |
| `data.payments[].referenceNumber` | string \| null | Yes | - | - |
| `data.payments[].customerId` | string \| null | Yes | - | format: uuid |
| `data.payments[].customerName` | string \| null | Yes | - | - |
| `data.payments[].pickupNumber` | string \| null | Yes | - | - |
| `data.payments[].purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.payments[].billOfLading` | string \| null | Yes | - | - |
| `data.payments[].origin` | string \| null | Yes | - | - |
| `data.payments[].destination` | string \| null | Yes | - | - |
| `data.payments[].pickupDate` | string \| null | Yes | - | format: date-time |
| `data.payments[].deliveryDate` | string \| null | Yes | - | format: date-time |
| `data.payments[].onHold` | boolean | Yes | - | - |
| `data.payments[].hasPod` | boolean | Yes | - | - |
| `data.payments[].packetFileId` | string \| null | Yes | - | format: uuid |
| `data.payments[].carrierPaymentStatus` | string | Yes | - | one of: UNPAID, PARTIAL, PAID |
| `data.payments[].carrierPaidCount` | integer | Yes | - | - |
| `data.payments[].carrierTotalCount` | integer | Yes | - | - |
| `data.payments[].carrierPaidAmount` | string | Yes | - | - |
| `data.payments[].carrierTotalAmount` | string | Yes | - | - |
| `data.payments[].invoiceRemitProfileId` | string \| null | Yes | - | format: uuid |
| `data.payments[].invoiceRemitProfileVersion` | integer \| null | Yes | - | - |
| `data.payments[].invoiceRemitProfileType` | string \| null | Yes | - | - |
| `data.payments[].invoiceRemitProfileName` | string \| null | Yes | - | - |
| `data.payments[].invoiceRemitRecipientEmail` | string \| null | Yes | - | - |
| `data.payments[].invoiceRemitRecipientMode` | string \| null | Yes | - | - |
| `data.pagination` | CustomerPaymentListPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/billing/customer-payments/back-to-delivered

`ark.move_customer_payments_back_to_delivered`

Moves selected ready customer payments back to DELIVERED, clears billing packet/payment amounts, and releases linked customer pay rows in one AR workflow.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerPaymentIds` | array<string> | Yes | Visible READY customer payment IDs to move back to DELIVERED. | min items: 1; max items: 100 |
| `customerPaymentIds[]` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/customer-payments/back-to-delivered' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "customerPaymentIds": [
    "<customerPaymentIds>"
  ]
}'
```

#### Success response shape

Moved customer payments back to delivered

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | MoveCustomerPaymentsBackToDeliveredResult | Yes | - | - |
| `data.customerPaymentIds` | array<string> | Yes | - | - |
| `data.customerPaymentIds[]` | string | Yes | - | format: uuid |
| `data.updatedCount` | integer | Yes | - | - |
| `data.payments` | array<object> | Yes | - | - |
| `data.payments[]` | object | Yes | - | - |
| `data.payments[].customerPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | format: uuid |
| `data.payments[].loadNumber` | string | Yes | - | - |
| `data.payments[].status` | string | Yes | - | one of: DELIVERED |
| `data.customerPayRowsReleased` | integer | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/billing/customer-payments/record

`ark.record_customer_payments`

Records selected invoiced or factored customer payments as paid in one AR workflow, with optional QuickBooks customer payment sync.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerPaymentIds` | array<string> | Yes | Visible INVOICED or FACTORED customer payment IDs to mark PAID. | min items: 1; max items: 100 |
| `customerPaymentIds[]` | string | Yes | - | format: uuid |
| `referenceNumber` | string \| null | No | Optional payment reference number applied to every selected payment. | max length: 100 |
| `paidDate` | string | Yes | Payment date in YYYY-MM-DD format. | - |
| `queueQuickBooksSync` | boolean | No | - | default: false |
| `depositToAccountId` | string | No | - | max length: 100 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/customer-payments/record' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "customerPaymentIds": [
    "<customerPaymentIds>"
  ],
  "paidDate": "<paidDate>"
}'
```

#### Success response shape

Recorded customer payments

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RecordCustomerPaymentsResult | Yes | - | - |
| `data.customerPaymentIds` | array<string> | Yes | - | - |
| `data.customerPaymentIds[]` | string | Yes | - | format: uuid |
| `data.paidDate` | string | Yes | - | format: date |
| `data.referenceNumber` | string \| null | Yes | - | - |
| `data.updatedCount` | integer | Yes | - | - |
| `data.payments` | array<object> | Yes | - | - |
| `data.payments[]` | object | Yes | - | - |
| `data.payments[].customerPaymentId` | string | Yes | - | format: uuid |
| `data.payments[].loadId` | string | Yes | - | format: uuid |
| `data.payments[].loadNumber` | string | Yes | - | - |
| `data.payments[].status` | string | Yes | - | one of: PAID |
| `data.payments[].paidDate` | string | Yes | - | format: date |
| `data.payments[].referenceNumber` | string \| null | Yes | - | - |
| `data.payments[].paymentAmount` | string \| null | Yes | - | - |
| `data.quickBooksSync` | QuickBooksSyncSummary | Yes | - | - |
| `data.quickBooksSync.requested` | boolean | Yes | - | - |
| `data.quickBooksSync.queued` | boolean | Yes | - | - |
| `data.quickBooksSync.status` | string \| null | Yes | - | - |
| `data.quickBooksSync.jobId` | string \| null | Yes | - | format: uuid |
| `data.quickBooksSync.error` | string \| null | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/billing/customer-payments/send-invoices

`ark.send_customer_invoices`

Sends selected ready customer invoice emails in one AR workflow, marks successful customer payments invoiced, returns per-payment failures, and can optionally queue QuickBooks invoice sync.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerPaymentIds` | array<string> | Yes | Visible READY customer payment IDs whose invoice emails should be sent in one AR workflow. | min items: 1; max items: 100 |
| `customerPaymentIds[]` | string | Yes | - | format: uuid |
| `queueQuickBooksSync` | boolean | No | Queue QuickBooks customer invoice sync after each successful invoice email. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/customer-payments/send-invoices' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "customerPaymentIds": [
    "<customerPaymentIds>"
  ]
}'
```

#### Success response shape

Sent customer invoices

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SendCustomerInvoicesResult | Yes | - | - |
| `data.customerPaymentIds` | array<string> | Yes | - | - |
| `data.customerPaymentIds[]` | string | Yes | - | format: uuid |
| `data.requestedCount` | integer | Yes | - | min: 0 |
| `data.sentCount` | integer | Yes | - | min: 0 |
| `data.failedCount` | integer | Yes | - | min: 0 |
| `data.invoices` | array<object> | Yes | - | - |
| `data.invoices[]` | object | Yes | - | - |
| `data.invoices[].customerPaymentId` | string | Yes | - | format: uuid |
| `data.invoices[].loadId` | string | Yes | - | format: uuid |
| `data.invoices[].loadNumber` | string | Yes | - | - |
| `data.invoices[].status` | string | Yes | - | one of: INVOICED |
| `data.invoices[].deliveryMode` | string | Yes | - | one of: direct, queued |
| `data.invoices[].recipientMode` | string | Yes | - | one of: customer_billing, remit_profile |
| `data.invoices[].recipientEmail` | string | Yes | - | format: email |
| `data.invoices[].sentAt` | string | Yes | - | format: date-time |
| `data.invoices[].quickBooksSync` | SendCustomerInvoiceQuickBooksSync | Yes | - | - |
| `data.invoices[].quickBooksSync.requested` | boolean | Yes | - | - |
| `data.invoices[].quickBooksSync.queued` | boolean | Yes | - | - |
| `data.invoices[].quickBooksSync.status` | string \| null | Yes | - | - |
| `data.invoices[].quickBooksSync.jobId` | string \| null | Yes | - | format: uuid |
| `data.invoices[].quickBooksSync.error` | string \| null | Yes | - | - |
| `data.invoices[].sideEffectError` | string \| null | Yes | - | - |
| `data.failures` | array<object> | Yes | - | - |
| `data.failures[]` | object | Yes | - | - |
| `data.failures[].customerPaymentId` | string | Yes | - | format: uuid |
| `data.failures[].loadId` | string \| null | Yes | - | format: uuid |
| `data.failures[].loadNumber` | string \| null | Yes | - | - |
| `data.failures[].code` | string | Yes | - | - |
| `data.failures[].message` | string | Yes | - | - |
| `data.failures[].status` | integer | Yes | - | - |
| `data.failures[].details` | unknown | No | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### GET /api/v1/billing/invoice-remit-profiles

`ark.list_invoice_remit_profiles`

Lists organization invoice remit profiles with default status, routing mode, remit email, address, and version snapshot context.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.include_inactive` | boolean | No | Include deactivated remit profiles for historical review. | default: false |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/invoice-remit-profiles' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Invoice remit profiles

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.profiles` | array<InvoiceRemitProfile> | Yes | - | - |
| `data.profiles[]` | InvoiceRemitProfile | Yes | - | - |
| `data.profiles[].id` | string | Yes | - | format: uuid |
| `data.profiles[].organizationId` | string | Yes | - | format: uuid |
| `data.profiles[].type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profiles[].name` | string | Yes | - | - |
| `data.profiles[].billingAddressId` | string \| null | Yes | - | format: uuid |
| `data.profiles[].billingAddress` | InvoiceRemitAddress \| null | Yes | - | - |
| `data.profiles[].remitEmail` | string \| null | Yes | - | format: email |
| `data.profiles[].invoiceInstructions` | string \| null | Yes | - | - |
| `data.profiles[].sendToRemitEmail` | boolean | Yes | - | - |
| `data.profiles[].active` | boolean | Yes | - | - |
| `data.profiles[].deletedAt` | string \| null | Yes | - | format: date-time |
| `data.profiles[].versionNumber` | integer | Yes | - | min: 1 |
| `data.profiles[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.profiles[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.profiles[].isDefault` | boolean | Yes | - | - |
| `data.profiles[].snapshot` | InvoiceRemitProfilePublicSnapshot | Yes | - | - |
| `data.profiles[].snapshot.id` | string | Yes | - | format: uuid |
| `data.profiles[].snapshot.organizationId` | string | Yes | - | format: uuid |
| `data.profiles[].snapshot.versionNumber` | integer | Yes | - | min: 1 |
| `data.profiles[].snapshot.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profiles[].snapshot.name` | string | Yes | - | - |
| `data.profiles[].snapshot.remitEmail` | string \| null | No | - | format: email |
| `data.profiles[].snapshot.sendToRemitEmail` | boolean | Yes | - | - |
| `data.profiles[].snapshot.invoiceInstructions` | string \| null | No | - | - |
| `data.profiles[].snapshot.address` | InvoiceRemitAddress \| null | No | - | - |
| `data.defaultProfileId` | string \| null | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/billing/invoice-remit-profiles

`ark.create_invoice_remit_profile`

Creates an organization invoice remit profile. Factoring and send-to-remit profiles require remitEmail.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `name` | string | Yes | - | min length: 1; max length: 200 |
| `remitEmail` | string \| null | No | - | format: email; max length: 500 |
| `invoiceInstructions` | string \| null | No | - | max length: 5000 |
| `sendToRemitEmail` | boolean | No | - | - |
| `billingAddress` | InvoiceRemitAddress \| null | No | - | - |
| `setAsDefault` | boolean | No | - | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/invoice-remit-profiles' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "standard",
  "name": "<name>"
}'
```

#### Success response shape

Created invoice remit profile

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.profile` | InvoiceRemitProfile | Yes | - | - |
| `data.profile.id` | string | Yes | - | format: uuid |
| `data.profile.organizationId` | string | Yes | - | format: uuid |
| `data.profile.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profile.name` | string | Yes | - | - |
| `data.profile.billingAddressId` | string \| null | Yes | - | format: uuid |
| `data.profile.billingAddress` | InvoiceRemitAddress \| null | Yes | - | - |
| `data.profile.remitEmail` | string \| null | Yes | - | format: email |
| `data.profile.invoiceInstructions` | string \| null | Yes | - | - |
| `data.profile.sendToRemitEmail` | boolean | Yes | - | - |
| `data.profile.active` | boolean | Yes | - | - |
| `data.profile.deletedAt` | string \| null | Yes | - | format: date-time |
| `data.profile.versionNumber` | integer | Yes | - | min: 1 |
| `data.profile.createdAt` | string \| null | Yes | - | format: date-time |
| `data.profile.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.profile.isDefault` | boolean | Yes | - | - |
| `data.profile.snapshot` | InvoiceRemitProfilePublicSnapshot | Yes | - | - |
| `data.profile.snapshot.id` | string | Yes | - | format: uuid |
| `data.profile.snapshot.organizationId` | string | Yes | - | format: uuid |
| `data.profile.snapshot.versionNumber` | integer | Yes | - | min: 1 |
| `data.profile.snapshot.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profile.snapshot.name` | string | Yes | - | - |
| `data.profile.snapshot.remitEmail` | string \| null | No | - | format: email |
| `data.profile.snapshot.sendToRemitEmail` | boolean | Yes | - | - |
| `data.profile.snapshot.invoiceInstructions` | string \| null | No | - | - |
| `data.profile.snapshot.address` | InvoiceRemitAddress \| null | No | - | - |
| `data.defaultProfileId` | string \| null | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### DELETE /api/v1/billing/invoice-remit-profiles/{profileId}

`ark.deactivate_invoice_remit_profile`

Deactivates a non-default organization invoice remit profile while preserving historical invoice snapshots.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.profileId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/billing/invoice-remit-profiles/<profileId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deactivated invoice remit profile

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.success` | unknown | Yes | - | - |
| `data.profile` | InvoiceRemitProfile | Yes | - | - |
| `data.profile.id` | string | Yes | - | format: uuid |
| `data.profile.organizationId` | string | Yes | - | format: uuid |
| `data.profile.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profile.name` | string | Yes | - | - |
| `data.profile.billingAddressId` | string \| null | Yes | - | format: uuid |
| `data.profile.billingAddress` | InvoiceRemitAddress \| null | Yes | - | - |
| `data.profile.remitEmail` | string \| null | Yes | - | format: email |
| `data.profile.invoiceInstructions` | string \| null | Yes | - | - |
| `data.profile.sendToRemitEmail` | boolean | Yes | - | - |
| `data.profile.active` | boolean | Yes | - | - |
| `data.profile.deletedAt` | string \| null | Yes | - | format: date-time |
| `data.profile.versionNumber` | integer | Yes | - | min: 1 |
| `data.profile.createdAt` | string \| null | Yes | - | format: date-time |
| `data.profile.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.profile.isDefault` | boolean | Yes | - | - |
| `data.profile.snapshot` | InvoiceRemitProfilePublicSnapshot | Yes | - | - |
| `data.profile.snapshot.id` | string | Yes | - | format: uuid |
| `data.profile.snapshot.organizationId` | string | Yes | - | format: uuid |
| `data.profile.snapshot.versionNumber` | integer | Yes | - | min: 1 |
| `data.profile.snapshot.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profile.snapshot.name` | string | Yes | - | - |
| `data.profile.snapshot.remitEmail` | string \| null | No | - | format: email |
| `data.profile.snapshot.sendToRemitEmail` | boolean | Yes | - | - |
| `data.profile.snapshot.invoiceInstructions` | string \| null | No | - | - |
| `data.profile.snapshot.address` | InvoiceRemitAddress \| null | No | - | - |
| `data.defaultProfileId` | string \| null | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### PATCH /api/v1/billing/invoice-remit-profiles/{profileId}

`ark.update_invoice_remit_profile`

Updates an organization invoice remit profile and creates the next profile version for future invoice snapshots.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.profileId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `type` | string | No | - | one of: standard, factoring, subsidiary, other |
| `name` | string | No | - | min length: 1; max length: 200 |
| `remitEmail` | string \| null | No | - | format: email; max length: 500 |
| `invoiceInstructions` | string \| null | No | - | max length: 5000 |
| `sendToRemitEmail` | boolean | No | - | - |
| `billingAddress` | InvoiceRemitAddress \| null | No | - | - |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/billing/invoice-remit-profiles/<profileId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated invoice remit profile

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.profile` | InvoiceRemitProfile | Yes | - | - |
| `data.profile.id` | string | Yes | - | format: uuid |
| `data.profile.organizationId` | string | Yes | - | format: uuid |
| `data.profile.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profile.name` | string | Yes | - | - |
| `data.profile.billingAddressId` | string \| null | Yes | - | format: uuid |
| `data.profile.billingAddress` | InvoiceRemitAddress \| null | Yes | - | - |
| `data.profile.remitEmail` | string \| null | Yes | - | format: email |
| `data.profile.invoiceInstructions` | string \| null | Yes | - | - |
| `data.profile.sendToRemitEmail` | boolean | Yes | - | - |
| `data.profile.active` | boolean | Yes | - | - |
| `data.profile.deletedAt` | string \| null | Yes | - | format: date-time |
| `data.profile.versionNumber` | integer | Yes | - | min: 1 |
| `data.profile.createdAt` | string \| null | Yes | - | format: date-time |
| `data.profile.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.profile.isDefault` | boolean | Yes | - | - |
| `data.profile.snapshot` | InvoiceRemitProfilePublicSnapshot | Yes | - | - |
| `data.profile.snapshot.id` | string | Yes | - | format: uuid |
| `data.profile.snapshot.organizationId` | string | Yes | - | format: uuid |
| `data.profile.snapshot.versionNumber` | integer | Yes | - | min: 1 |
| `data.profile.snapshot.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profile.snapshot.name` | string | Yes | - | - |
| `data.profile.snapshot.remitEmail` | string \| null | No | - | format: email |
| `data.profile.snapshot.sendToRemitEmail` | boolean | Yes | - | - |
| `data.profile.snapshot.invoiceInstructions` | string \| null | No | - | - |
| `data.profile.snapshot.address` | InvoiceRemitAddress \| null | No | - | - |
| `data.defaultProfileId` | string \| null | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/billing/invoice-remit-profiles/{profileId}/default

`ark.set_default_invoice_remit_profile`

Sets the organization default invoice remit profile used when a customer does not have a customer-specific remit default.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.profileId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/invoice-remit-profiles/<profileId>/default' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Default invoice remit profile

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.success` | unknown | Yes | - | - |
| `data.defaultProfileId` | string | Yes | - | format: uuid |
| `data.previousDefaultProfileId` | string \| null | Yes | - | format: uuid |
| `data.profile` | object | Yes | - | - |
| `data.profile.id` | string | Yes | - | format: uuid |
| `data.profile.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.profile.name` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/billing/organization-ach

`ark.get_organization_ach_settings`

Returns organization ACH originator settings for billing users. Tax, bank, routing, and NACHA credentials are always masked on the external API.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/organization-ach' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Organization ACH settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | OrganizationAchSettingsPayload | Yes | - | - |
| `data.organizationId` | string | Yes | - | format: uuid |
| `data.organizationName` | string \| null | Yes | - | - |
| `data.bankName` | string \| null | Yes | - | - |
| `data.bankAccountName` | string \| null | Yes | - | - |
| `data.sensitiveFieldsIncluded` | boolean | Yes | - | - |
| `data.federalTaxId` | null | Yes | - | - |
| `data.bankAccountNumber` | null | Yes | - | - |
| `data.bankRoutingNumber` | null | Yes | - | - |
| `data.nachaDiscretionaryData` | null | Yes | - | - |
| `data.nachaCompanyId` | null | Yes | - | - |
| `data.masked` | OrganizationAchSettingsMasked | Yes | - | - |
| `data.masked.federalTaxIdPresent` | boolean | Yes | - | - |
| `data.masked.bankAccountNumberLast4` | string \| null | Yes | - | - |
| `data.masked.bankRoutingNumberLast4` | string \| null | Yes | - | - |
| `data.masked.nachaDiscretionaryDataPresent` | boolean | Yes | - | - |
| `data.masked.nachaCompanyIdPresent` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### GET /api/v1/billing/pay-holds

`ark.list_pay_holds`

Lists visible active or resolved pay holds and claims with load, customer, value, note, and creator context.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `one of: canViewBilling`, `one of: canViewPayHoldsReport`, `one of: canEditLoad`, `one of: canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | string | No | - | one of: active, resolved, all; default: "active" |
| `query.claim_type` | string | No | - | one of: claim, hold, all; default: "all" |
| `query.value_from` | number | No | - | min: 0 |
| `query.value_to` | number | No | - | min: 0 |
| `query.load_number_from` | number | No | - | min: 0 |
| `query.load_number_to` | number | No | - | min: 0 |
| `query.created_by` | string | No | - | format: uuid |
| `query.currency` | string | No | - | one of: USD, CAD, MXN |
| `query.search` | string | No | Search across load number, customer, notes, pickup number, PO, BOL, creator name, and creator email. | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/pay-holds' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Pay holds

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.payHolds` | array<PayHoldListItem> | Yes | - | - |
| `data.payHolds[]` | PayHoldListItem | Yes | - | - |
| `data.payHolds[].payHoldId` | string | Yes | - | format: uuid |
| `data.payHolds[].loadId` | string | Yes | - | - |
| `data.payHolds[].loadNumber` | number \| null | Yes | - | - |
| `data.payHolds[].customerId` | string \| null | Yes | - | format: uuid |
| `data.payHolds[].customerName` | string \| null | Yes | - | - |
| `data.payHolds[].status` | string | Yes | - | one of: active, resolved |
| `data.payHolds[].value` | string \| null | Yes | Decimal pay hold or claim value as a string. | - |
| `data.payHolds[].currency` | string | Yes | - | - |
| `data.payHolds[].notes` | string \| null | Yes | - | - |
| `data.payHolds[].isClaim` | boolean | Yes | - | - |
| `data.payHolds[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.payHolds[].createdBy` | string \| null | Yes | - | format: uuid |
| `data.payHolds[].createdByName` | string \| null | Yes | - | - |
| `data.payHolds[].resolvedAt` | string \| null | Yes | - | format: date-time |
| `data.payHolds[].resolvedBy` | string \| null | Yes | - | format: uuid |
| `data.payHolds[].pickupNumber` | string \| null | Yes | - | - |
| `data.payHolds[].purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.payHolds[].billOfLading` | string \| null | Yes | - | - |
| `data.pagination` | PayHoldListPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/billing/pay-holds/bulk-resolve

`ark.bulk_resolve_pay_holds`

Resolves multiple active visible pay holds or claims in one batch, returning per-hold outcomes for report cleanup workflows.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canMakeAdjustments`, `one of: canViewBilling`, `one of: canViewPayHoldsReport`, `one of: canEditLoad`, `one of: canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `payHoldIds` | array<string> | Yes | Active visible pay hold IDs to resolve in one batch. | min items: 1; max items: 100 |
| `payHoldIds[]` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/pay-holds/bulk-resolve' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "payHoldIds": [
    "<payHoldIds>"
  ]
}'
```

#### Success response shape

Bulk pay hold resolution outcomes

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.results` | array<BulkResolvePayHoldResult> | Yes | - | - |
| `data.results[]` | BulkResolvePayHoldResult | Yes | - | - |
| `data.results[].payHoldId` | string | Yes | - | format: uuid |
| `data.results[].status` | string | Yes | - | one of: resolved, error |
| `data.results[].code` | string \| null | Yes | - | one of: not_found, access_denied, already_resolved, null |
| `data.results[].message` | string | Yes | - | - |
| `data.results[].loadId` | string \| null | Yes | - | format: uuid |
| `data.results[].resolvedAt` | string \| null | Yes | - | format: date-time |
| `data.successCount` | integer | Yes | - | min: 0 |
| `data.errorCount` | integer | Yes | - | min: 0 |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 422 | Invalid request |

### GET /api/v1/billing/payment-destinations

`ark.list_payment_destinations`

Returns carrier and factoring payment destination details for billing workflows. Bank and tax credentials are always masked on the external API.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.carrier_ids` | string | No | Comma-separated carrier IDs. | - |
| `query.factoring_company_ids` | string | No | Comma-separated factoring company IDs. | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/payment-destinations' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

OK

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.includeSensitivePaymentFields` | boolean | Yes | - | - |
| `data.items` | array<PaymentDestination> | Yes | - | - |
| `data.items[]` | PaymentDestination | Yes | - | - |
| `data.items[].kind` | string | Yes | - | one of: carrier, factoring_company |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].displayName` | string \| null | Yes | - | - |
| `data.items[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.items[].carrierName` | string \| null | Yes | - | - |
| `data.items[].factoringCompanyId` | string \| null | Yes | - | format: uuid |
| `data.items[].factoringCompanyName` | string \| null | Yes | - | - |
| `data.items[].bankName` | string \| null | Yes | - | - |
| `data.items[].bankType` | string \| null | Yes | - | - |
| `data.items[].bankAccountNum` | null | Yes | - | - |
| `data.items[].bankRoutingNum` | null | Yes | - | - |
| `data.items[].federalTaxId` | null | Yes | - | - |
| `data.items[].masked` | object | Yes | - | - |
| `data.items[].masked.bankAccountLast4` | string \| null | Yes | - | - |
| `data.items[].masked.bankRoutingLast4` | string \| null | Yes | - | - |
| `data.items[].masked.federalTaxIdLast4` | string \| null | Yes | - | - |
| `data.items[].sensitiveFields` | object | Yes | - | - |
| `data.items[].sensitiveFields.bankAccountNumSet` | boolean | Yes | - | - |
| `data.items[].sensitiveFields.bankRoutingNumSet` | boolean | Yes | - | - |
| `data.items[].sensitiveFields.federalTaxIdSet` | boolean | Yes | - | - |
| `data.missing` | object | Yes | - | - |
| `data.missing.carrierIds` | array<string> | Yes | - | - |
| `data.missing.carrierIds[]` | string | Yes | - | format: uuid |
| `data.missing.factoringCompanyIds` | array<string> | Yes | - | - |
| `data.missing.factoringCompanyIds[]` | string | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/billing/payment-terms

`ark.list_payment_terms`

Lists organization payment terms used by customer, carrier, and factoring payment routing.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.include_deleted` | boolean | No | Include archived payment terms. | default: false |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/billing/payment-terms' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Payment terms

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.terms` | array<PaymentTerm> | Yes | - | - |
| `data.terms[]` | PaymentTerm | Yes | - | - |
| `data.terms[].id` | string | Yes | - | format: uuid |
| `data.terms[].days` | integer \| null | Yes | - | - |
| `data.terms[].discount` | number \| null | Yes | - | - |
| `data.terms[].quickbooksTermId` | string \| null | Yes | - | - |
| `data.terms[].deletedAt` | string \| null | Yes | - | format: date-time |
| `data.terms[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.terms[].modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/billing/payment-terms

`ark.create_payment_term`

Creates an organization payment term that can be assigned to customers, carriers, or factoring companies.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `days` | integer | Yes | - | min: 1; max: 365 |
| `discount` | number | No | - | default: 0; min: 0; max: 100 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/billing/payment-terms' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "days": 1
}'
```

#### Success response shape

Created payment term

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.term` | PaymentTerm | Yes | - | - |
| `data.term.id` | string | Yes | - | format: uuid |
| `data.term.days` | integer \| null | Yes | - | - |
| `data.term.discount` | number \| null | Yes | - | - |
| `data.term.quickbooksTermId` | string \| null | Yes | - | - |
| `data.term.deletedAt` | string \| null | Yes | - | format: date-time |
| `data.term.createdAt` | string \| null | Yes | - | format: date-time |
| `data.term.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### DELETE /api/v1/billing/payment-terms/{paymentTermId}

`ark.archive_payment_term`

Archives an organization payment term by setting deleted_at, matching the website payment term delete action.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.paymentTermId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/billing/payment-terms/<paymentTermId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Archived payment term

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.term` | PaymentTerm | Yes | - | - |
| `data.term.id` | string | Yes | - | format: uuid |
| `data.term.days` | integer \| null | Yes | - | - |
| `data.term.discount` | number \| null | Yes | - | - |
| `data.term.quickbooksTermId` | string \| null | Yes | - | - |
| `data.term.deletedAt` | string \| null | Yes | - | format: date-time |
| `data.term.createdAt` | string \| null | Yes | - | format: date-time |
| `data.term.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.archived` | unknown | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/carrier-invites

`ark.list_carrier_invites`

Lists carrier onboarding invites for the organization with status, DOT, email, expiration, submission, and linked-carrier state.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canInviteCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | CarrierInviteStatusFilter | No | - | - |
| `query.query` | string | No | - | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carrier-invites' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier invites

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.invites` | array<CarrierInviteSummary> | Yes | - | - |
| `data.invites[]` | CarrierInviteSummary | Yes | - | - |
| `data.invites[].id` | string | Yes | - | format: uuid |
| `data.invites[].email` | string | Yes | - | format: email |
| `data.invites[].dotNumber` | string | Yes | - | - |
| `data.invites[].mcNumber` | string \| null | Yes | - | - |
| `data.invites[].legalName` | string | Yes | - | - |
| `data.invites[].status` | string | Yes | - | - |
| `data.invites[].createdAt` | string | Yes | - | format: date-time |
| `data.invites[].expiresAt` | string | Yes | - | format: date-time |
| `data.invites[].emailSentAt` | string \| null | Yes | - | format: date-time |
| `data.invites[].emailResentCount` | integer | Yes | - | - |
| `data.invites[].lastAccessedAt` | string \| null | Yes | - | format: date-time |
| `data.invites[].submittedAt` | string \| null | Yes | - | format: date-time |
| `data.invites[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.pagination` | CarrierInvitePagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/carrier-invites

`ark.create_carrier_invite`

Creates a carrier onboarding invite from FMCSA DOT data, sends the invite email, and records the pending invite.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canInviteCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `email` | string | Yes | - | format: email; max length: 254 |
| `dotNumber` | string | Yes | - | min length: 1; max length: 20 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carrier-invites' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "<email>",
  "dotNumber": "<dotNumber>"
}'
```

#### Success response shape

Created carrier invite

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.invite` | CarrierInviteSummary | Yes | - | - |
| `data.invite.id` | string | Yes | - | format: uuid |
| `data.invite.email` | string | Yes | - | format: email |
| `data.invite.dotNumber` | string | Yes | - | - |
| `data.invite.mcNumber` | string \| null | Yes | - | - |
| `data.invite.legalName` | string | Yes | - | - |
| `data.invite.status` | string | Yes | - | - |
| `data.invite.createdAt` | string | Yes | - | format: date-time |
| `data.invite.expiresAt` | string | Yes | - | format: date-time |
| `data.invite.emailSentAt` | string \| null | Yes | - | format: date-time |
| `data.invite.emailResentCount` | integer | Yes | - | - |
| `data.invite.lastAccessedAt` | string \| null | Yes | - | format: date-time |
| `data.invite.submittedAt` | string \| null | Yes | - | format: date-time |
| `data.invite.carrierId` | string \| null | Yes | - | format: uuid |
| `data.emailSentAt` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### DELETE /api/v1/carrier-invites/{inviteId}

`ark.cancel_carrier_invite`

Cancels a pending carrier onboarding invite and removes pending invite uploads when available.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canInviteCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.inviteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/carrier-invites/<inviteId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Cancelled carrier invite

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.invite` | CarrierInviteSummary | Yes | - | - |
| `data.invite.id` | string | Yes | - | format: uuid |
| `data.invite.email` | string | Yes | - | format: email |
| `data.invite.dotNumber` | string | Yes | - | - |
| `data.invite.mcNumber` | string \| null | Yes | - | - |
| `data.invite.legalName` | string | Yes | - | - |
| `data.invite.status` | string | Yes | - | - |
| `data.invite.createdAt` | string | Yes | - | format: date-time |
| `data.invite.expiresAt` | string | Yes | - | format: date-time |
| `data.invite.emailSentAt` | string \| null | Yes | - | format: date-time |
| `data.invite.emailResentCount` | integer | Yes | - | - |
| `data.invite.lastAccessedAt` | string \| null | Yes | - | format: date-time |
| `data.invite.submittedAt` | string \| null | Yes | - | format: date-time |
| `data.invite.carrierId` | string \| null | Yes | - | format: uuid |
| `data.storageCleanup` | CancelCarrierInviteStorageCleanup | Yes | - | - |
| `data.storageCleanup.deletedFileCount` | integer | Yes | - | - |
| `data.storageCleanup.warning` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/carrier-invites/{inviteId}/resend

`ark.resend_carrier_invite`

Resends a pending carrier onboarding invite email and extends the invite expiration window.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canInviteCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.inviteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carrier-invites/<inviteId>/resend' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Resent carrier invite

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.invite` | CarrierInviteSummary | Yes | - | - |
| `data.invite.id` | string | Yes | - | format: uuid |
| `data.invite.email` | string | Yes | - | format: email |
| `data.invite.dotNumber` | string | Yes | - | - |
| `data.invite.mcNumber` | string \| null | Yes | - | - |
| `data.invite.legalName` | string | Yes | - | - |
| `data.invite.status` | string | Yes | - | - |
| `data.invite.createdAt` | string | Yes | - | format: date-time |
| `data.invite.expiresAt` | string | Yes | - | format: date-time |
| `data.invite.emailSentAt` | string \| null | Yes | - | format: date-time |
| `data.invite.emailResentCount` | integer | Yes | - | - |
| `data.invite.lastAccessedAt` | string \| null | Yes | - | format: date-time |
| `data.invite.submittedAt` | string \| null | Yes | - | format: date-time |
| `data.invite.carrierId` | string \| null | Yes | - | format: uuid |
| `data.expiresAt` | string | Yes | - | format: date-time |
| `data.resendCount` | integer | Yes | - | - |
| `data.emailSentAt` | string | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### POST /api/v1/carrier-invites/preview

`ark.preview_carrier_invite`

Looks up FMCSA carrier details and existing ARK carrier or pending invite conflicts before sending an onboarding invite.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canInviteCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `dotNumber` | string | Yes | - | min length: 1; max length: 20 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carrier-invites/preview' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "dotNumber": "<dotNumber>"
}'
```

#### Success response shape

Carrier invite preview

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.fmcsa` | CarrierInviteFmcsaSummary | Yes | - | - |
| `data.fmcsa.legalName` | string | Yes | - | - |
| `data.fmcsa.dbaName` | string \| null | Yes | - | - |
| `data.fmcsa.dotNumber` | string | Yes | - | - |
| `data.fmcsa.mcNumber` | string \| null | Yes | - | - |
| `data.fmcsa.address` | string \| null | Yes | - | - |
| `data.fmcsa.city` | string \| null | Yes | - | - |
| `data.fmcsa.state` | string \| null | Yes | - | - |
| `data.fmcsa.zip` | string \| null | Yes | - | - |
| `data.fmcsa.phone` | string \| null | Yes | - | - |
| `data.fmcsa.brokerAuthority` | boolean | Yes | - | - |
| `data.fmcsa.commonAuthority` | boolean | Yes | - | - |
| `data.fmcsa.contractAuthority` | boolean | Yes | - | - |
| `data.existingCarrier` | object \| null | Yes | - | - |
| `data.pendingInvite` | object \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### GET /api/v1/carriers

`ark.search_carriers`

Searches organization carriers by name, DBA, DOT, MC, SCAC, code, and dispatch contact.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | No | - | min length: 1; max length: 100 |
| `query.active` | boolean | No | - | - |
| `query.include_do_not_use` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier search results

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.items` | array<object> | Yes | - | - |
| `data.items[]` | object | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].name` | string \| null | Yes | - | - |
| `data.items[].dbaName` | string \| null | Yes | - | - |
| `data.items[].code` | string \| null | Yes | - | - |
| `data.items[].dotNum` | string \| null | Yes | - | - |
| `data.items[].mcNum` | string \| null | Yes | - | - |
| `data.items[].dispatchEmail` | string \| null | No | - | - |
| `data.items[].dispatchPhone` | string \| null | No | - | - |
| `data.items[].active` | boolean | Yes | - | - |
| `data.items[].doNotUse` | boolean | Yes | - | - |
| `data.items[].domicileCountry` | string | Yes | - | - |
| `data.items[].operatingCountries` | array<string> | Yes | - | - |
| `data.items[].operatingCountries[]` | string | Yes | - | - |
| `data.items[].scac` | string \| null | No | - | - |
| `data.items[].defaultCurrency` | string | Yes | - | - |
| `data.items[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.items[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.items[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.pagination` | CursorPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/carriers

`ark.create_carrier`

Creates an organization carrier profile.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canCreateCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `active` | boolean | No | - | default: true |
| `doNotUse` | boolean | No | - | default: false |
| `name` | string | Yes | - | min length: 1; max length: 200 |
| `dbaName` | string \| null | No | - | max length: 200 |
| `code` | string \| null | No | - | max length: 50 |
| `notes` | string \| null | No | - | max length: 5000 |
| `dotNum` | string \| null | No | - | max length: 30 |
| `mcNum` | string \| null | No | - | max length: 30 |
| `dispatchEmail` | string \| null | No | - | max length: 500 |
| `dispatchPhone` | string \| null | No | - | max length: 50 |
| `domicileCountry` | string | No | - | one of: USA, CAN, MEX; default: "USA" |
| `operatingCountries` | array<string> | No | - | min items: 1; max items: 3 |
| `operatingCountries[]` | string | No | - | one of: USA, CAN, MEX |
| `scac` | string \| null | No | - | max length: 30 |
| `caat` | string \| null | No | - | max length: 100 |
| `sctPermit` | string \| null | No | - | max length: 100 |
| `nscNumber` | string \| null | No | - | max length: 100 |
| `nscProvince` | string \| null | No | - | max length: 100 |
| `gstHstNumber` | string \| null | No | - | max length: 100 |
| `defaultCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "<name>"
}'
```

#### Success response shape

Created carrier

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Carrier | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.dbaName` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.code` | string \| null | Yes | - | - |
| `data.dotNum` | string \| null | Yes | - | - |
| `data.mcNum` | string \| null | Yes | - | - |
| `data.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.dispatchEmail` | string \| null | Yes | - | - |
| `data.dispatchPhone` | string \| null | Yes | - | - |
| `data.active` | boolean | Yes | - | - |
| `data.doNotUse` | boolean | Yes | - | - |
| `data.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.operatingCountries` | array<string> | Yes | - | - |
| `data.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.scac` | string \| null | Yes | - | - |
| `data.caat` | string \| null | Yes | - | - |
| `data.sctPermit` | string \| null | Yes | - | - |
| `data.nscNumber` | string \| null | Yes | - | - |
| `data.nscProvince` | string \| null | Yes | - | - |
| `data.gstHstNumber` | string \| null | Yes | - | - |
| `data.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.paymentMethod` | string \| null | Yes | - | - |
| `data.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.factoringId` | string \| null | Yes | - | format: uuid |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### DELETE /api/v1/carriers/{carrierId}

`ark.delete_carrier`

Soft-deletes an organization carrier profile.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canDeleteCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/carriers/<carrierId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deleted carrier

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.deleted` | unknown | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/carriers/{carrierId}

`ark.get_carrier`

Returns one organization carrier by ID.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Get carrier

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Carrier | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.dbaName` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.code` | string \| null | Yes | - | - |
| `data.dotNum` | string \| null | Yes | - | - |
| `data.mcNum` | string \| null | Yes | - | - |
| `data.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.dispatchEmail` | string \| null | Yes | - | - |
| `data.dispatchPhone` | string \| null | Yes | - | - |
| `data.active` | boolean | Yes | - | - |
| `data.doNotUse` | boolean | Yes | - | - |
| `data.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.operatingCountries` | array<string> | Yes | - | - |
| `data.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.scac` | string \| null | Yes | - | - |
| `data.caat` | string \| null | Yes | - | - |
| `data.sctPermit` | string \| null | Yes | - | - |
| `data.nscNumber` | string \| null | Yes | - | - |
| `data.nscProvince` | string \| null | Yes | - | - |
| `data.gstHstNumber` | string \| null | Yes | - | - |
| `data.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.paymentMethod` | string \| null | Yes | - | - |
| `data.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.factoringId` | string \| null | Yes | - | format: uuid |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/carriers/{carrierId}

`ark.update_carrier`

Updates an organization carrier profile.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canEditCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `name` | string | No | - | min length: 1; max length: 200 |
| `dbaName` | string \| null | No | - | max length: 200 |
| `code` | string \| null | No | - | max length: 50 |
| `notes` | string \| null | No | - | max length: 5000 |
| `dotNum` | string \| null | No | - | max length: 30 |
| `mcNum` | string \| null | No | - | max length: 30 |
| `dispatchEmail` | string \| null | No | - | max length: 500 |
| `dispatchPhone` | string \| null | No | - | max length: 50 |
| `domicileCountry` | string | No | - | one of: USA, CAN, MEX; default: "USA" |
| `operatingCountries` | array<string> | No | - | min items: 1; max items: 3 |
| `operatingCountries[]` | string | No | - | one of: USA, CAN, MEX |
| `scac` | string \| null | No | - | max length: 30 |
| `caat` | string \| null | No | - | max length: 100 |
| `sctPermit` | string \| null | No | - | max length: 100 |
| `nscNumber` | string \| null | No | - | max length: 100 |
| `nscProvince` | string \| null | No | - | max length: 100 |
| `gstHstNumber` | string \| null | No | - | max length: 100 |
| `defaultCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/carriers/<carrierId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated carrier

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Carrier | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.dbaName` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.code` | string \| null | Yes | - | - |
| `data.dotNum` | string \| null | Yes | - | - |
| `data.mcNum` | string \| null | Yes | - | - |
| `data.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.dispatchEmail` | string \| null | Yes | - | - |
| `data.dispatchPhone` | string \| null | Yes | - | - |
| `data.active` | boolean | Yes | - | - |
| `data.doNotUse` | boolean | Yes | - | - |
| `data.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.operatingCountries` | array<string> | Yes | - | - |
| `data.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.scac` | string \| null | Yes | - | - |
| `data.caat` | string \| null | Yes | - | - |
| `data.sctPermit` | string \| null | Yes | - | - |
| `data.nscNumber` | string \| null | Yes | - | - |
| `data.nscProvince` | string \| null | Yes | - | - |
| `data.gstHstNumber` | string \| null | Yes | - | - |
| `data.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.paymentMethod` | string \| null | Yes | - | - |
| `data.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.factoringId` | string \| null | Yes | - | format: uuid |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### GET /api/v1/carriers/{carrierId}/files

`ark.list_carrier_files`

Lists files and compliance documents attached to a visible carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | Visible ARK carrier ID. | format: uuid |
| `query.type` | string | No | Optional carrier document type filter, such as W9, Insurance, Authority, Contract, or Other. | - |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/files' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

OK

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrier` | Carrier | Yes | - | - |
| `data.carrier.id` | string | Yes | - | format: uuid |
| `data.carrier.name` | string \| null | Yes | - | - |
| `data.carrier.dbaName` | string \| null | Yes | - | - |
| `data.carrier.notes` | string \| null | Yes | - | - |
| `data.carrier.code` | string \| null | Yes | - | - |
| `data.carrier.dotNum` | string \| null | Yes | - | - |
| `data.carrier.mcNum` | string \| null | Yes | - | - |
| `data.carrier.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.carrier.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.carrier.dispatchEmail` | string \| null | Yes | - | - |
| `data.carrier.dispatchPhone` | string \| null | Yes | - | - |
| `data.carrier.active` | boolean | Yes | - | - |
| `data.carrier.doNotUse` | boolean | Yes | - | - |
| `data.carrier.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.operatingCountries` | array<string> | Yes | - | - |
| `data.carrier.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.scac` | string \| null | Yes | - | - |
| `data.carrier.caat` | string \| null | Yes | - | - |
| `data.carrier.sctPermit` | string \| null | Yes | - | - |
| `data.carrier.nscNumber` | string \| null | Yes | - | - |
| `data.carrier.nscProvince` | string \| null | Yes | - | - |
| `data.carrier.gstHstNumber` | string \| null | Yes | - | - |
| `data.carrier.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.carrier.paymentMethod` | string \| null | Yes | - | - |
| `data.carrier.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.carrier.factoringId` | string \| null | Yes | - | format: uuid |
| `data.carrier.createdAt` | string \| null | Yes | - | format: date-time |
| `data.carrier.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.items` | array<CarrierFile> | Yes | - | - |
| `data.items[]` | CarrierFile | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].name` | string | Yes | - | - |
| `data.items[].path` | string | Yes | - | - |
| `data.items[].mime` | string \| null | Yes | - | - |
| `data.items[].type` | string | Yes | - | - |
| `data.items[].loadId` | string \| null | Yes | - | format: uuid |
| `data.items[].dispatchId` | string \| null | Yes | - | format: uuid |
| `data.items[].organizationId` | string | Yes | - | format: uuid |
| `data.items[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.items[].createdBy` | string \| null | Yes | - | format: uuid |
| `data.items[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.items[].systemGenerated` | boolean | Yes | - | - |
| `data.pagination` | object | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### DELETE /api/v1/carriers/{carrierId}/files/{fileId}

`ark.delete_carrier_file`

Deletes a user-uploaded carrier file from storage and the files table. System-generated files are protected.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canEditCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | Visible ARK carrier ID. | format: uuid |
| `path.fileId` | string | Yes | Carrier file ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/carriers/<carrierId>/files/<fileId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deleted file

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.deleted` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/carriers/{carrierId}/files/{fileId}/download-url

`ark.get_carrier_file_download_url`

Creates a short-lived signed download URL for a visible carrier file.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | Visible ARK carrier ID. | format: uuid |
| `path.fileId` | string | Yes | Carrier file ID. | format: uuid |
| `query.expires_in_seconds` | integer | No | - | default: 3600; min: 60; max: 86400 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/files/<fileId>/download-url' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

OK

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.file` | CarrierFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.signedUrl` | string | Yes | - | - |
| `data.expiresInSeconds` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/carriers/{carrierId}/files/finalize-upload

`ark.finalize_carrier_file_upload`

Finalizes a prepared upload by inserting the carrier file record and clearing the pending upload.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canEditCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | Visible ARK carrier ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `filePath` | string | Yes | - | min length: 1; max length: 2000 |
| `fileName` | string | No | - | min length: 1; max length: 255 |
| `fileType` | string | Yes | - | min length: 1; max length: 100 |
| `mimeType` | string | Yes | - | min length: 1; max length: 255 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/<carrierId>/files/finalize-upload' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "filePath": "<filePath>",
  "fileType": "<fileType>",
  "mimeType": "<mimeType>"
}'
```

#### Success response shape

Finalized upload

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrier` | Carrier | Yes | - | - |
| `data.carrier.id` | string | Yes | - | format: uuid |
| `data.carrier.name` | string \| null | Yes | - | - |
| `data.carrier.dbaName` | string \| null | Yes | - | - |
| `data.carrier.notes` | string \| null | Yes | - | - |
| `data.carrier.code` | string \| null | Yes | - | - |
| `data.carrier.dotNum` | string \| null | Yes | - | - |
| `data.carrier.mcNum` | string \| null | Yes | - | - |
| `data.carrier.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.carrier.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.carrier.dispatchEmail` | string \| null | Yes | - | - |
| `data.carrier.dispatchPhone` | string \| null | Yes | - | - |
| `data.carrier.active` | boolean | Yes | - | - |
| `data.carrier.doNotUse` | boolean | Yes | - | - |
| `data.carrier.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.operatingCountries` | array<string> | Yes | - | - |
| `data.carrier.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.scac` | string \| null | Yes | - | - |
| `data.carrier.caat` | string \| null | Yes | - | - |
| `data.carrier.sctPermit` | string \| null | Yes | - | - |
| `data.carrier.nscNumber` | string \| null | Yes | - | - |
| `data.carrier.nscProvince` | string \| null | Yes | - | - |
| `data.carrier.gstHstNumber` | string \| null | Yes | - | - |
| `data.carrier.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.carrier.paymentMethod` | string \| null | Yes | - | - |
| `data.carrier.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.carrier.factoringId` | string \| null | Yes | - | format: uuid |
| `data.carrier.createdAt` | string \| null | Yes | - | format: date-time |
| `data.carrier.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.file` | CarrierFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/carriers/{carrierId}/files/prepare-upload

`ark.prepare_carrier_file_upload`

Creates a signed upload URL and pending upload record for attaching a file to a visible carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canEditCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | Visible ARK carrier ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `fileName` | string | Yes | - | min length: 1; max length: 255 |
| `fileType` | string | Yes | - | min length: 1; max length: 100 |
| `mimeType` | string | Yes | - | min length: 1; max length: 255 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/<carrierId>/files/prepare-upload' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "<fileName>",
  "fileType": "<fileType>",
  "mimeType": "<mimeType>"
}'
```

#### Success response shape

Prepared upload

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrier` | Carrier | Yes | - | - |
| `data.carrier.id` | string | Yes | - | format: uuid |
| `data.carrier.name` | string \| null | Yes | - | - |
| `data.carrier.dbaName` | string \| null | Yes | - | - |
| `data.carrier.notes` | string \| null | Yes | - | - |
| `data.carrier.code` | string \| null | Yes | - | - |
| `data.carrier.dotNum` | string \| null | Yes | - | - |
| `data.carrier.mcNum` | string \| null | Yes | - | - |
| `data.carrier.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.carrier.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.carrier.dispatchEmail` | string \| null | Yes | - | - |
| `data.carrier.dispatchPhone` | string \| null | Yes | - | - |
| `data.carrier.active` | boolean | Yes | - | - |
| `data.carrier.doNotUse` | boolean | Yes | - | - |
| `data.carrier.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.operatingCountries` | array<string> | Yes | - | - |
| `data.carrier.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.scac` | string \| null | Yes | - | - |
| `data.carrier.caat` | string \| null | Yes | - | - |
| `data.carrier.sctPermit` | string \| null | Yes | - | - |
| `data.carrier.nscNumber` | string \| null | Yes | - | - |
| `data.carrier.nscProvince` | string \| null | Yes | - | - |
| `data.carrier.gstHstNumber` | string \| null | Yes | - | - |
| `data.carrier.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.carrier.paymentMethod` | string \| null | Yes | - | - |
| `data.carrier.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.carrier.factoringId` | string \| null | Yes | - | format: uuid |
| `data.carrier.createdAt` | string \| null | Yes | - | format: date-time |
| `data.carrier.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.fileName` | string | Yes | - | - |
| `data.fileType` | string | Yes | - | - |
| `data.mimeType` | string | Yes | - | - |
| `data.filePath` | string | Yes | - | - |
| `data.pendingUploadId` | string | Yes | - | format: uuid |
| `data.signedUrl` | string | Yes | - | - |
| `data.token` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/carriers/{carrierId}/fmcsa/authority

`ark.get_carrier_authority`

Returns FMCSA authority, authority history, revocation, and BOC-3 evidence for a visible ARK carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/fmcsa/authority' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier FMCSA authority

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CarrierFmcsaEvidence | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrierName` | string \| null | Yes | - | - |
| `data.dotNumber` | integer | Yes | - | - |
| `data.source` | string | Yes | - | one of: fmcsa |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/carriers/{carrierId}/fmcsa/crashes

`ark.get_carrier_crashes`

Returns FMCSA crash rows for a visible ARK carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |
| `query.cursor` | string | No | - | - |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 200 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/fmcsa/crashes' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier FMCSA crashes

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CarrierFmcsaEvidence | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrierName` | string \| null | Yes | - | - |
| `data.dotNumber` | integer | Yes | - | - |
| `data.source` | string | Yes | - | one of: fmcsa |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/carriers/{carrierId}/fmcsa/fleet

`ark.get_carrier_fleet`

Returns FMCSA fleet summary and VIN-backed vehicle evidence for a visible ARK carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |
| `query.page` | integer | No | - | default: 1; min: 1 |
| `query.limit` | integer | No | - | default: 100; min: 1; max: 500 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/fmcsa/fleet' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier FMCSA fleet

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CarrierFmcsaEvidence | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrierName` | string \| null | Yes | - | - |
| `data.dotNumber` | integer | Yes | - | - |
| `data.source` | string | Yes | - | one of: fmcsa |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/carriers/{carrierId}/fmcsa/history

`ark.get_carrier_history`

Returns FMCSA carrier profile change history for a visible ARK carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |
| `query.category` | string | No | - | one of: all, status, identity, contact, safety, fleet, insurance, authority; default: "all" |
| `query.field_prefix` | string | No | - | min length: 1; max length: 100 |
| `query.cursor` | string | No | - | - |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/fmcsa/history' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier FMCSA history

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CarrierFmcsaEvidence | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrierName` | string \| null | Yes | - | - |
| `data.dotNumber` | integer | Yes | - | - |
| `data.source` | string | Yes | - | one of: fmcsa |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/carriers/{carrierId}/fmcsa/inspections

`ark.get_carrier_inspections`

Returns FMCSA roadside inspections, violations, and citations for a visible ARK carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |
| `query.year` | string | No | - | - |
| `query.state` | string | No | - | min length: 2; max length: 2 |
| `query.inspection_level` | integer | No | - | min: 1; max: 8 |
| `query.oos` | boolean | No | - | - |
| `query.cursor` | string | No | - | - |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 200 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/fmcsa/inspections' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier FMCSA inspections

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CarrierFmcsaEvidence | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrierName` | string \| null | Yes | - | - |
| `data.dotNumber` | integer | Yes | - | - |
| `data.source` | string | Yes | - | one of: fmcsa |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/carriers/{carrierId}/fmcsa/insurance

`ark.get_carrier_insurance`

Returns FMCSA active insurance, policy, history, and rejected-filing evidence for a visible ARK carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/fmcsa/insurance' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier FMCSA insurance

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CarrierFmcsaEvidence | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrierName` | string \| null | Yes | - | - |
| `data.dotNumber` | integer | Yes | - | - |
| `data.source` | string | Yes | - | one of: fmcsa |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/carriers/{carrierId}/onboarding-profile

`ark.get_carrier_onboarding_profile`

Returns the saved provider onboarding profile for an organization carrier, including current packet status, agreements, artifacts, contacts, insurance, compliance, safety, authority, identity, and payment provenance read models.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/onboarding-profile' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier onboarding profile

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CarrierOnboardingProfile | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrierName` | string \| null | Yes | - | - |
| `data.dotNumber` | string \| null | Yes | - | - |
| `data.mcNumber` | string \| null | Yes | - | - |
| `data.profile` | CarrierOnboardingProfileData | Yes | - | - |
| `data.profile.current` | object \| null | Yes | - | - |
| `data.profile.providerCurrents` | array<object> | No | - | - |
| `data.profile.providerCurrents[]` | object | No | - | - |
| `data.profile.arkOnboardingCurrent` | object \| null | No | - | - |
| `data.profile.agreements` | array<object> | Yes | - | - |
| `data.profile.agreements[]` | object | Yes | - | - |
| `data.profile.artifacts` | array<object> | Yes | - | - |
| `data.profile.artifacts[]` | object | Yes | - | - |
| `data.profile.contacts` | array<object> | Yes | - | - |
| `data.profile.contacts[]` | object | Yes | - | - |
| `data.profile.insuranceCoverages` | array<object> | No | - | - |
| `data.profile.insuranceCoverages[]` | object | No | - | - |
| `data.profile.complianceFindings` | array<object> | No | - | - |
| `data.profile.complianceFindings[]` | object | No | - | - |
| `data.profile.safetySnapshots` | array<object> | No | - | - |
| `data.profile.safetySnapshots[]` | object | No | - | - |
| `data.profile.authoritySnapshots` | array<object> | No | - | - |
| `data.profile.authoritySnapshots[]` | object | No | - | - |
| `data.profile.operationsSnapshots` | array<object> | No | - | - |
| `data.profile.operationsSnapshots[]` | object | No | - | - |
| `data.profile.identitySignals` | array<object> | No | - | - |
| `data.profile.identitySignals[]` | object | No | - | - |
| `data.profile.paymentProvenance` | array<object> | No | - | - |
| `data.profile.paymentProvenance[]` | object | No | - | - |
| `data.profile.comparisonSummary` | object \| null | No | - | - |
| `data.profile.viewInProviderUrl` | string \| null | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/carriers/{carrierId}/onboarding/approve

`ark.approve_carrier_onboarding`

Approves a carrier submitted through self-service onboarding, activates the carrier, updates the invite, and sends the approval notification.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canApproveCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/<carrierId>/onboarding/approve' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Approved carrier onboarding

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrier` | CarrierOnboardingReviewCarrier | Yes | - | - |
| `data.carrier.id` | string | Yes | - | format: uuid |
| `data.carrier.organizationId` | string | Yes | - | format: uuid |
| `data.carrier.name` | string \| null | Yes | - | - |
| `data.carrier.dbaName` | string \| null | Yes | - | - |
| `data.carrier.dispatchEmail` | string \| null | Yes | - | format: email |
| `data.carrier.active` | boolean | Yes | - | - |
| `data.carrier.doNotUse` | boolean | Yes | - | - |
| `data.carrier.needsReview` | boolean | Yes | - | - |
| `data.invite` | CarrierOnboardingReviewInvite | Yes | - | - |
| `data.invite.id` | string | Yes | - | format: uuid |
| `data.invite.email` | string | Yes | - | format: email |
| `data.invite.status` | string | Yes | - | one of: approved, rejected |
| `data.invite.reviewedAt` | string \| null | Yes | - | format: date-time |
| `data.notification` | CarrierOnboardingReviewNotification | Yes | - | - |
| `data.notification.email` | string \| null | Yes | - | format: email |
| `data.notification.sent` | boolean | Yes | - | - |
| `data.notification.warning` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/carriers/{carrierId}/onboarding/reject

`ark.reject_carrier_onboarding`

Rejects a carrier submitted through self-service onboarding, marks the carrier do-not-use, updates the invite, and sends the rejection notification.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canApproveCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `rejectionNote` | string | No | - | max length: 2000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/<carrierId>/onboarding/reject' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Rejected carrier onboarding

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrier` | CarrierOnboardingReviewCarrier | Yes | - | - |
| `data.carrier.id` | string | Yes | - | format: uuid |
| `data.carrier.organizationId` | string | Yes | - | format: uuid |
| `data.carrier.name` | string \| null | Yes | - | - |
| `data.carrier.dbaName` | string \| null | Yes | - | - |
| `data.carrier.dispatchEmail` | string \| null | Yes | - | format: email |
| `data.carrier.active` | boolean | Yes | - | - |
| `data.carrier.doNotUse` | boolean | Yes | - | - |
| `data.carrier.needsReview` | boolean | Yes | - | - |
| `data.invite` | CarrierOnboardingReviewInvite | Yes | - | - |
| `data.invite.id` | string | Yes | - | format: uuid |
| `data.invite.email` | string | Yes | - | format: email |
| `data.invite.status` | string | Yes | - | one of: approved, rejected |
| `data.invite.reviewedAt` | string \| null | Yes | - | format: date-time |
| `data.notification` | CarrierOnboardingReviewNotification | Yes | - | - |
| `data.notification.email` | string \| null | Yes | - | format: email |
| `data.notification.sent` | boolean | Yes | - | - |
| `data.notification.warning` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/carriers/{carrierId}/review-metrics

`ark.get_carrier_review_metrics`

Returns the current average rating, review count, and on-time performance metrics for a visible carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | Visible ARK carrier ID. | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/review-metrics' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

OK

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrier` | Carrier | Yes | - | - |
| `data.carrier.id` | string | Yes | - | format: uuid |
| `data.carrier.name` | string \| null | Yes | - | - |
| `data.carrier.dbaName` | string \| null | Yes | - | - |
| `data.carrier.notes` | string \| null | Yes | - | - |
| `data.carrier.code` | string \| null | Yes | - | - |
| `data.carrier.dotNum` | string \| null | Yes | - | - |
| `data.carrier.mcNum` | string \| null | Yes | - | - |
| `data.carrier.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.carrier.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.carrier.dispatchEmail` | string \| null | Yes | - | - |
| `data.carrier.dispatchPhone` | string \| null | Yes | - | - |
| `data.carrier.active` | boolean | Yes | - | - |
| `data.carrier.doNotUse` | boolean | Yes | - | - |
| `data.carrier.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.operatingCountries` | array<string> | Yes | - | - |
| `data.carrier.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.scac` | string \| null | Yes | - | - |
| `data.carrier.caat` | string \| null | Yes | - | - |
| `data.carrier.sctPermit` | string \| null | Yes | - | - |
| `data.carrier.nscNumber` | string \| null | Yes | - | - |
| `data.carrier.nscProvince` | string \| null | Yes | - | - |
| `data.carrier.gstHstNumber` | string \| null | Yes | - | - |
| `data.carrier.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.carrier.paymentMethod` | string \| null | Yes | - | - |
| `data.carrier.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.carrier.factoringId` | string \| null | Yes | - | format: uuid |
| `data.carrier.createdAt` | string \| null | Yes | - | format: date-time |
| `data.carrier.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.metrics` | CarrierReviewMetrics | Yes | - | - |
| `data.metrics.averageRating` | number | Yes | - | - |
| `data.metrics.reviewCount` | integer | Yes | - | - |
| `data.metrics.totalStars` | integer | Yes | - | - |
| `data.metrics.onTimePercentage` | number \| null | Yes | - | - |
| `data.metrics.onTimeShipments` | integer | Yes | - | - |
| `data.metrics.totalShipments` | integer | Yes | - | - |
| `data.metrics.ratingUpdatedAt` | string \| null | Yes | - | format: date-time |
| `data.metrics.performanceCalculatedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### GET /api/v1/carriers/{carrierId}/reviews

`ark.list_carrier_reviews`

Lists broker-entered reviews for a visible carrier and returns current rating and on-time metrics.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | Visible ARK carrier ID. | format: uuid |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/reviews' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

OK

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrier` | Carrier | Yes | - | - |
| `data.carrier.id` | string | Yes | - | format: uuid |
| `data.carrier.name` | string \| null | Yes | - | - |
| `data.carrier.dbaName` | string \| null | Yes | - | - |
| `data.carrier.notes` | string \| null | Yes | - | - |
| `data.carrier.code` | string \| null | Yes | - | - |
| `data.carrier.dotNum` | string \| null | Yes | - | - |
| `data.carrier.mcNum` | string \| null | Yes | - | - |
| `data.carrier.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.carrier.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.carrier.dispatchEmail` | string \| null | Yes | - | - |
| `data.carrier.dispatchPhone` | string \| null | Yes | - | - |
| `data.carrier.active` | boolean | Yes | - | - |
| `data.carrier.doNotUse` | boolean | Yes | - | - |
| `data.carrier.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.operatingCountries` | array<string> | Yes | - | - |
| `data.carrier.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.scac` | string \| null | Yes | - | - |
| `data.carrier.caat` | string \| null | Yes | - | - |
| `data.carrier.sctPermit` | string \| null | Yes | - | - |
| `data.carrier.nscNumber` | string \| null | Yes | - | - |
| `data.carrier.nscProvince` | string \| null | Yes | - | - |
| `data.carrier.gstHstNumber` | string \| null | Yes | - | - |
| `data.carrier.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.carrier.paymentMethod` | string \| null | Yes | - | - |
| `data.carrier.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.carrier.factoringId` | string \| null | Yes | - | format: uuid |
| `data.carrier.createdAt` | string \| null | Yes | - | format: date-time |
| `data.carrier.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.metrics` | CarrierReviewMetrics | Yes | - | - |
| `data.metrics.averageRating` | number | Yes | - | - |
| `data.metrics.reviewCount` | integer | Yes | - | - |
| `data.metrics.totalStars` | integer | Yes | - | - |
| `data.metrics.onTimePercentage` | number \| null | Yes | - | - |
| `data.metrics.onTimeShipments` | integer | Yes | - | - |
| `data.metrics.totalShipments` | integer | Yes | - | - |
| `data.metrics.ratingUpdatedAt` | string \| null | Yes | - | format: date-time |
| `data.metrics.performanceCalculatedAt` | string \| null | Yes | - | format: date-time |
| `data.items` | array<CarrierReview> | Yes | - | - |
| `data.items[]` | CarrierReview | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].carrierId` | string | Yes | - | format: uuid |
| `data.items[].organizationId` | string | Yes | - | format: uuid |
| `data.items[].loadId` | string \| null | Yes | - | format: uuid |
| `data.items[].rating` | integer | Yes | - | min: 1; max: 5 |
| `data.items[].comment` | string \| null | Yes | - | - |
| `data.items[].reviewerName` | string | Yes | - | - |
| `data.items[].createdAt` | string | Yes | - | format: date-time |
| `data.items[].createdBy` | string \| null | Yes | - | format: uuid |
| `data.pagination` | object | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/carriers/{carrierId}/reviews

`ark.create_carrier_review`

Creates a broker carrier review with a 1-5 rating, optional comment, and optional visible load link.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canEditCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | Visible ARK carrier ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `loadId` | string | No | - | format: uuid |
| `rating` | integer | Yes | - | min: 1; max: 5 |
| `comment` | string \| null | No | - | max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/<carrierId>/reviews' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "rating": 1
}'
```

#### Success response shape

Created carrier review

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrier` | Carrier | Yes | - | - |
| `data.carrier.id` | string | Yes | - | format: uuid |
| `data.carrier.name` | string \| null | Yes | - | - |
| `data.carrier.dbaName` | string \| null | Yes | - | - |
| `data.carrier.notes` | string \| null | Yes | - | - |
| `data.carrier.code` | string \| null | Yes | - | - |
| `data.carrier.dotNum` | string \| null | Yes | - | - |
| `data.carrier.mcNum` | string \| null | Yes | - | - |
| `data.carrier.primaryEmail` | string \| null | Yes | Primary carrier email from the carrier address record. | format: email |
| `data.carrier.primaryPhone` | string \| null | Yes | Primary carrier phone from the carrier address record. | - |
| `data.carrier.dispatchEmail` | string \| null | Yes | - | - |
| `data.carrier.dispatchPhone` | string \| null | Yes | - | - |
| `data.carrier.active` | boolean | Yes | - | - |
| `data.carrier.doNotUse` | boolean | Yes | - | - |
| `data.carrier.domicileCountry` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.operatingCountries` | array<string> | Yes | - | - |
| `data.carrier.operatingCountries[]` | string | Yes | - | one of: USA, CAN, MEX |
| `data.carrier.scac` | string \| null | Yes | - | - |
| `data.carrier.caat` | string \| null | Yes | - | - |
| `data.carrier.sctPermit` | string \| null | Yes | - | - |
| `data.carrier.nscNumber` | string \| null | Yes | - | - |
| `data.carrier.nscProvince` | string \| null | Yes | - | - |
| `data.carrier.gstHstNumber` | string \| null | Yes | - | - |
| `data.carrier.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.carrier.paymentMethod` | string \| null | Yes | - | - |
| `data.carrier.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.carrier.factoringId` | string \| null | Yes | - | format: uuid |
| `data.carrier.createdAt` | string \| null | Yes | - | format: date-time |
| `data.carrier.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.review` | CarrierReview | Yes | - | - |
| `data.review.id` | string | Yes | - | format: uuid |
| `data.review.carrierId` | string | Yes | - | format: uuid |
| `data.review.organizationId` | string | Yes | - | format: uuid |
| `data.review.loadId` | string \| null | Yes | - | format: uuid |
| `data.review.rating` | integer | Yes | - | min: 1; max: 5 |
| `data.review.comment` | string \| null | Yes | - | - |
| `data.review.reviewerName` | string | Yes | - | - |
| `data.review.createdAt` | string | Yes | - | format: date-time |
| `data.review.createdBy` | string \| null | Yes | - | format: uuid |
| `data.metrics` | CarrierReviewMetrics | Yes | - | - |
| `data.metrics.averageRating` | number | Yes | - | - |
| `data.metrics.reviewCount` | integer | Yes | - | - |
| `data.metrics.totalStars` | integer | Yes | - | - |
| `data.metrics.onTimePercentage` | number \| null | Yes | - | - |
| `data.metrics.onTimeShipments` | integer | Yes | - | - |
| `data.metrics.totalShipments` | integer | Yes | - | - |
| `data.metrics.ratingUpdatedAt` | string \| null | Yes | - | format: date-time |
| `data.metrics.performanceCalculatedAt` | string \| null | Yes | - | format: date-time |
| `data.created` | unknown | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/carriers/{carrierId}/risk-card

`ark.get_carrier_risk_card`

Returns a visible carrier risk card with FMCSA safety, insurance, authority, fleet, crash, and risk indicator context.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/risk-card' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier risk card

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CarrierRiskCard | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.carrierName` | string \| null | Yes | - | - |
| `data.dotNumber` | integer | Yes | - | - |
| `data.generatedAt` | string | Yes | - | format: date-time |
| `data.source` | string | Yes | - | one of: fmcsa |
| `data.profile` | object \| null | Yes | - | - |
| `data.riskIndicators` | array<string> | Yes | - | - |
| `data.riskIndicators[]` | string | Yes | - | - |
| `data.safety` | object | Yes | - | - |
| `data.safety.safetyRating` | string \| null | Yes | - | - |
| `data.safety.safetyRatingDate` | string \| null | Yes | - | - |
| `data.safety.safetyReviewDate` | string \| null | Yes | - | - |
| `data.safety.safetyReviewType` | string \| null | Yes | - | - |
| `data.safety.scoreDate` | string \| null | Yes | - | - |
| `data.safety.basicScores` | object | Yes | - | - |
| `data.safety.latestMetrics` | object \| null | Yes | - | - |
| `data.safety.oosOrderCount` | integer | Yes | - | - |
| `data.safety.latestOosOrders` | array<object> | Yes | - | - |
| `data.safety.latestOosOrders[]` | object | Yes | - | - |
| `data.insurance` | object | Yes | - | - |
| `data.insurance.activePolicyCount` | integer | Yes | - | - |
| `data.insurance.latestActivePolicies` | array<object> | Yes | - | - |
| `data.insurance.latestActivePolicies[]` | object | Yes | - | - |
| `data.insurance.rejectedFilingCount` | integer | Yes | - | - |
| `data.insurance.latestRejectedFilings` | array<object> | Yes | - | - |
| `data.insurance.latestRejectedFilings[]` | object | Yes | - | - |
| `data.authority` | object | Yes | - | - |
| `data.authority.authorityRecordCount` | integer | Yes | - | - |
| `data.authority.latestAuthorityRecords` | array<object> | Yes | - | - |
| `data.authority.latestAuthorityRecords[]` | object | Yes | - | - |
| `data.authority.revocationCount` | integer | Yes | - | - |
| `data.authority.latestRevocations` | array<object> | Yes | - | - |
| `data.authority.latestRevocations[]` | object | Yes | - | - |
| `data.fleet` | object \| null | Yes | - | - |
| `data.crashes` | object | Yes | - | - |
| `data.crashes.total24mo` | integer | Yes | - | - |
| `data.crashes.fatal24mo` | integer | Yes | - | - |
| `data.crashes.injuries24mo` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/carriers/{carrierId}/verified-dispatch-emails

`ark.list_carrier_verified_dispatch_emails`

Fetches MyCarrierPortal verified dispatcher email addresses for a visible ARK carrier.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.carrierId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/<carrierId>/verified-dispatch-emails' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Carrier verified dispatch emails

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | CarrierVerifiedDispatchEmails | Yes | - | - |
| `data.carrierId` | string | Yes | - | format: uuid |
| `data.dotNumber` | string | Yes | - | - |
| `data.mcNumber` | string \| null | Yes | - | - |
| `data.emails` | array<string> | Yes | - | - |
| `data.emails[]` | string | Yes | - | format: email |
| `data.source` | unknown | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 503 | External provider or worker queue could not be reached |

### POST /api/v1/carriers/import

`ark.import_carriers`

Validates and imports carriers from parsed CSV rows with international authority, insurance, payment, factoring, and encrypted bank/tax fields.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canCreateCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `rows` | array<ImportCarrierRow> | Yes | - | min items: 1; max items: 1000 |
| `rows[]` | ImportCarrierRow | Yes | Parsed CSV row for carrier import. | - |
| `rows[].name` | string | Yes | - | min length: 1; max length: 200 |
| `rows[].dbaName` | string \| null | No | - | max length: 200 |
| `rows[].active` | boolean | No | - | default: false |
| `rows[].doNotUse` | boolean | No | - | default: false |
| `rows[].notes` | string \| null | No | - | max length: 5000 |
| `rows[].dispatchEmail` | string \| null | No | Email address or semicolon/comma-separated emails. | - |
| `rows[].dispatchPhone` | string \| null | No | - | max length: 50 |
| `rows[].domicileCountry` | string | No | - | one of: USA, CAN, MEX; default: "USA" |
| `rows[].operatingCountries` | array<string> | No | - | min items: 1; max items: 3 |
| `rows[].operatingCountries[]` | string | No | - | one of: USA, CAN, MEX |
| `rows[].dotNumber` | string \| null | No | DOT number. Required with US operating authority unless mcNumber is provided. | max length: 30 |
| `rows[].mcNumber` | string \| null | No | MC, FF, MX, or numeric authority identifier. | max length: 30 |
| `rows[].scac` | string \| null | No | - | - |
| `rows[].caat` | string \| null | No | Required for carriers operating in Mexico. | max length: 30 |
| `rows[].taxId` | string \| null | No | Sensitive tax ID to store encrypted. Value is never returned. | max length: 100 |
| `rows[].sctPermit` | string \| null | No | - | max length: 100 |
| `rows[].nscNumber` | string \| null | No | Required for carriers operating in Canada. | max length: 100 |
| `rows[].nscProvince` | string \| null | No | Required for carriers operating in Canada. | max length: 100 |
| `rows[].gstHstNumber` | string \| null | No | - | max length: 100 |
| `rows[].defaultCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `rows[].address` | string \| null | No | - | max length: 500 |
| `rows[].address2` | string \| null | No | - | max length: 500 |
| `rows[].city` | string \| null | No | - | max length: 200 |
| `rows[].state` | string \| null | No | - | max length: 20 |
| `rows[].zip` | string \| null | No | - | max length: 30 |
| `rows[].phone` | string \| null | No | - | max length: 50 |
| `rows[].email` | string \| null | No | Email address or semicolon/comma-separated emails. | - |
| `rows[].billingAddress` | string \| null | No | - | max length: 500 |
| `rows[].billingAddress2` | string \| null | No | - | max length: 500 |
| `rows[].billingCity` | string \| null | No | - | max length: 200 |
| `rows[].billingState` | string \| null | No | - | max length: 20 |
| `rows[].billingZip` | string \| null | No | - | max length: 30 |
| `rows[].billingPhone` | string \| null | No | - | max length: 50 |
| `rows[].billingEmail` | string \| null | No | Email address or semicolon/comma-separated emails. | - |
| `rows[].fmcsaBrokerAuthority` | boolean | No | - | default: false |
| `rows[].fmcsaCommonAuthority` | boolean | No | - | default: false |
| `rows[].fmcsaContractAuthority` | boolean | No | - | default: false |
| `rows[].insuranceAutoLiability` | number | No | - | - |
| `rows[].insuranceAutoLiabilityCompany` | string \| null | No | - | max length: 200 |
| `rows[].insuranceAutoLiabilityPolicyNum` | string \| null | No | - | max length: 100 |
| `rows[].insuranceAutoLiabilityExpiration` | string \| null | No | - | max length: 50 |
| `rows[].insuranceGeneralLiability` | number | No | - | - |
| `rows[].insuranceGeneralLiabilityCompany` | string \| null | No | - | max length: 200 |
| `rows[].insuranceGeneralLiabilityPolicyNum` | string \| null | No | - | max length: 100 |
| `rows[].insuranceGeneralLiabilityExpiration` | string \| null | No | - | max length: 50 |
| `rows[].insuranceCargo` | number | No | - | - |
| `rows[].insuranceCargoCompany` | string \| null | No | - | max length: 200 |
| `rows[].insuranceCargoPolicyNum` | string \| null | No | - | max length: 100 |
| `rows[].insuranceCargoExpiration` | string \| null | No | - | max length: 50 |
| `rows[].useFactoring` | boolean | No | - | default: false |
| `rows[].factoringCompanyName` | string \| null | No | Existing factoring company name to resolve when useFactoring is true. | max length: 200 |
| `rows[].paymentTermDays` | integer | No | Required when useFactoring is false. | - |
| `rows[].paymentTermDiscount` | number | No | - | default: 0 |
| `rows[].paymentMethod` | string \| null | No | - | max length: 50 |
| `rows[].bankName` | string \| null | No | - | max length: 100 |
| `rows[].bankType` | string \| null | No | - | max length: 50 |
| `rows[].bankAccountNum` | string \| null | No | Sensitive bank account number to store encrypted. Value is never returned. | max length: 100 |
| `rows[].transitNumber` | string \| null | No | Canadian transit number used with institutionNumber. | max length: 20 |
| `rows[].institutionNumber` | string \| null | No | Canadian institution number used with transitNumber. | max length: 20 |
| `rows[].bankRoutingNum` | string \| null | No | US ABA, Canadian combined routing, or Mexican CLABE. Stored encrypted. | max length: 50 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/import' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "name": "<name>"
    }
  ]
}'
```

#### Success response shape

Carrier import result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ImportCarriersResult | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.totalRows` | integer | Yes | - | min: 0 |
| `data.successCount` | integer | Yes | - | min: 0 |
| `data.errorCount` | integer | Yes | - | min: 0 |
| `data.skippedCount` | integer | Yes | - | min: 0 |
| `data.errors` | array<ImportCarrierError> | Yes | - | - |
| `data.errors[]` | ImportCarrierError | Yes | - | - |
| `data.errors[].row` | integer | Yes | - | min: 1 |
| `data.errors[].field` | string | Yes | - | - |
| `data.errors[].value` | string | Yes | - | - |
| `data.errors[].message` | string | Yes | - | - |
| `data.createdCarriers` | array<ImportedCarrierSummary> | Yes | - | - |
| `data.createdCarriers[]` | ImportedCarrierSummary | Yes | - | - |
| `data.createdCarriers[].row` | integer | Yes | - | min: 1 |
| `data.createdCarriers[].carrierId` | string | Yes | - | format: uuid |
| `data.createdCarriers[].name` | string | Yes | - | - |
| `data.createdCarriers[].addressId` | string | Yes | - | format: uuid |
| `data.createdCarriers[].billingAddressId` | string | Yes | - | format: uuid |
| `data.createdCarriers[].fmcsaId` | string | Yes | - | format: uuid |
| `data.createdCarriers[].insuranceId` | string | Yes | - | format: uuid |
| `data.createdCarriers[].factoringId` | string \| null | Yes | - | format: uuid |
| `data.createdCarriers[].paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.createdCarriers[].paymentTermMatched` | boolean \| null | Yes | - | - |
| `data.createdCarriers[].sensitiveFields` | object | Yes | - | - |
| `data.createdCarriers[].sensitiveFields.taxIdSet` | boolean | Yes | - | - |
| `data.createdCarriers[].sensitiveFields.bankAccountNumSet` | boolean | Yes | - | - |
| `data.createdCarriers[].sensitiveFields.bankRoutingNumSet` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/carriers/provider-onboarding/invite

`ark.invite_carrier_provider_onboarding`

Sends a carrier onboarding invitation through Highway, RMIS, or MyCarrierPortal using the same provider-specific workflow as the carrier screen.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canInviteCarrierExternal` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | CarrierProviderOnboardingProvider | Yes | - | one of: highway, rmis, mycarrierportal |
| `email` | string | Yes | - | format: email; max length: 254 |
| `carrierId` | string | No | - | format: uuid |
| `dotNumber` | string | No | - | min length: 1; max length: 32 |
| `mcNumber` | string | No | - | min length: 1; max length: 32 |
| `highwayCarrierId` | string | No | - | min length: 1; max length: 64 |
| `highwayExternalId` | string | No | - | min length: 1; max length: 100 |
| `companyName` | string | No | - | min length: 1; max length: 200 |
| `contactName` | string | No | - | min length: 1; max length: 200 |
| `createUserName` | string | No | - | min length: 1; max length: 200 |
| `createUserEmail` | string | No | - | format: email; max length: 254 |
| `clientMemberId` | string | No | - | min length: 1; max length: 100 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/provider-onboarding/invite' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "highway",
  "email": "<email>"
}'
```

#### Success response shape

Provider onboarding invitation sent

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | InviteCarrierProviderOnboardingResult | Yes | - | - |
| `data.provider` | CarrierProviderOnboardingProvider | Yes | - | one of: highway, rmis, mycarrierportal |
| `data.success` | unknown | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.invitation` | object | No | - | - |
| `data.providerResponse` | object | No | - | - |
| `data.persistedToCarrier` | boolean | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |
| 502 | External provider or worker queue could not be reached |

### POST /api/v1/carriers/provider-onboarding/preview

`ark.preview_carrier_provider_onboarding`

Looks up a carrier in Highway, RMIS, or MyCarrierPortal before sending an external onboarding invitation.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canInviteCarrierExternal` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | CarrierProviderOnboardingProvider | Yes | - | one of: highway, rmis, mycarrierportal |
| `dotNumber` | string | No | - | min length: 1; max length: 32 |
| `mcNumber` | string | No | - | min length: 1; max length: 32 |
| `highwayCarrierId` | string | No | - | min length: 1; max length: 64 |
| `highwayExternalId` | string | No | - | min length: 1; max length: 100 |
| `email` | string | No | - | format: email; max length: 254 |
| `includeCarrierData` | boolean | No | - | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/provider-onboarding/preview' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "highway"
}'
```

#### Success response shape

Provider onboarding preview

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | PreviewCarrierProviderOnboardingResult | Yes | - | - |
| `data.provider` | CarrierProviderOnboardingProvider | Yes | - | one of: highway, rmis, mycarrierportal |
| `data.lookup` | object | Yes | - | - |
| `data.lookup.dotNumber` | string \| null | Yes | - | - |
| `data.lookup.mcNumber` | string \| null | Yes | - | - |
| `data.lookup.highwayCarrierId` | string \| null | Yes | - | - |
| `data.lookup.highwayExternalId` | string \| null | Yes | - | - |
| `data.preview` | object | Yes | - | - |
| `data.verifiedEmails` | array<string> | No | - | - |
| `data.verifiedEmails[]` | string | No | - | format: email |
| `data.carrierData` | object | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 422 | Invalid request |
| 502 | External provider or worker queue could not be reached |

### POST /api/v1/carriers/provider-sync

`ark.sync_carrier_provider_profile`

Syncs a carrier profile, packet, documents, compliance, insurance, identity, and payment evidence from Highway, RMIS, or MyCarrierPortal into ARK.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:write` |
| ARK permissions | `canEditCarrier` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | string | Yes | External onboarding and monitoring provider to sync from. | one of: highway, rmis, mycarrierportal |
| `carrierId` | string | No | Optional existing ARK carrier ID to refresh from the provider. | format: uuid |
| `dotNumber` | string | No | Optional DOT number lookup for provider sync. | max length: 32 |
| `mcNumber` | string | No | Optional MC/MX docket number lookup for provider sync. | max length: 32 |
| `highwayCarrierId` | string | No | Highway carrier ID when syncing from Highway. | max length: 64 |
| `highwayExternalId` | string | No | Highway external ID when syncing from Highway. | max length: 100 |
| `rmisCarrierId` | string | No | RMIS carrier ID when syncing from RMIS. | max length: 64 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/provider-sync' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "highway"
}'
```

#### Success response shape

Synced carrier provider profile

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SyncCarrierProviderProfileResult | Yes | - | - |
| `data.provider` | string | Yes | - | one of: highway, rmis, mycarrierportal |
| `data.status` | string | Yes | - | one of: completed, completed_with_warning, already_running |
| `data.carrierId` | string \| null | Yes | - | format: uuid |
| `data.providerCarrierId` | string \| null | Yes | - | - |
| `data.snapshotId` | string \| null | Yes | - | format: uuid |
| `data.packetStatus` | string \| null | Yes | - | - |
| `data.retryAfterSeconds` | integer \| null | Yes | - | min: 0 |
| `data.warnings` | array<string> | Yes | - | - |
| `data.warnings[]` | string | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### GET /api/v1/carriers/rmis-registration-steps

`ark.get_rmis_registration_steps`

Fetches RMIS registration-step activity for a carrier by RMIS ID, DOT, MC/MX, intrastate number, or today activity.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canInviteCarrierExternal` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.rmis_carrier_id` | string | No | - | max length: 64 |
| `query.dot_number` | string | No | - | max length: 32 |
| `query.mc_number` | string | No | - | max length: 32 |
| `query.intra_state_number` | string | No | - | max length: 64 |
| `query.all_activity_for_today` | boolean | No | - | default: false |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/carriers/rmis-registration-steps' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

RMIS registration steps

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | GetRmisRegistrationStepsResult | Yes | - | - |
| `data.provider` | unknown | Yes | - | - |
| `data.filter` | object | Yes | - | - |
| `data.filter.rmisCarrierId` | string \| null | Yes | - | - |
| `data.filter.dotNumber` | string \| null | Yes | - | - |
| `data.filter.mcNumber` | string \| null | Yes | - | - |
| `data.filter.intraStateNumber` | string \| null | Yes | - | - |
| `data.filter.allActivityForToday` | boolean | Yes | - | - |
| `data.steps` | array<object> | Yes | - | - |
| `data.steps[]` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 422 | Invalid request |
| 502 | External provider or worker queue could not be reached |

### POST /api/v1/carriers/rmis-registration-steps

`ark.get_rmis_registration_steps`

POST variant for fetching RMIS registration-step activity when a JSON body is easier than query parameters.

| Requirement | Value |
| --- | --- |
| Scopes | `carriers:read` |
| ARK permissions | `canInviteCarrierExternal` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `rmisCarrierId` | string | No | - | min length: 1; max length: 64 |
| `dotNumber` | string | No | - | min length: 1; max length: 32 |
| `mcNumber` | string | No | - | min length: 1; max length: 32 |
| `intraStateNumber` | string | No | - | min length: 1; max length: 64 |
| `allActivityForToday` | boolean | No | - | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/carriers/rmis-registration-steps' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

RMIS registration steps

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | GetRmisRegistrationStepsResult | Yes | - | - |
| `data.provider` | unknown | Yes | - | - |
| `data.filter` | object | Yes | - | - |
| `data.filter.rmisCarrierId` | string \| null | Yes | - | - |
| `data.filter.dotNumber` | string \| null | Yes | - | - |
| `data.filter.mcNumber` | string \| null | Yes | - | - |
| `data.filter.intraStateNumber` | string \| null | Yes | - | - |
| `data.filter.allActivityForToday` | boolean | Yes | - | - |
| `data.steps` | array<object> | Yes | - | - |
| `data.steps[]` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 422 | Invalid request |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/compliance/pod-reviews

`ark.list_pod_review_queue`

Lists visible delivered loads with proof-of-delivery file and review status context for billing compliance work.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | PodReviewQueueStatus | No | - | - |
| `query.query` | string | No | Optional load number or customer search text. | min length: 1; max length: 100 |
| `query.q` | string | No | Alias for query. | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/compliance/pod-reviews' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

POD review queue

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.items` | array<PodReviewQueueItem> | Yes | - | - |
| `data.items[]` | PodReviewQueueItem | Yes | - | - |
| `data.items[].loadId` | string | Yes | - | format: uuid |
| `data.items[].loadNumber` | integer | Yes | - | - |
| `data.items[].customerName` | string \| null | Yes | - | - |
| `data.items[].originCity` | string \| null | Yes | - | - |
| `data.items[].originState` | string \| null | Yes | - | - |
| `data.items[].destinationCity` | string \| null | Yes | - | - |
| `data.items[].destinationState` | string \| null | Yes | - | - |
| `data.items[].complianceStatus` | string | Yes | - | - |
| `data.items[].latestReviewDate` | string \| null | Yes | - | format: date-time |
| `data.items[].latestReviewer` | string \| null | Yes | - | - |
| `data.items[].createdAt` | string | Yes | - | format: date-time |
| `data.items[].loadStatus` | string \| null | Yes | - | - |
| `data.items[].carrierName` | string \| null | Yes | - | - |
| `data.items[].podFile` | PodReviewQueueFile \| null | Yes | - | - |
| `data.pagination` | object | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/compliance/pod-reviews/bulk-review

`ark.bulk_update_pod_review_status`

Bulk approves or rejects visible proof-of-delivery document reviews from the billing compliance queue.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `reviewIds` | array<string> | Yes | - | min items: 1; max items: 100 |
| `reviewIds[]` | string | Yes | - | format: uuid |
| `status` | string | Yes | - | one of: approved, rejected |
| `approvalNotes` | string \| null | No | - | max length: 5000 |
| `rejectionReason` | string \| null | No | - | max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/compliance/pod-reviews/bulk-review' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "reviewIds": [
    "<reviewIds>"
  ],
  "status": "approved"
}'
```

#### Success response shape

Updated POD reviews

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.reviews` | array<PodDocumentReview> | Yes | - | - |
| `data.reviews[]` | PodDocumentReview | Yes | - | - |
| `data.reviews[].id` | string | Yes | - | format: uuid |
| `data.reviews[].organizationId` | string | Yes | - | - |
| `data.reviews[].loadId` | string | Yes | - | format: uuid |
| `data.reviews[].fileId` | string | Yes | - | format: uuid |
| `data.reviews[].status` | PodReviewStatus | Yes | - | one of: pending_review, approved, rejected, revision_required |
| `data.reviews[].reviewedBy` | string \| null | Yes | - | - |
| `data.reviews[].reviewedAt` | string \| null | Yes | - | format: date-time |
| `data.reviews[].approvalNotes` | string \| null | Yes | - | - |
| `data.reviews[].rejectionReason` | string \| null | Yes | - | - |
| `data.reviews[].requiresRevision` | boolean \| null | Yes | - | - |
| `data.reviews[].priority` | integer \| null | Yes | - | - |
| `data.reviews[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.reviews[].updatedAt` | string \| null | Yes | - | format: date-time |
| `data.count` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/compliance/pod-reviews/review

`ark.update_pod_review_status`

Approves, rejects, requests revision, or resets review status for a visible proof-of-delivery document.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `reviewId` | string | No | - | format: uuid |
| `fileId` | string | No | - | format: uuid |
| `status` | PodReviewStatus | Yes | - | one of: pending_review, approved, rejected, revision_required |
| `approvalNotes` | string \| null | No | - | max length: 5000 |
| `rejectionReason` | string \| null | No | - | max length: 5000 |
| `priority` | integer | No | - | min: 1; max: 5 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/compliance/pod-reviews/review' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '"<body>"'
```

#### Success response shape

Updated POD review

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.review` | PodDocumentReview | Yes | - | - |
| `data.review.id` | string | Yes | - | format: uuid |
| `data.review.organizationId` | string | Yes | - | - |
| `data.review.loadId` | string | Yes | - | format: uuid |
| `data.review.fileId` | string | Yes | - | format: uuid |
| `data.review.status` | PodReviewStatus | Yes | - | one of: pending_review, approved, rejected, revision_required |
| `data.review.reviewedBy` | string \| null | Yes | - | - |
| `data.review.reviewedAt` | string \| null | Yes | - | format: date-time |
| `data.review.approvalNotes` | string \| null | Yes | - | - |
| `data.review.rejectionReason` | string \| null | Yes | - | - |
| `data.review.requiresRevision` | boolean \| null | Yes | - | - |
| `data.review.priority` | integer \| null | Yes | - | - |
| `data.review.createdAt` | string \| null | Yes | - | format: date-time |
| `data.review.updatedAt` | string \| null | Yes | - | format: date-time |
| `data.action` | string | Yes | - | one of: created, updated |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/customers

`ark.search_customers`

Searches customers visible to the connected actor by name, code, and team visibility.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:read` |
| ARK permissions | `canViewCustomers` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | No | - | min length: 1; max length: 100 |
| `query.team_ids` | string | No | Comma-separated team IDs. Omit to use all teams visible to the connected user. | - |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/customers' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Visible customer search results

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.items` | array<object> | Yes | - | - |
| `data.items[]` | object | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].name` | string \| null | Yes | - | - |
| `data.items[].code` | string \| null | Yes | - | - |
| `data.items[].type` | string \| null | Yes | - | - |
| `data.items[].country` | string | Yes | - | - |
| `data.items[].defaultCurrency` | string | Yes | - | - |
| `data.items[].trackingEmail` | string \| null | Yes | - | - |
| `data.items[].createdAt` | string | Yes | - | format: date-time |
| `data.items[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.pagination` | CursorPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/customers

`ark.create_customer`

Creates a customer profile and visible team mappings.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:write` |
| ARK permissions | `canCreateCustomer` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `name` | string | Yes | - | min length: 2; max length: 200 |
| `code` | string \| null | No | - | max length: 50 |
| `type` | string \| null | No | - | max length: 50 |
| `country` | string | No | - | one of: USA, CAN, MEX; default: "USA" |
| `defaultCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `trackingEmail` | string \| null | No | - | max length: 500 |
| `notes` | string \| null | No | - | max length: 5000 |
| `businessHoursOpen` | string \| null | No | - | max length: 50 |
| `businessHoursClose` | string \| null | No | - | max length: 50 |
| `paymentTermId` | string \| null | No | - | format: uuid |
| `teamIds` | array<string> | Yes | - | min items: 1; max items: 100 |
| `teamIds[]` | string | Yes | - | format: uuid |
| `defaultInvoiceRemitProfileId` | string \| null | No | Optional customer-specific invoice remit profile ID. Use null to inherit the organization default. | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/customers' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "<name>",
  "teamIds": [
    "<teamIds>"
  ]
}'
```

#### Success response shape

Created customer

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Customer | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.code` | string \| null | Yes | - | - |
| `data.type` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.businessHoursOpen` | string \| null | Yes | - | - |
| `data.businessHoursClose` | string \| null | Yes | - | - |
| `data.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.country` | string | Yes | - | one of: USA, CAN, MEX |
| `data.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.trackingEmail` | string \| null | Yes | - | - |
| `data.teamIds` | array<string> | Yes | - | - |
| `data.teamIds[]` | string | Yes | - | format: uuid |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.defaultInvoiceRemitProfileId` | string \| null | Yes | - | format: uuid |
| `data.defaultInvoiceRemitProfile` | object \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### DELETE /api/v1/customers/{customerId}

`ark.delete_customer`

Soft-deletes a visible customer when every mapped customer team is inside the connected actor team scope.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:write` |
| ARK permissions | `canDeleteCustomer` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.customerId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/customers/<customerId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deleted customer

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.deleted` | unknown | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/customers/{customerId}

`ark.get_customer`

Returns one visible customer by ID.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:read` |
| ARK permissions | `canViewCustomers` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.customerId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/customers/<customerId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Get customer

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Customer | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.code` | string \| null | Yes | - | - |
| `data.type` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.businessHoursOpen` | string \| null | Yes | - | - |
| `data.businessHoursClose` | string \| null | Yes | - | - |
| `data.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.country` | string | Yes | - | one of: USA, CAN, MEX |
| `data.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.trackingEmail` | string \| null | Yes | - | - |
| `data.teamIds` | array<string> | Yes | - | - |
| `data.teamIds[]` | string | Yes | - | format: uuid |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.defaultInvoiceRemitProfileId` | string \| null | Yes | - | format: uuid |
| `data.defaultInvoiceRemitProfile` | object \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/customers/{customerId}

`ark.update_customer`

Updates a visible customer profile and optional team mappings.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:write` |
| ARK permissions | `canEditCustomer` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.customerId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `name` | string | No | - | min length: 2; max length: 200 |
| `code` | string \| null | No | - | max length: 50 |
| `type` | string \| null | No | - | max length: 50 |
| `country` | string | No | - | one of: USA, CAN, MEX; default: "USA" |
| `defaultCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `trackingEmail` | string \| null | No | - | max length: 500 |
| `notes` | string \| null | No | - | max length: 5000 |
| `businessHoursOpen` | string \| null | No | - | max length: 50 |
| `businessHoursClose` | string \| null | No | - | max length: 50 |
| `paymentTermId` | string \| null | No | - | format: uuid |
| `defaultInvoiceRemitProfileId` | string \| null | No | Optional customer-specific invoice remit profile ID. Use null to inherit the organization default. | format: uuid |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/customers/<customerId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated customer

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Customer | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.code` | string \| null | Yes | - | - |
| `data.type` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.businessHoursOpen` | string \| null | Yes | - | - |
| `data.businessHoursClose` | string \| null | Yes | - | - |
| `data.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.country` | string | Yes | - | one of: USA, CAN, MEX |
| `data.defaultCurrency` | string | Yes | - | one of: USD, CAD, MXN |
| `data.trackingEmail` | string \| null | Yes | - | - |
| `data.teamIds` | array<string> | Yes | - | - |
| `data.teamIds[]` | string | Yes | - | format: uuid |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.defaultInvoiceRemitProfileId` | string \| null | Yes | - | format: uuid |
| `data.defaultInvoiceRemitProfile` | object \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PUT /api/v1/customers/{customerId}/billing-requirements

`ark.set_customer_billing_requirements`

Replaces the required billing packet document type list for a visible customer. Send an empty requiredBillingPacketFileTypes array to clear requirements.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:write` |
| ARK permissions | `canEditCustomer` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.customerId` | string | Yes | Visible ARK customer ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `requiredBillingPacketFileTypes` | array<string> | Yes | Exact required billing packet document types for the customer. Send an empty array to clear requirements. | max items: 50 |
| `requiredBillingPacketFileTypes[]` | string | Yes | - | one of: BOL, Load Tender, Rate Approval, Lumper Receipt, POD, Other |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/customers/<customerId>/billing-requirements' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "requiredBillingPacketFileTypes": [
    "BOL"
  ]
}'
```

#### Success response shape

Customer billing requirement result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | SetCustomerBillingRequirementsResult | Yes | - | - |
| `data.customerId` | string | Yes | - | format: uuid |
| `data.requiredBillingPacketFileTypes` | array<string> | Yes | - | - |
| `data.requiredBillingPacketFileTypes[]` | string | Yes | - | one of: BOL, Load Tender, Rate Approval, Lumper Receipt, POD, Other |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### PUT /api/v1/customers/{customerId}/managers

`ark.set_customer_managers`

Replaces the assigned manager user list for a visible customer. Send an empty managerIds array to clear customer managers.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:write` |
| ARK permissions | `canEditCustomer` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.customerId` | string | Yes | Visible ARK customer ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `managerIds` | array<string> | Yes | Exact active ARK user IDs to assign as customer managers. Send an empty array to clear managers. | max items: 100 |
| `managerIds[]` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/customers/<customerId>/managers' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "managerIds": [
    "<managerIds>"
  ]
}'
```

#### Success response shape

Customer manager assignment result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | SetCustomerManagersResult | Yes | - | - |
| `data.customerId` | string | Yes | - | format: uuid |
| `data.managerIds` | array<string> | Yes | - | - |
| `data.managerIds[]` | string | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### PUT /api/v1/customers/{customerId}/project44

`ark.set_customer_project44_mapping`

Creates, updates, or deactivates the tenant-admin project44 customer mapping for a visible customer.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:write` |
| ARK permissions | `canEditCustomer` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.customerId` | string | Yes | Visible ARK customer ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `active` | boolean | Yes | Whether project44 forwarding is active for this customer mapping. | - |
| `project44CustomerId` | string | No | project44 customer ID. Required when active is true. | min length: 1; max length: 200 |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/customers/<customerId>/project44' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "active": false
}'
```

#### Success response shape

Customer project44 mapping result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | SetCustomerProject44MappingResult | Yes | - | - |
| `data.customerId` | string | Yes | - | format: uuid |
| `data.mapping` | object \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### PUT /api/v1/customers/{customerId}/teams

`ark.set_customer_team_visibility`

Replaces the customer team mappings the connected actor can manage while preserving existing mappings outside the actor team scope.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:write` |
| ARK permissions | `canEditCustomer` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.customerId` | string | Yes | Visible ARK customer ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `teamIds` | array<string> | Yes | Visible ARK team IDs to set for the customer. Existing customer mappings outside the connection team scope are preserved and returned. | min items: 1; max items: 100 |
| `teamIds[]` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/customers/<customerId>/teams' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "teamIds": [
    "<teamIds>"
  ]
}'
```

#### Success response shape

Customer team visibility result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | SetCustomerTeamVisibilityResult | Yes | - | - |
| `data.customerId` | string | Yes | - | format: uuid |
| `data.teamIds` | array<string> | Yes | Final customer team visibility IDs after preserving hidden mappings. | - |
| `data.teamIds[]` | string | Yes | - | format: uuid |
| `data.preservedTeamIds` | array<string> | Yes | Existing customer team mappings outside the connection team scope that were preserved. | - |
| `data.preservedTeamIds[]` | string | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/customers/import

`ark.import_customers`

Validates and imports customers from parsed CSV rows with team visibility, duplicate skipping, payment term matching, address, insurance, and credit details.

| Requirement | Value |
| --- | --- |
| Scopes | `customers:write` |
| ARK permissions | `canCreateCustomer` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `rows` | array<ImportCustomerRow> | Yes | - | min items: 1; max items: 1000 |
| `rows[]` | ImportCustomerRow | Yes | Parsed CSV row for customer import. | - |
| `rows[].teamName` | string | No | - | max length: 200 |
| `rows[].teamId` | string | No | - | - |
| `rows[].name` | string | Yes | - | min length: 1; max length: 200 |
| `rows[].country` | string | No | - | one of: USA, CAN, MEX; default: "USA" |
| `rows[].defaultCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `rows[].code` | string \| null | No | - | max length: 50 |
| `rows[].notes` | string \| null | No | - | max length: 5000 |
| `rows[].trackingEmail` | string \| null | No | - | max length: 500 |
| `rows[].businessHoursOpen` | string \| null | No | - | max length: 50 |
| `rows[].businessHoursClose` | string \| null | No | - | max length: 50 |
| `rows[].address` | string \| null | No | - | max length: 500 |
| `rows[].address2` | string \| null | No | - | max length: 500 |
| `rows[].city` | string \| null | No | - | max length: 200 |
| `rows[].state` | string \| null | No | - | max length: 20 |
| `rows[].zip` | string \| null | No | - | max length: 30 |
| `rows[].phone` | string \| null | No | - | max length: 50 |
| `rows[].email` | string \| null | No | - | max length: 500 |
| `rows[].insuranceAutoLiability` | number | No | - | - |
| `rows[].insuranceGeneralLiability` | number | No | - | - |
| `rows[].insuranceCargo` | number | No | - | - |
| `rows[].creditFederalId` | string \| null | No | - | max length: 100 |
| `rows[].creditBillingAddress` | string \| null | No | - | max length: 500 |
| `rows[].creditBillingAddress2` | string \| null | No | - | max length: 500 |
| `rows[].creditBillingCity` | string \| null | No | - | max length: 200 |
| `rows[].creditBillingState` | string \| null | No | - | max length: 20 |
| `rows[].creditBillingZip` | string \| null | No | - | max length: 30 |
| `rows[].creditBillingPhone` | string \| null | No | - | max length: 50 |
| `rows[].creditBillingEmail` | string \| null | No | - | max length: 500 |
| `rows[].creditBillingContact` | string \| null | No | - | max length: 200 |
| `rows[].creditApproved` | boolean | No | - | - |
| `rows[].creditLimit` | number | No | - | - |
| `rows[].paymentTermDays` | integer | No | Payment term days to match against an organization payment term. | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/customers/import' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "name": "<name>"
    }
  ]
}'
```

#### Success response shape

Customer import result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ImportCustomersResult | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.totalRows` | integer | Yes | - | min: 0 |
| `data.successCount` | integer | Yes | - | min: 0 |
| `data.errorCount` | integer | Yes | - | min: 0 |
| `data.skippedCount` | integer | Yes | - | min: 0 |
| `data.errors` | array<ImportCustomerError> | Yes | - | - |
| `data.errors[]` | ImportCustomerError | Yes | - | - |
| `data.errors[].row` | integer | Yes | - | min: 1 |
| `data.errors[].field` | string | Yes | - | - |
| `data.errors[].value` | string | Yes | - | - |
| `data.errors[].message` | string | Yes | - | - |
| `data.createdCustomers` | array<ImportedCustomerSummary> | Yes | - | - |
| `data.createdCustomers[]` | ImportedCustomerSummary | Yes | - | - |
| `data.createdCustomers[].row` | integer | Yes | - | min: 1 |
| `data.createdCustomers[].customerId` | string | Yes | - | format: uuid |
| `data.createdCustomers[].name` | string | Yes | - | - |
| `data.createdCustomers[].teamId` | string | Yes | - | format: uuid |
| `data.createdCustomers[].paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.createdCustomers[].addressId` | string | Yes | - | format: uuid |
| `data.createdCustomers[].creditInfoId` | string | Yes | - | format: uuid |
| `data.createdCustomers[].insuranceId` | string | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/docs/search

`ark.search_docs`

Searches ARK user-facing support docs and developer API/MCP docs.

| Requirement | Value |
| --- | --- |
| Scopes | `docs:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | Yes | - | min length: 2; max length: 200 |
| `query.limit` | integer | No | - | default: 5; min: 1; max: 10 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/docs/search?q=<q>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Documentation search results

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.query` | string | Yes | - | - |
| `data.results` | array<object> | Yes | - | - |
| `data.results[]` | object | Yes | - | - |
| `data.results[].title` | string | Yes | - | - |
| `data.results[].url` | string | Yes | - | - |
| `data.results[].path` | string | Yes | - | - |
| `data.results[].snippet` | string | Yes | - | - |
| `data.results[].score` | number | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/edi/connections

`ark.list_edi_partner_connections`

Lists broker-admin EDI partner connection requests, active assignments, routing identifiers, and shipper-to-customer mappings.

| Requirement | Value |
| --- | --- |
| Scopes | `edi:read` |
| ARK permissions | `canAdminEdi` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.include_requests` | boolean | No | - | default: true |
| `query.include_connections` | boolean | No | - | default: true |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/edi/connections' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

EDI partner connections

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.requests` | array<EdiPartnerRequest> | Yes | - | - |
| `data.requests[]` | EdiPartnerRequest | Yes | - | - |
| `data.requests[].id` | string | Yes | - | format: uuid |
| `data.requests[].organizationId` | string | Yes | - | format: uuid |
| `data.requests[].partnerDisplayName` | string | Yes | - | - |
| `data.requests[].normalizedPartnerKey` | string | Yes | - | - |
| `data.requests[].requestNotes` | string \| null | No | - | - |
| `data.requests[].status` | string | Yes | - | - |
| `data.requests[].requestedBy` | string \| null | No | - | format: uuid |
| `data.requests[].reviewedBy` | string \| null | No | - | format: uuid |
| `data.requests[].reviewedAt` | string \| null | No | - | format: date-time |
| `data.requests[].partnerDefinitionId` | string \| null | No | - | format: uuid |
| `data.requests[].matchedPartnerDisplayName` | string \| null | No | - | - |
| `data.requests[].createdAt` | string | Yes | - | format: date-time |
| `data.requests[].updatedAt` | string | Yes | - | format: date-time |
| `data.connections` | array<EdiPartnerConnection> | Yes | - | - |
| `data.connections[]` | EdiPartnerConnection | Yes | - | - |
| `data.connections[].id` | string | Yes | - | format: uuid |
| `data.connections[].organizationId` | string | Yes | - | format: uuid |
| `data.connections[].partnerDefinitionId` | string \| null | No | - | format: uuid |
| `data.connections[].partnerSlug` | string \| null | No | - | - |
| `data.connections[].partnerDisplayName` | string | Yes | - | - |
| `data.connections[].normalizedPartnerKey` | string | Yes | - | - |
| `data.connections[].partnerKey` | string \| null | No | - | - |
| `data.connections[].templateKey` | string \| null | No | - | - |
| `data.connections[].templateVersion` | string \| null | No | - | - |
| `data.connections[].templateStatus` | string \| null | No | - | - |
| `data.connections[].transportType` | string | Yes | - | - |
| `data.connections[].onboardingStatus` | string | Yes | - | one of: requested, internal_review, testing, active, suspended, error, archived |
| `data.connections[].transportStatus` | string | Yes | - | one of: pending, configured, testing, active, suspended, error |
| `data.connections[].assignmentStatus` | string | Yes | - | one of: active, suspended, archived |
| `data.connections[].requestId` | string \| null | No | - | format: uuid |
| `data.connections[].requestNotes` | string \| null | No | - | - |
| `data.connections[].serverKey` | string \| null | No | - | - |
| `data.connections[].agreementId` | string \| null | No | - | - |
| `data.connections[].connectorId` | string \| null | No | - | - |
| `data.connections[].inboundAs2Identity` | string \| null | No | - | - |
| `data.connections[].outboundAs2Identity` | string \| null | No | - | - |
| `data.connections[].isaSenderId` | string \| null | No | - | - |
| `data.connections[].isaReceiverId` | string \| null | No | - | - |
| `data.connections[].gsSenderId` | string \| null | No | - | - |
| `data.connections[].gsReceiverId` | string \| null | No | - | - |
| `data.connections[].routingDiscriminator` | string \| null | No | - | - |
| `data.connections[].activatedAt` | string \| null | No | - | format: date-time |
| `data.connections[].createdAt` | string | Yes | - | format: date-time |
| `data.connections[].updatedAt` | string | Yes | - | format: date-time |
| `data.connections[].shipperConfigs` | array<EdiShipperConfig> | Yes | - | - |
| `data.connections[].shipperConfigs[]` | EdiShipperConfig | Yes | - | - |
| `data.connections[].shipperConfigs[].id` | string | Yes | - | format: uuid |
| `data.connections[].shipperConfigs[].organizationId` | string | Yes | - | format: uuid |
| `data.connections[].shipperConfigs[].partnerAssignmentId` | string | Yes | - | format: uuid |
| `data.connections[].shipperConfigs[].customerId` | string | Yes | - | format: uuid |
| `data.connections[].shipperConfigs[].customerName` | string | Yes | - | - |
| `data.connections[].shipperConfigs[].shipperDisplayName` | string | Yes | - | - |
| `data.connections[].shipperConfigs[].normalizedShipperIdentifier` | string | Yes | - | - |
| `data.connections[].shipperConfigs[].matchStrategy` | string | Yes | - | one of: shipper_name, reference_number, shipper_name_or_reference |
| `data.connections[].shipperConfigs[].referenceMappings` | array<string> | Yes | - | - |
| `data.connections[].shipperConfigs[].referenceMappings[]` | string | Yes | - | - |
| `data.connections[].shipperConfigs[].overrides` | object | Yes | - | - |
| `data.connections[].shipperConfigs[].isActive` | boolean | Yes | - | - |
| `data.connections[].shipperConfigs[].createdAt` | string | Yes | - | format: date-time |
| `data.connections[].shipperConfigs[].updatedAt` | string | Yes | - | format: date-time |
| `data.counts` | object | Yes | - | - |
| `data.counts.requests` | integer | Yes | - | - |
| `data.counts.connections` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/edi/connections

`ark.request_edi_partner_connection`

Requests or updates an EDI trading-partner setup request for the organization.

| Requirement | Value |
| --- | --- |
| Scopes | `edi:write` |
| ARK permissions | `canAdminEdi` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `partnerDisplayName` | string | Yes | - | min length: 1; max length: 200 |
| `requestNotes` | string \| null | No | - | max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/edi/connections' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "partnerDisplayName": "<partnerDisplayName>"
}'
```

#### Success response shape

EDI partner connection request

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.request` | EdiPartnerRequest | Yes | - | - |
| `data.request.id` | string | Yes | - | format: uuid |
| `data.request.organizationId` | string | Yes | - | format: uuid |
| `data.request.partnerDisplayName` | string | Yes | - | - |
| `data.request.normalizedPartnerKey` | string | Yes | - | - |
| `data.request.requestNotes` | string \| null | No | - | - |
| `data.request.status` | string | Yes | - | - |
| `data.request.requestedBy` | string \| null | No | - | format: uuid |
| `data.request.reviewedBy` | string \| null | No | - | format: uuid |
| `data.request.reviewedAt` | string \| null | No | - | format: date-time |
| `data.request.partnerDefinitionId` | string \| null | No | - | format: uuid |
| `data.request.matchedPartnerDisplayName` | string \| null | No | - | - |
| `data.request.createdAt` | string | Yes | - | format: date-time |
| `data.request.updatedAt` | string | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### PATCH /api/v1/edi/connections/{connectionId}

`ark.update_edi_partner_connection`

Updates an EDI partner connection status, transport identifiers, routing identifiers, and setup notes.

| Requirement | Value |
| --- | --- |
| Scopes | `edi:write` |
| ARK permissions | `canAdminEdi` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.connectionId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `partnerDisplayName` | string | No | - | min length: 1; max length: 200 |
| `requestNotes` | string \| null | No | - | max length: 5000 |
| `onboardingStatus` | string | No | - | one of: requested, internal_review, testing, active, suspended, error, archived |
| `transportStatus` | string | No | - | one of: pending, configured, testing, active, suspended, error |
| `assignmentStatus` | string | No | - | one of: active, suspended, archived |
| `serverKey` | string \| null | No | - | max length: 200 |
| `agreementId` | string \| null | No | - | max length: 200 |
| `connectorId` | string \| null | No | - | max length: 200 |
| `inboundAs2Identity` | string \| null | No | - | max length: 200 |
| `outboundAs2Identity` | string \| null | No | - | max length: 200 |
| `isaSenderId` | string \| null | No | - | max length: 50 |
| `isaReceiverId` | string \| null | No | - | max length: 50 |
| `gsSenderId` | string \| null | No | - | max length: 50 |
| `gsReceiverId` | string \| null | No | - | max length: 50 |
| `routingDiscriminator` | string \| null | No | - | max length: 100 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/edi/connections/<connectionId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated EDI partner connection

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.connection` | EdiPartnerConnection | Yes | - | - |
| `data.connection.id` | string | Yes | - | format: uuid |
| `data.connection.organizationId` | string | Yes | - | format: uuid |
| `data.connection.partnerDefinitionId` | string \| null | No | - | format: uuid |
| `data.connection.partnerSlug` | string \| null | No | - | - |
| `data.connection.partnerDisplayName` | string | Yes | - | - |
| `data.connection.normalizedPartnerKey` | string | Yes | - | - |
| `data.connection.partnerKey` | string \| null | No | - | - |
| `data.connection.templateKey` | string \| null | No | - | - |
| `data.connection.templateVersion` | string \| null | No | - | - |
| `data.connection.templateStatus` | string \| null | No | - | - |
| `data.connection.transportType` | string | Yes | - | - |
| `data.connection.onboardingStatus` | string | Yes | - | one of: requested, internal_review, testing, active, suspended, error, archived |
| `data.connection.transportStatus` | string | Yes | - | one of: pending, configured, testing, active, suspended, error |
| `data.connection.assignmentStatus` | string | Yes | - | one of: active, suspended, archived |
| `data.connection.requestId` | string \| null | No | - | format: uuid |
| `data.connection.requestNotes` | string \| null | No | - | - |
| `data.connection.serverKey` | string \| null | No | - | - |
| `data.connection.agreementId` | string \| null | No | - | - |
| `data.connection.connectorId` | string \| null | No | - | - |
| `data.connection.inboundAs2Identity` | string \| null | No | - | - |
| `data.connection.outboundAs2Identity` | string \| null | No | - | - |
| `data.connection.isaSenderId` | string \| null | No | - | - |
| `data.connection.isaReceiverId` | string \| null | No | - | - |
| `data.connection.gsSenderId` | string \| null | No | - | - |
| `data.connection.gsReceiverId` | string \| null | No | - | - |
| `data.connection.routingDiscriminator` | string \| null | No | - | - |
| `data.connection.activatedAt` | string \| null | No | - | format: date-time |
| `data.connection.createdAt` | string | Yes | - | format: date-time |
| `data.connection.updatedAt` | string | Yes | - | format: date-time |
| `data.connection.shipperConfigs` | array<EdiShipperConfig> | Yes | - | - |
| `data.connection.shipperConfigs[]` | EdiShipperConfig | Yes | - | - |
| `data.connection.shipperConfigs[].id` | string | Yes | - | format: uuid |
| `data.connection.shipperConfigs[].organizationId` | string | Yes | - | format: uuid |
| `data.connection.shipperConfigs[].partnerAssignmentId` | string | Yes | - | format: uuid |
| `data.connection.shipperConfigs[].customerId` | string | Yes | - | format: uuid |
| `data.connection.shipperConfigs[].customerName` | string | Yes | - | - |
| `data.connection.shipperConfigs[].shipperDisplayName` | string | Yes | - | - |
| `data.connection.shipperConfigs[].normalizedShipperIdentifier` | string | Yes | - | - |
| `data.connection.shipperConfigs[].matchStrategy` | string | Yes | - | one of: shipper_name, reference_number, shipper_name_or_reference |
| `data.connection.shipperConfigs[].referenceMappings` | array<string> | Yes | - | - |
| `data.connection.shipperConfigs[].referenceMappings[]` | string | Yes | - | - |
| `data.connection.shipperConfigs[].overrides` | object | Yes | - | - |
| `data.connection.shipperConfigs[].isActive` | boolean | Yes | - | - |
| `data.connection.shipperConfigs[].createdAt` | string | Yes | - | format: date-time |
| `data.connection.shipperConfigs[].updatedAt` | string | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/edi/tenders

`ark.list_edi_tenders`

Lists visible inbound EDI load tenders with customer mapping, load linkage, acknowledgment, decision, and latest status-update context.

| Requirement | Value |
| --- | --- |
| Scopes | `edi:read` |
| ARK permissions | `canViewEdi` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | string | No | - | one of: received, accepted, rejected |
| `query.include_test_environments` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 100; min: 1; max: 200 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/edi/tenders' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

EDI tender list

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.tenders` | array<EdiTenderListItem> | Yes | - | - |
| `data.tenders[]` | EdiTenderListItem | Yes | - | - |
| `data.tenders[].id` | string | Yes | - | format: uuid |
| `data.tenders[].organizationId` | string | Yes | - | - |
| `data.tenders[].transactionId` | string | Yes | - | - |
| `data.tenders[].partnerDefinitionId` | string \| null | No | - | - |
| `data.tenders[].partnerAssignmentId` | string \| null | No | - | - |
| `data.tenders[].environmentProfileId` | string \| null | No | - | - |
| `data.tenders[].partnerKey` | string | Yes | - | - |
| `data.tenders[].templateKey` | string | Yes | - | - |
| `data.tenders[].templateVersion` | string | Yes | - | - |
| `data.tenders[].tenderReference` | string | Yes | - | - |
| `data.tenders[].status` | string | Yes | - | - |
| `data.tenders[].stopCount` | integer | Yes | - | - |
| `data.tenders[].originCity` | string \| null | No | - | - |
| `data.tenders[].originState` | string \| null | No | - | - |
| `data.tenders[].destinationCity` | string \| null | No | - | - |
| `data.tenders[].destinationState` | string \| null | No | - | - |
| `data.tenders[].pickupDate` | string \| null | No | - | - |
| `data.tenders[].expiresAt` | string \| null | No | - | format: date-time |
| `data.tenders[].createdAt` | string | Yes | - | format: date-time |
| `data.tenders[].decisionAt` | string \| null | No | - | format: date-time |
| `data.tenders[].loadId` | string \| null | No | - | format: uuid |
| `data.tenders[].loadNumber` | integer \| null | No | - | - |
| `data.tenders[].canonicalTender` | object | Yes | - | - |
| `data.tenders[].inboundRawPayloadPreview` | string \| null | No | - | - |
| `data.tenders[].acknowledgmentTransactionId` | string | No | - | - |
| `data.tenders[].decisionTransactionId` | string | No | - | - |
| `data.tenders[].latestStatusUpdateTransactionId` | string | No | - | - |
| `data.tenders[].latestStatusUpdateCode` | string \| null | No | - | - |
| `data.tenders[].latestStatusUpdateLabel` | string \| null | No | - | - |
| `data.tenders[].latestStatusUpdateAt` | string \| null | No | - | format: date-time |
| `data.tenders[].latestStatusTransportStatus` | string \| null | No | - | - |
| `data.tenders[].latestStatusMdnStatus` | string \| null | No | - | - |
| `data.tenders[].partnerDisplayName` | string \| null | No | - | - |
| `data.tenders[].mappedCustomerId` | string \| null | No | - | format: uuid |
| `data.tenders[].mappedCustomerName` | string \| null | No | - | - |
| `data.tenders[].mappedShipperConfigId` | string \| null | No | - | - |
| `data.tenders[].mappedShipperDisplayName` | string \| null | No | - | - |
| `data.tenders[].mappedPartnerConnectionId` | string \| null | No | - | - |
| `data.count` | integer | Yes | - | - |
| `data.truncated` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/edi/tenders/{tenderId}/build-load

`ark.build_load_from_edi_tender`

Creates a broker load from an accepted visible EDI tender. Returns structured review-plan details in error.details.plan when customer, team, customer pay, or location resolution needs operator input.

| Requirement | Value |
| --- | --- |
| Scopes | `edi:read`, `loads:write` |
| ARK permissions | `canViewEdi`, `canCreateLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.tenderId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerId` | string | No | Customer ID to use when the EDI shipper mapping is missing or ambiguous. | format: uuid |
| `teamId` | string | No | Visible team ID for the created load. Omit only when the connection has one visible team. | format: uuid |
| `manualCustomerRate` | number \| string \| null | No | Customer rate to use when the EDI tender does not include a trusted customer-pay value. | - |
| `manualCustomerRateExplicitZero` | boolean | No | Set true only when a zero manual customer rate is intentional. | - |
| `reviewedLoadCreateArgs` | object | No | Reviewed load-create argument overrides from the load-review flow. Use only after a review plan is returned. | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/edi/tenders/<tenderId>/build-load' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

EDI tender load build result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.tenderId` | string | Yes | - | format: uuid |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.loadNumber` | integer \| null | Yes | - | - |
| `data.status` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Tender needs review before a load can be created. The response error details include a load-build plan. |

### POST /api/v1/edi/tenders/{tenderId}/decision

`ark.take_edi_tender_action`

Applies an EDI tender decision for a visible tender and queues outbound response work when configured.

| Requirement | Value |
| --- | --- |
| Scopes | `edi:write` |
| ARK permissions | `canTakeEdiTenderAction` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.tenderId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `decision` | string | Yes | - | one of: accept, reject |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/edi/tenders/<tenderId>/decision' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "accept"
}'
```

#### Success response shape

Tender decision result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.tenderId` | string | Yes | - | format: uuid |
| `data.status` | string | Yes | - | - |
| `data.decisionAt` | string | Yes | - | format: date-time |
| `data.decisionTransactionId` | string | No | - | format: uuid |
| `data.outboundDispatchQueued` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/edi/tenders/{tenderId}/status-update

`ark.emit_edi_status_update`

Emits a shipment status update for a visible EDI tender linked to a broker load and queues outbound 214 dispatch work.

| Requirement | Value |
| --- | --- |
| Scopes | `edi:write` |
| ARK permissions | `canTakeEdiTenderAction` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.tenderId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `statusKey` | string | Yes | - | min length: 1; max length: 100 |
| `eventAt` | string | No | - | format: date-time |
| `stopSequenceNumber` | string | No | - | min length: 1; max length: 50 |
| `timeCode` | string | No | - | min length: 1; max length: 10 |
| `appointmentNumber` | string | No | - | min length: 1; max length: 100 |
| `carrierReferenceNumber` | string | No | - | min length: 1; max length: 100 |
| `secondaryCarrierScac` | string | No | - | min length: 1; max length: 20 |
| `proofOfDeliveryName` | string | No | - | min length: 1; max length: 200 |
| `eventLocation` | EmitEdiStatusEventLocation | No | - | - |
| `eventLocation.city` | string | No | - | min length: 1; max length: 100 |
| `eventLocation.state` | string | No | - | min length: 1; max length: 50 |
| `eventLocation.longitude` | string | No | - | min length: 1; max length: 50 |
| `eventLocation.latitude` | string | No | - | min length: 1; max length: 50 |
| `eventLocation.longitudeDirection` | string | No | - | min length: 1; max length: 2 |
| `eventLocation.latitudeDirection` | string | No | - | min length: 1; max length: 2 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/edi/tenders/<tenderId>/status-update' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "statusKey": "<statusKey>"
}'
```

#### Success response shape

EDI status update result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.tenderId` | string | Yes | - | format: uuid |
| `data.transactionId` | string | No | - | format: uuid |
| `data.statusKey` | string | Yes | - | - |
| `data.statusCode` | string | Yes | - | - |
| `data.statusLabel` | string | Yes | - | - |
| `data.duplicateSuppressed` | boolean | Yes | - | - |
| `data.throttled` | boolean | Yes | - | - |
| `data.transportStatus` | string | Yes | - | - |
| `data.dispatchStatus` | string | Yes | - | - |
| `data.mdnStatus` | string | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.outboundDispatchQueued` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/email/custom

`ark.send_custom_email`

Sends a custom ARK TMS email from the organization sender with optional storage or inline attachments.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canViewLoads` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `to` | CustomEmailRecipientField | Yes | - | - |
| `cc` | CustomEmailRecipientField | No | - | - |
| `bcc` | CustomEmailRecipientField | No | - | - |
| `subject` | string | No | - | default: ""; max length: 500 |
| `body` | string | No | - | default: ""; max length: 100000 |
| `htmlBody` | string | No | - | max length: 250000 |
| `replyTo` | CustomEmailReplyTo | No | - | - |
| `storageAttachments` | array<CustomEmailStorageAttachment> | No | - | max items: 25 |
| `storageAttachments[]` | CustomEmailStorageAttachment | No | - | - |
| `storageAttachments[].path` | string | No | - | min length: 1; max length: 2000 |
| `storageAttachments[].name` | string | No | - | min length: 1; max length: 255 |
| `storageAttachments[].type` | string | No | - | min length: 1; max length: 255 |
| `inlineAttachments` | array<CustomEmailInlineAttachment> | No | - | max items: 10 |
| `inlineAttachments[]` | CustomEmailInlineAttachment | No | - | - |
| `inlineAttachments[].name` | string | No | - | min length: 1; max length: 255 |
| `inlineAttachments[].type` | string | No | - | min length: 1; max length: 255 |
| `inlineAttachments[].base64` | string | No | - | min length: 1; max length: 20000000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/email/custom' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "<to>"
}'
```

#### Success response shape

Sent custom email

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SendCustomEmailData | Yes | - | - |
| `data.success` | unknown | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.deliveryMode` | string \| null | Yes | - | one of: direct, queued, null |
| `data.emailMessageId` | string \| null | Yes | - | - |
| `data.providerMessageId` | string \| null | Yes | - | - |
| `data.recipients` | object | Yes | - | - |
| `data.recipients.to` | array<string> | Yes | - | - |
| `data.recipients.to[]` | string | Yes | - | format: email |
| `data.recipients.cc` | array<string> | Yes | - | - |
| `data.recipients.cc[]` | string | Yes | - | format: email |
| `data.recipients.bccCount` | integer | Yes | - | min: 0 |
| `data.subject` | string | Yes | - | - |
| `data.attachmentCount` | integer | Yes | - | min: 0 |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 413 | Request exceeds the supported operation size |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/factoring-companies

`ark.search_factoring_companies`

Searches organization factoring companies so agents can identify carrier payment destinations before updating carrier payment routing.

| Requirement | Value |
| --- | --- |
| Scopes | `factoring:read` |
| ARK permissions | `canViewFactoring` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | No | - | min length: 1; max length: 100 |
| `query.include_deleted` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/factoring-companies' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Factoring company search results

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.items` | array<object> | Yes | - | - |
| `data.items[]` | object | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].name` | string | Yes | - | - |
| `data.items[].notes` | string \| null | Yes | - | - |
| `data.items[].active` | boolean | Yes | - | - |
| `data.items[].deleted` | boolean | Yes | - | - |
| `data.items[].paymentMethod` | string \| null | Yes | - | - |
| `data.items[].paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.items[].billingAddress` | object \| null | Yes | - | - |
| `data.items[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.items[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.pagination` | CursorPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/factoring-companies

`ark.create_factoring_company`

Creates an organization factoring company used for carrier payment routing without returning raw bank or tax values.

| Requirement | Value |
| --- | --- |
| Scopes | `factoring:write` |
| ARK permissions | `canCreateFactoring` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `active` | boolean | No | - | default: true |
| `name` | string | Yes | - | min length: 1; max length: 200 |
| `notes` | string \| null | No | - | max length: 5000 |
| `billingAddress` | FactoringCompanyAddressInput \| null | No | - | - |
| `federalTaxId` | string \| null | No | Sensitive tax ID to set. Use null to clear; value is never returned. | max length: 100 |
| `paymentMethod` | string \| null | No | - | max length: 50 |
| `paymentTermId` | string | Yes | - | format: uuid |
| `bankName` | string \| null | No | - | max length: 100 |
| `bankType` | string \| null | No | - | max length: 50 |
| `bankAccountNum` | string \| null | No | Sensitive bank account number to set. Use null to clear; value is never returned. | max length: 100 |
| `bankRoutingNum` | string \| null | No | Sensitive 9-digit routing number to set. Use null to clear; value is never returned. | max length: 50 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/factoring-companies' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "<name>",
  "paymentTermId": "<paymentTermId>"
}'
```

#### Success response shape

Created factoring company

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.factoringCompany` | object | Yes | - | - |
| `data.factoringCompany.id` | string | Yes | - | format: uuid |
| `data.factoringCompany.name` | string | Yes | - | - |
| `data.factoringCompany.notes` | string \| null | Yes | - | - |
| `data.factoringCompany.active` | boolean | Yes | - | - |
| `data.factoringCompany.deleted` | boolean | Yes | - | - |
| `data.factoringCompany.paymentMethod` | string \| null | Yes | - | - |
| `data.factoringCompany.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.factoringCompany.billingAddressId` | string \| null | Yes | - | format: uuid |
| `data.factoringCompany.sensitiveFields` | object | Yes | - | - |
| `data.factoringCompany.sensitiveFields.federalTaxIdSet` | boolean | Yes | - | - |
| `data.factoringCompany.sensitiveFields.bankAccountNumSet` | boolean | Yes | - | - |
| `data.factoringCompany.sensitiveFields.bankRoutingNumSet` | boolean | Yes | - | - |
| `data.factoringCompany.createdAt` | string \| null | Yes | - | format: date-time |
| `data.factoringCompany.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### DELETE /api/v1/factoring-companies/{factoringCompanyId}

`ark.archive_factoring_company`

Archives an organization factoring company by marking it deleted, matching the website factoring delete action.

| Requirement | Value |
| --- | --- |
| Scopes | `factoring:write` |
| ARK permissions | `canDeleteFactoring` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.factoringCompanyId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/factoring-companies/<factoringCompanyId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Archived factoring company

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.factoringCompanyId` | string | Yes | - | format: uuid |
| `data.archived` | unknown | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### PATCH /api/v1/factoring-companies/{factoringCompanyId}

`ark.update_factoring_company`

Updates an organization factoring company and lets authorized users set or clear sensitive payment fields without echoing them back.

| Requirement | Value |
| --- | --- |
| Scopes | `factoring:write` |
| ARK permissions | `canEditFactoring` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.factoringCompanyId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `active` | boolean | No | - | - |
| `name` | string | No | - | min length: 1; max length: 200 |
| `notes` | string \| null | No | - | max length: 5000 |
| `billingAddress` | FactoringCompanyAddressInput \| null | No | - | - |
| `federalTaxId` | string \| null | No | Sensitive tax ID to set. Use null to clear; value is never returned. | max length: 100 |
| `paymentMethod` | string \| null | No | - | max length: 50 |
| `paymentTermId` | string | No | - | format: uuid |
| `bankName` | string \| null | No | - | max length: 100 |
| `bankType` | string \| null | No | - | max length: 50 |
| `bankAccountNum` | string \| null | No | Sensitive bank account number to set. Use null to clear; value is never returned. | max length: 100 |
| `bankRoutingNum` | string \| null | No | Sensitive 9-digit routing number to set. Use null to clear; value is never returned. | max length: 50 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/factoring-companies/<factoringCompanyId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated factoring company

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.factoringCompany` | object | Yes | - | - |
| `data.factoringCompany.id` | string | Yes | - | format: uuid |
| `data.factoringCompany.name` | string | Yes | - | - |
| `data.factoringCompany.notes` | string \| null | Yes | - | - |
| `data.factoringCompany.active` | boolean | Yes | - | - |
| `data.factoringCompany.deleted` | boolean | Yes | - | - |
| `data.factoringCompany.paymentMethod` | string \| null | Yes | - | - |
| `data.factoringCompany.paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.factoringCompany.billingAddressId` | string \| null | Yes | - | format: uuid |
| `data.factoringCompany.sensitiveFields` | object | Yes | - | - |
| `data.factoringCompany.sensitiveFields.federalTaxIdSet` | boolean | Yes | - | - |
| `data.factoringCompany.sensitiveFields.bankAccountNumSet` | boolean | Yes | - | - |
| `data.factoringCompany.sensitiveFields.bankRoutingNumSet` | boolean | Yes | - | - |
| `data.factoringCompany.createdAt` | string \| null | Yes | - | format: date-time |
| `data.factoringCompany.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/factoring-companies/import

`ark.import_factoring_companies`

Validates and imports factoring companies from parsed CSV rows, resolving payment terms by days and discount for the organization.

| Requirement | Value |
| --- | --- |
| Scopes | `factoring:write` |
| ARK permissions | `canCreateFactoring` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `rows` | array<ImportFactoringCompanyRow> | Yes | - | min items: 1; max items: 1000 |
| `rows[]` | ImportFactoringCompanyRow | Yes | Parsed CSV row for factoring company import. | - |
| `rows[].name` | string | Yes | - | min length: 1; max length: 200 |
| `rows[].notes` | string \| null | No | - | max length: 5000 |
| `rows[].active` | boolean | No | - | default: true |
| `rows[].billingAddress` | string | No | - | max length: 500 |
| `rows[].billingAddress2` | string | No | - | max length: 500 |
| `rows[].billingCity` | string | No | - | max length: 200 |
| `rows[].billingState` | string | No | - | max length: 20 |
| `rows[].billingZip` | string | No | - | max length: 30 |
| `rows[].billingPhone` | string | No | - | max length: 50 |
| `rows[].billingEmail` | string \| null | No | Email address or semicolon/comma-separated emails. | - |
| `rows[].federalTaxId` | string | No | Sensitive tax ID to store encrypted. Value is never returned. | max length: 100 |
| `rows[].paymentMethod` | string | No | - | max length: 50 |
| `rows[].paymentTermDays` | integer | No | Payment term day count. The import links a matching organization payment term when days and discount match. | - |
| `rows[].paymentTermDiscount` | number | No | - | default: 0 |
| `rows[].bankName` | string | No | - | max length: 100 |
| `rows[].bankType` | string | No | - | max length: 50 |
| `rows[].bankAccountNum` | string | No | Sensitive bank account number to store encrypted. Value is never returned. | max length: 100 |
| `rows[].bankRoutingNum` | string | No | Sensitive bank routing number. Formatting characters are accepted; stored encrypted after validation. | max length: 50 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/factoring-companies/import' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "name": "<name>"
    }
  ]
}'
```

#### Success response shape

Factoring company import result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ImportFactoringCompaniesResult | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.totalRows` | integer | Yes | - | min: 0 |
| `data.successCount` | integer | Yes | - | min: 0 |
| `data.errorCount` | integer | Yes | - | min: 0 |
| `data.skippedCount` | integer | Yes | - | min: 0 |
| `data.errors` | array<ImportFactoringCompanyError> | Yes | - | - |
| `data.errors[]` | ImportFactoringCompanyError | Yes | - | - |
| `data.errors[].row` | integer | Yes | - | min: 1 |
| `data.errors[].field` | string | Yes | - | - |
| `data.errors[].value` | string | Yes | - | - |
| `data.errors[].message` | string | Yes | - | - |
| `data.createdFactoringCompanies` | array<ImportedFactoringCompanySummary> | Yes | - | - |
| `data.createdFactoringCompanies[]` | ImportedFactoringCompanySummary | Yes | - | - |
| `data.createdFactoringCompanies[].row` | integer | Yes | - | min: 1 |
| `data.createdFactoringCompanies[].factoringCompanyId` | string | Yes | - | format: uuid |
| `data.createdFactoringCompanies[].name` | string | Yes | - | - |
| `data.createdFactoringCompanies[].billingAddressId` | string \| null | Yes | - | format: uuid |
| `data.createdFactoringCompanies[].paymentTermId` | string \| null | Yes | - | format: uuid |
| `data.createdFactoringCompanies[].paymentTermMatched` | boolean \| null | Yes | - | - |
| `data.createdFactoringCompanies[].sensitiveFields` | object | Yes | - | - |
| `data.createdFactoringCompanies[].sensitiveFields.federalTaxIdSet` | boolean | Yes | - | - |
| `data.createdFactoringCompanies[].sensitiveFields.bankAccountNumSet` | boolean | Yes | - | - |
| `data.createdFactoringCompanies[].sensitiveFields.bankRoutingNumSet` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/integrations/{provider}/settings

`ark.get_integration_settings`

Returns safe non-secret organization integration settings, active state, and credential presence for a provider setup panel.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.provider` | string | Yes | Integration provider. | one of: ark_tracking, dat, highway, macropoint, mycarrierportal, rmis, sylectus, truckertools |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/integrations/<provider>/settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Integration settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | IntegrationSettingsResult | Yes | - | - |
| `data.provider` | IntegrationSettingsProvider | Yes | - | one of: ark_tracking, dat, highway, macropoint, mycarrierportal, rmis, sylectus, truckertools |
| `data.active` | boolean | Yes | - | - |
| `data.configured` | boolean | Yes | - | - |
| `data.config` | object | Yes | - | - |
| `data.credentials` | IntegrationSettingsCredentials | Yes | - | - |
| `data.credentials.clientIdPresent` | boolean | Yes | - | - |
| `data.credentials.clientSecretPresent` | boolean | Yes | - | - |
| `data.credentials.apiKeyPresent` | boolean | Yes | - | - |
| `data.credentials.refreshTokenPresent` | boolean | Yes | - | - |
| `data.credentials.expiresAt` | string \| null | Yes | - | format: date-time |
| `data.credentials.refreshTokenExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.metadata` | IntegrationSettingsMetadata | Yes | - | - |
| `data.metadata.createdAt` | string \| null | Yes | - | format: date-time |
| `data.metadata.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.metadata.mockMode` | boolean | No | - | - |
| `data.metadata.effectiveEnvironment` | string | No | - | - |
| `data.metadata.environmentLocked` | boolean | No | - | - |
| `data.metadata.availableEnvironments` | array<string> | No | - | - |
| `data.metadata.availableEnvironments[]` | string | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/integrations/{provider}/settings

`ark.update_integration_settings`

Updates organization-level ARK Tracking, DAT, Sylectus, MacroPoint, TruckerTools, MyCarrierPortal, RMIS, or Highway settings and credentials.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.provider` | string | Yes | Integration provider. | one of: ark_tracking, dat, highway, macropoint, mycarrierportal, rmis, sylectus, truckertools |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | IntegrationSettingsProvider | Yes | - | one of: ark_tracking, dat, highway, macropoint, mycarrierportal, rmis, sylectus, truckertools |
| `enabled` | boolean | No | - | - |
| `clientId` | string | No | - | max length: 200 |
| `clientSecret` | string | No | - | max length: 2000 |
| `apiKey` | string | No | - | max length: 2000 |
| `config` | object | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/integrations/<provider>/settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "ark_tracking"
}'
```

#### Success response shape

Updated integration settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateIntegrationSettingsResult | Yes | - | - |
| `data.provider` | IntegrationSettingsProvider | Yes | - | one of: ark_tracking, dat, highway, macropoint, mycarrierportal, rmis, sylectus, truckertools |
| `data.active` | boolean | Yes | - | - |
| `data.configured` | boolean | Yes | - | - |
| `data.config` | object | Yes | - | - |
| `data.credentials` | IntegrationSettingsCredentials | Yes | - | - |
| `data.credentials.clientIdPresent` | boolean | Yes | - | - |
| `data.credentials.clientSecretPresent` | boolean | Yes | - | - |
| `data.credentials.apiKeyPresent` | boolean | Yes | - | - |
| `data.credentials.refreshTokenPresent` | boolean | Yes | - | - |
| `data.credentials.expiresAt` | string \| null | Yes | - | format: date-time |
| `data.credentials.refreshTokenExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.metadata` | IntegrationSettingsMetadata | Yes | - | - |
| `data.metadata.createdAt` | string \| null | Yes | - | format: date-time |
| `data.metadata.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.metadata.mockMode` | boolean | No | - | - |
| `data.metadata.effectiveEnvironment` | string | No | - | - |
| `data.metadata.environmentLocked` | boolean | No | - | - |
| `data.metadata.availableEnvironments` | array<string> | No | - | - |
| `data.metadata.availableEnvironments[]` | string | No | - | - |
| `data.updatedFields` | array<string> | Yes | - | - |
| `data.updatedFields[]` | string | Yes | - | - |
| `data.credentialFieldsChanged` | array<string> | Yes | - | - |
| `data.credentialFieldsChanged[]` | string | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.validation` | unknown | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 503 | External provider or worker queue could not be reached |

### GET /api/v1/integrations/active

`ark.list_active_integrations`

Lists active integration providers for the organization so scripts and agents can decide which provider workflows are available.

| Requirement | Value |
| --- | --- |
| Scopes | `context:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/integrations/active' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Active integrations

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | ListActiveIntegrationsPayload | Yes | - | - |
| `data.organizationId` | string | Yes | - | format: uuid |
| `data.providers` | array<string> | Yes | - | - |
| `data.providers[]` | string | Yes | - | - |
| `data.integrations` | array<ActiveIntegration> | Yes | - | - |
| `data.integrations[]` | ActiveIntegration | Yes | - | - |
| `data.integrations[].provider` | string | Yes | - | - |
| `data.integrations[].active` | boolean | Yes | - | one of: true |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/integrations/project44/settings

`ark.get_project44_settings`

Returns project44 forwarding settings, enablement state, and platform credential health for tenant-admin integration troubleshooting.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/integrations/project44/settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Project44 settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Project44SettingsPayload | Yes | - | - |
| `data.provider` | string | Yes | - | one of: project44 |
| `data.enabled` | boolean | Yes | - | - |
| `data.platformCredentialsConfigured` | boolean | Yes | - | - |
| `data.platformConfigHealth` | Project44PlatformConfigHealth | Yes | - | - |
| `data.platformConfigHealth.configured` | boolean | Yes | - | - |
| `data.platformConfigHealth.distributedTokenCacheConfigured` | boolean | Yes | - | - |
| `data.platformConfigHealth.missingOrInvalid` | array<string> | Yes | - | - |
| `data.platformConfigHealth.missingOrInvalid[]` | string | Yes | - | - |
| `data.platformConfigHealth.warnings` | array<string> | Yes | - | - |
| `data.platformConfigHealth.warnings[]` | string | Yes | - | - |
| `data.platformConfigHealth.environment` | string | No | - | - |
| `data.platformConfigHealth.region` | string | No | - | - |
| `data.platformConfigHealth.baseUrl` | string | No | - | - |
| `data.canEditProject44CustomerMapping` | boolean | Yes | - | - |
| `data.config` | Project44Config | Yes | - | - |
| `data.config.defaultShipmentIdentifierType` | string | Yes | - | one of: BILL_OF_LADING, ORDER |
| `data.config.defaultShipmentIdentifierSource` | string | Yes | - | one of: bill_of_lading, pickup_number, purchase_order_number, load_number |
| `data.config.positionThrottleSeconds` | integer | Yes | - | min: 1 |
| `data.config.carrierIdentifierType` | string | Yes | - | one of: SCAC, DOT_NUMBER, MC_NUMBER, P44_EU, SYSTEM, P44_GLOBAL, VAT |
| `data.config.carrierIdentifierValue` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### PATCH /api/v1/integrations/project44/settings

`ark.update_project44_settings`

Updates project44 forwarding enablement and organization-level shipment identifier settings.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `enabled` | boolean | Yes | - | - |
| `config` | object | No | - | - |
| `config.defaultShipmentIdentifierType` | string | No | - | one of: BILL_OF_LADING, ORDER |
| `config.defaultShipmentIdentifierSource` | string | No | - | one of: bill_of_lading, pickup_number, purchase_order_number, load_number |
| `config.positionThrottleSeconds` | integer | No | - | min: 1 |
| `config.carrierIdentifierType` | string | No | - | one of: SCAC, DOT_NUMBER, MC_NUMBER, P44_EU |
| `config.carrierIdentifierValue` | string | No | - | max length: 200 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/integrations/project44/settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'
```

#### Success response shape

Updated project44 settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UpdateProject44SettingsPayload | Yes | - | - |
| `data.provider` | string | Yes | - | one of: project44 |
| `data.enabled` | boolean | Yes | - | - |
| `data.platformCredentialsConfigured` | boolean | Yes | - | - |
| `data.platformConfigHealth` | Project44PlatformConfigHealth | Yes | - | - |
| `data.platformConfigHealth.configured` | boolean | Yes | - | - |
| `data.platformConfigHealth.distributedTokenCacheConfigured` | boolean | Yes | - | - |
| `data.platformConfigHealth.missingOrInvalid` | array<string> | Yes | - | - |
| `data.platformConfigHealth.missingOrInvalid[]` | string | Yes | - | - |
| `data.platformConfigHealth.warnings` | array<string> | Yes | - | - |
| `data.platformConfigHealth.warnings[]` | string | Yes | - | - |
| `data.platformConfigHealth.environment` | string | No | - | - |
| `data.platformConfigHealth.region` | string | No | - | - |
| `data.platformConfigHealth.baseUrl` | string | No | - | - |
| `data.canEditProject44CustomerMapping` | boolean | Yes | - | - |
| `data.config` | Project44Config | Yes | - | - |
| `data.config.defaultShipmentIdentifierType` | string | Yes | - | one of: BILL_OF_LADING, ORDER |
| `data.config.defaultShipmentIdentifierSource` | string | Yes | - | one of: bill_of_lading, pickup_number, purchase_order_number, load_number |
| `data.config.positionThrottleSeconds` | integer | Yes | - | min: 1 |
| `data.config.carrierIdentifierType` | string | Yes | - | one of: SCAC, DOT_NUMBER, MC_NUMBER, P44_EU, SYSTEM, P44_GLOBAL, VAT |
| `data.config.carrierIdentifierValue` | string | Yes | - | - |
| `data.updatedFields` | array<string> | Yes | - | - |
| `data.updatedFields[]` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/integrations/project44/test

`ark.test_project44_connection`

Validates project44 platform credentials by fetching an access token. Forced refreshes consume project44 token generation quota.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required because this operation makes an external provider call. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `forceRefresh` | boolean | No | - | default: true |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/integrations/project44/test' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Project44 connection test result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | TestProject44ConnectionPayload | Yes | - | - |
| `data.ok` | boolean | Yes | - | one of: true |
| `data.provider` | string | Yes | - | one of: project44 |
| `data.tokenType` | string | Yes | - | - |
| `data.expiresAt` | string | Yes | - | format: date-time |
| `data.forceRefresh` | boolean | Yes | - | - |
| `data.warning` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### GET /api/v1/integrations/quickbooks/carrier-mappings

`ark.list_quickbooks_carrier_mappings`

Lists ARK carriers and their QuickBooks vendor mapping state for setup, unmapped-entity cleanup, and sync troubleshooting.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.mapping_status` | QuickBooksMappingStatus | No | - | - |
| `query.search` | string | No | Searches carrier name, MC number, and DOT number. | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/integrations/quickbooks/carrier-mappings' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

QuickBooks carrier mappings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ListQuickBooksMappingsResult | Yes | - | - |
| `data.type` | string | Yes | - | one of: customer, carrier |
| `data.mappings` | array<QuickBooksEntityMapping> | Yes | - | - |
| `data.mappings[]` | QuickBooksEntityMapping | Yes | - | - |
| `data.mappings[].entity` | QuickBooksMappingEntity | Yes | - | - |
| `data.mappings[].entity.id` | string | Yes | - | - |
| `data.mappings[].entity.name` | string \| null | Yes | - | - |
| `data.mappings[].entity.mcNumber` | string \| null | No | - | - |
| `data.mappings[].entity.dotNumber` | string \| null | No | - | - |
| `data.mappings[].qboEntityId` | string \| null | Yes | - | - |
| `data.mappings[].mapped` | boolean | Yes | - | - |
| `data.mappings[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.totalCount` | integer | Yes | - | - |
| `data.pagination` | QuickBooksMappingsPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |
| `data.generatedAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### PATCH /api/v1/integrations/quickbooks/carrier-mappings

`ark.update_quickbooks_carrier_mappings`

Updates or clears ARK carrier to QuickBooks vendor mappings using the same conflict checks as the QuickBooks settings UI.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `mappings` | array<QuickBooksMappingChange> | Yes | - | min items: 1; max items: 500 |
| `mappings[]` | QuickBooksMappingChange | Yes | - | - |
| `mappings[].tmsEntityId` | string | Yes | - | format: uuid |
| `mappings[].qboEntityId` | string \| null | Yes | - | min length: 1; max length: 100 |
| `mappings[].previousQboEntityId` | string \| null | No | - | min length: 1; max length: 100 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/integrations/quickbooks/carrier-mappings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "mappings": [
    {
      "tmsEntityId": "<tmsEntityId>",
      "qboEntityId": "<qboEntityId>"
    }
  ]
}'
```

#### Success response shape

Updated QuickBooks carrier mappings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateQuickBooksMappingsResult | Yes | - | - |
| `data.type` | string | Yes | - | one of: customer, carrier |
| `data.requestedCount` | integer | Yes | - | - |
| `data.savedCount` | integer | Yes | - | - |
| `data.mappedCount` | integer | Yes | - | - |
| `data.clearedCount` | integer | Yes | - | - |
| `data.entityIds` | array<string> | Yes | - | - |
| `data.entityIds[]` | string | Yes | - | format: uuid |
| `data.qboEntityIds` | array<string> | Yes | - | - |
| `data.qboEntityIds[]` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/integrations/quickbooks/customer-mappings

`ark.list_quickbooks_customer_mappings`

Lists ARK customers and their QuickBooks customer mapping state for setup, unmapped-entity cleanup, and sync troubleshooting.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.mapping_status` | QuickBooksMappingStatus | No | - | - |
| `query.search` | string | No | - | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/integrations/quickbooks/customer-mappings' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

QuickBooks customer mappings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ListQuickBooksMappingsResult | Yes | - | - |
| `data.type` | string | Yes | - | one of: customer, carrier |
| `data.mappings` | array<QuickBooksEntityMapping> | Yes | - | - |
| `data.mappings[]` | QuickBooksEntityMapping | Yes | - | - |
| `data.mappings[].entity` | QuickBooksMappingEntity | Yes | - | - |
| `data.mappings[].entity.id` | string | Yes | - | - |
| `data.mappings[].entity.name` | string \| null | Yes | - | - |
| `data.mappings[].entity.mcNumber` | string \| null | No | - | - |
| `data.mappings[].entity.dotNumber` | string \| null | No | - | - |
| `data.mappings[].qboEntityId` | string \| null | Yes | - | - |
| `data.mappings[].mapped` | boolean | Yes | - | - |
| `data.mappings[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.totalCount` | integer | Yes | - | - |
| `data.pagination` | QuickBooksMappingsPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |
| `data.generatedAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### PATCH /api/v1/integrations/quickbooks/customer-mappings

`ark.update_quickbooks_customer_mappings`

Updates or clears ARK customer to QuickBooks customer mappings using the same conflict checks as the QuickBooks settings UI.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `mappings` | array<QuickBooksMappingChange> | Yes | - | min items: 1; max items: 500 |
| `mappings[]` | QuickBooksMappingChange | Yes | - | - |
| `mappings[].tmsEntityId` | string | Yes | - | format: uuid |
| `mappings[].qboEntityId` | string \| null | Yes | - | min length: 1; max length: 100 |
| `mappings[].previousQboEntityId` | string \| null | No | - | min length: 1; max length: 100 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/integrations/quickbooks/customer-mappings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "mappings": [
    {
      "tmsEntityId": "<tmsEntityId>",
      "qboEntityId": "<qboEntityId>"
    }
  ]
}'
```

#### Success response shape

Updated QuickBooks customer mappings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateQuickBooksMappingsResult | Yes | - | - |
| `data.type` | string | Yes | - | one of: customer, carrier |
| `data.requestedCount` | integer | Yes | - | - |
| `data.savedCount` | integer | Yes | - | - |
| `data.mappedCount` | integer | Yes | - | - |
| `data.clearedCount` | integer | Yes | - | - |
| `data.entityIds` | array<string> | Yes | - | - |
| `data.entityIds[]` | string | Yes | - | format: uuid |
| `data.qboEntityIds` | array<string> | Yes | - | - |
| `data.qboEntityIds[]` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/integrations/quickbooks/reference-data

`ark.list_quickbooks_reference_data`

Lists QuickBooks accounts, customers, custom fields, payment accounts, items, terms, tax codes, or vendors for accounting setup, mapping, and sync troubleshooting.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.resource` | QuickBooksReferenceResource | Yes | - | - |
| `query.search` | string | No | - | min length: 1; max length: 100 |
| `query.max_results` | integer | No | - | default: 100; min: 1; max: 1000 |
| `query.account_type` | string | No | - | max length: 100 |
| `query.classification` | string | No | - | max length: 100 |
| `query.category` | string | No | - | one of: vendor_expense |
| `query.item_type` | string | No | - | one of: Service, Inventory, NonInventory |
| `query.include_config` | boolean | No | - | default: false |
| `query.account_usage` | string | No | - | one of: carrier, customer; default: "carrier" |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/integrations/quickbooks/reference-data?resource=<resource>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

QuickBooks reference data

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ListQuickBooksReferenceDataResult | Yes | - | - |
| `data.resource` | QuickBooksReferenceResource | Yes | - | one of: accounts, customers, custom_fields, payment_accounts, items, terms, tax_codes, vendors |
| `data.records` | array<object> | Yes | - | - |
| `data.records[]` | object | Yes | - | - |
| `data.total` | integer | Yes | - | - |
| `data.maxResults` | integer | Yes | - | - |
| `data.hasMore` | boolean | Yes | - | - |
| `data.query` | QuickBooksReferenceDataQuery | Yes | - | - |
| `data.query.qboQuery` | string | Yes | - | - |
| `data.query.endpoint` | string | Yes | - | - |
| `data.config` | QuickBooksReferenceDataConfig \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 502 | External provider or worker queue could not be reached |

### PATCH /api/v1/integrations/quickbooks/settings

`ark.update_quickbooks_settings`

Updates QuickBooks accounting settings, charge mappings, tax-code mappings, payment accounts, terms, and custom field mappings while preserving connected tokens.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:write` |
| ARK permissions | `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `autoSync` | boolean | No | - | - |
| `customerOnBill` | boolean | No | - | - |
| `printChecksFromQuickBooks` | boolean | No | - | - |
| `bankAccountId` | string | No | - | max length: 100 |
| `customerPaymentAccountId` | string | No | - | max length: 100 |
| `invoiceTermsId` | string | No | - | max length: 100 |
| `defaultBillingTermsId` | string | No | - | max length: 100 |
| `vendorMapping` | object | No | - | - |
| `customerMapping` | object | No | - | - |
| `taxCodeMapping` | object | No | - | - |
| `taxCodeMapping.customer` | object | No | - | - |
| `taxCodeMapping.vendor` | object | No | - | - |
| `customFields` | object | No | - | - |
| `customFields.bills` | object | No | - | - |
| `customFields.bills.loadNumberFieldId` | string | No | - | max length: 100 |
| `customFields.bills.loadNumberFieldName` | string | No | - | max length: 100 |
| `customFields.bills.referenceNumberFieldId` | string | No | - | max length: 100 |
| `customFields.bills.referenceNumberFieldName` | string | No | - | max length: 100 |
| `customFields.invoices` | object | No | - | - |
| `customFields.invoices.loadNumberFieldId` | string | No | - | max length: 100 |
| `customFields.invoices.loadNumberFieldName` | string | No | - | max length: 100 |
| `customFields.invoices.referenceNumberFieldId` | string | No | - | max length: 100 |
| `customFields.invoices.referenceNumberFieldName` | string | No | - | max length: 100 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/integrations/quickbooks/settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated QuickBooks settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateQuickBooksSettingsResult | Yes | - | - |
| `data.provider` | unknown | Yes | - | - |
| `data.config` | object | Yes | - | - |
| `data.updatedFields` | array<string> | Yes | - | - |
| `data.updatedFields[]` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/integrations/quickbooks/status

`ark.get_quickbooks_status`

Returns safe QuickBooks connection health, token expiry state, realm presence, missing requirements, and integration configuration for accounting workflow decisions.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/integrations/quickbooks/status' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

QuickBooks status

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | QuickBooksStatus | Yes | - | - |
| `data.provider` | unknown | Yes | - | - |
| `data.isConfigured` | boolean | Yes | - | - |
| `data.isConnected` | boolean | Yes | - | - |
| `data.active` | boolean | Yes | - | - |
| `data.connectionState` | QuickBooksConnectionState | Yes | - | one of: connected, not_configured, inactive, missing_credentials, needs_refresh, expired |
| `data.needsReconnect` | boolean | Yes | - | - |
| `data.requiresRefresh` | boolean | Yes | - | - |
| `data.hasRealmId` | boolean | Yes | - | - |
| `data.hasAccessToken` | boolean | Yes | Presence-only token indicator. Token values are never returned. | - |
| `data.hasRefreshToken` | boolean | Yes | Presence-only token indicator. Token values are never returned. | - |
| `data.realmId` | string \| null | Yes | - | - |
| `data.accessTokenExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.refreshTokenExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.accessTokenExpired` | boolean | Yes | - | - |
| `data.refreshTokenExpired` | boolean | Yes | - | - |
| `data.accessTokenExpiresSoon` | boolean | Yes | - | - |
| `data.missingRequirements` | array<string> | Yes | - | - |
| `data.missingRequirements[]` | string | Yes | - | - |
| `data.config` | object \| null | Yes | - | - |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/integrations/quickbooks/sync-jobs

`ark.list_quickbooks_sync_jobs`

Lists visible QuickBooks sync jobs with status, operation, retryability, error, active-sync, and item context for accounting workflow monitoring.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.status` | string | No | - | one of: queued, enqueue_failed, processing, retrying, succeeded, partial_failed, failed, stuck, canceled |
| `query.status_group` | string | No | - | one of: actionable, active, terminal, all; default: "actionable" |
| `query.operation` | QuickBooksSyncOperation | No | - | - |
| `query.include_items` | boolean | No | - | default: true |
| `query.search` | string | No | Search across job IDs, operation, status, error text, item labels, and QuickBooks entity IDs. | min length: 1; max length: 100 |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/integrations/quickbooks/sync-jobs' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

QuickBooks sync jobs

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.jobs` | array<QuickBooksSyncJobSummary> | Yes | - | - |
| `data.jobs[]` | QuickBooksSyncJobSummary | Yes | - | - |
| `data.jobs[].jobId` | string | Yes | - | format: uuid |
| `data.jobs[].operation` | QuickBooksSyncOperation | Yes | - | one of: customer_invoice_create, customer_invoice_mark_paid, customer_payment_create, carrier_bill_create, carrier_bill_mark_paid, carrier_settlement_create, customer_invoice_update, carrier_bill_update |
| `data.jobs[].status` | QuickBooksSyncJobStatus | Yes | - | one of: queued, enqueue_failed, processing, retrying, succeeded, partial_failed, failed, stuck, canceled |
| `data.jobs[].retryable` | boolean | Yes | - | - |
| `data.jobs[].requestedFrom` | string \| null | Yes | - | - |
| `data.jobs[].qstashMessageId` | string \| null | Yes | - | - |
| `data.jobs[].attemptCount` | integer | Yes | - | - |
| `data.jobs[].maxAttempts` | integer | Yes | - | - |
| `data.jobs[].totalItems` | integer | Yes | - | - |
| `data.jobs[].succeededItems` | integer | Yes | - | - |
| `data.jobs[].failedItems` | integer | Yes | - | - |
| `data.jobs[].skippedItems` | integer | Yes | - | - |
| `data.jobs[].lastError` | string \| null | Yes | - | - |
| `data.jobs[].lastErrorCode` | string \| null | Yes | - | - |
| `data.jobs[].nextRetryAt` | string \| null | Yes | - | format: date-time |
| `data.jobs[].heartbeatAt` | string \| null | Yes | - | format: date-time |
| `data.jobs[].startedAt` | string \| null | Yes | - | format: date-time |
| `data.jobs[].completedAt` | string \| null | Yes | - | format: date-time |
| `data.jobs[].createdBy` | string \| null | Yes | - | - |
| `data.jobs[].createdAt` | string | Yes | - | format: date-time |
| `data.jobs[].updatedAt` | string | Yes | - | format: date-time |
| `data.jobs[].payload` | object | Yes | - | - |
| `data.jobs[].result` | object | Yes | - | - |
| `data.jobs[].items` | array<QuickBooksSyncJobItemSummary> | No | - | - |
| `data.jobs[].items[]` | QuickBooksSyncJobItemSummary | No | - | - |
| `data.jobs[].items[].itemId` | string | No | - | format: uuid |
| `data.jobs[].items[].operation` | QuickBooksSyncOperation | No | - | one of: customer_invoice_create, customer_invoice_mark_paid, customer_payment_create, carrier_bill_create, carrier_bill_mark_paid, carrier_settlement_create, customer_invoice_update, carrier_bill_update |
| `data.jobs[].items[].entityType` | string | No | - | - |
| `data.jobs[].items[].entityId` | string \| null | No | - | - |
| `data.jobs[].items[].entityKey` | string \| null | No | - | - |
| `data.jobs[].items[].displayLabel` | string \| null | No | - | - |
| `data.jobs[].items[].status` | string | No | - | one of: queued, processing, succeeded, skipped, retrying, failed, blocked |
| `data.jobs[].items[].attemptCount` | integer | No | - | - |
| `data.jobs[].items[].qboEntityType` | string \| null | No | - | - |
| `data.jobs[].items[].qboEntityId` | string \| null | No | - | - |
| `data.jobs[].items[].errorCode` | string \| null | No | - | - |
| `data.jobs[].items[].errorMessage` | string \| null | No | - | - |
| `data.jobs[].items[].actionMessage` | string \| null | No | - | - |
| `data.jobs[].items[].startedAt` | string \| null | No | - | format: date-time |
| `data.jobs[].items[].completedAt` | string \| null | No | - | format: date-time |
| `data.jobs[].items[].createdAt` | string | No | - | format: date-time |
| `data.jobs[].items[].updatedAt` | string | No | - | format: date-time |
| `data.activeSync` | QuickBooksSyncActiveSyncSummary | Yes | - | - |
| `data.activeSync.count` | integer | Yes | - | - |
| `data.activeSync.hasActiveSync` | boolean | Yes | - | - |
| `data.pagination` | QuickBooksSyncJobPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | - |
| `data.generatedAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/integrations/quickbooks/sync-jobs

`ark.queue_quickbooks_sync_job`

Queues a QuickBooks sync workflow for invoices, payments, bills, settlements, or update syncs after validating visibility and operation-specific inputs.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `operation` | QuickBooksSyncOperation | Yes | - | one of: customer_invoice_create, customer_invoice_mark_paid, customer_payment_create, carrier_bill_create, carrier_bill_mark_paid, carrier_settlement_create, customer_invoice_update, carrier_bill_update |
| `paymentIds` | array<string> | No | - | min items: 1; max items: 50 |
| `paymentIds[]` | string | No | - | format: uuid |
| `depositToAccountId` | string | No | - | min length: 1; max length: 100 |
| `settlementNumbers` | array<integer> | No | - | min items: 1; max items: 10 |
| `settlementNumbers[]` | integer | No | - | min: 1 |
| `referenceNumber` | string | No | - | min length: 1; max length: 100 |
| `paidDate` | string | No | - | - |
| `loadId` | string | No | - | format: uuid |
| `paymentId` | string | No | - | format: uuid |
| `dispatchId` | string | No | - | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/integrations/quickbooks/sync-jobs' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "customer_invoice_create"
}'
```

#### Success response shape

Queued QuickBooks sync job

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | QueueQuickBooksSyncJobResult | Yes | - | - |
| `data.operation` | QuickBooksSyncOperation | Yes | - | one of: customer_invoice_create, customer_invoice_mark_paid, customer_payment_create, carrier_bill_create, carrier_bill_mark_paid, carrier_settlement_create, customer_invoice_update, carrier_bill_update |
| `data.queued` | boolean | Yes | - | - |
| `data.status` | string | Yes | - | one of: queued, skipped |
| `data.jobId` | string \| null | Yes | - | format: uuid |
| `data.totalItems` | integer | Yes | - | - |
| `data.requestedItemCount` | integer | Yes | - | - |
| `data.queuedItemCount` | integer | Yes | - | - |
| `data.skippedPaymentIds` | array<string> | Yes | - | - |
| `data.skippedPaymentIds[]` | string | Yes | - | format: uuid |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 413 | Request exceeds the supported operation size |
| 502 | External provider or worker queue could not be reached |

### POST /api/v1/integrations/quickbooks/sync-jobs/{jobId}/retry

`ark.retry_quickbooks_sync_job`

Retries a visible failed QuickBooks sync job by resetting retryable items, requeueing the worker, and recording a lifecycle event.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.jobId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/integrations/quickbooks/sync-jobs/<jobId>/retry' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Retried QuickBooks sync job

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RetryQuickBooksSyncJobResult | Yes | - | - |
| `data.job` | QuickBooksSyncJobSummary | Yes | - | - |
| `data.job.jobId` | string | Yes | - | format: uuid |
| `data.job.operation` | QuickBooksSyncOperation | Yes | - | one of: customer_invoice_create, customer_invoice_mark_paid, customer_payment_create, carrier_bill_create, carrier_bill_mark_paid, carrier_settlement_create, customer_invoice_update, carrier_bill_update |
| `data.job.status` | QuickBooksSyncJobStatus | Yes | - | one of: queued, enqueue_failed, processing, retrying, succeeded, partial_failed, failed, stuck, canceled |
| `data.job.retryable` | boolean | Yes | - | - |
| `data.job.requestedFrom` | string \| null | Yes | - | - |
| `data.job.qstashMessageId` | string \| null | Yes | - | - |
| `data.job.attemptCount` | integer | Yes | - | - |
| `data.job.maxAttempts` | integer | Yes | - | - |
| `data.job.totalItems` | integer | Yes | - | - |
| `data.job.succeededItems` | integer | Yes | - | - |
| `data.job.failedItems` | integer | Yes | - | - |
| `data.job.skippedItems` | integer | Yes | - | - |
| `data.job.lastError` | string \| null | Yes | - | - |
| `data.job.lastErrorCode` | string \| null | Yes | - | - |
| `data.job.nextRetryAt` | string \| null | Yes | - | format: date-time |
| `data.job.heartbeatAt` | string \| null | Yes | - | format: date-time |
| `data.job.startedAt` | string \| null | Yes | - | format: date-time |
| `data.job.completedAt` | string \| null | Yes | - | format: date-time |
| `data.job.createdBy` | string \| null | Yes | - | - |
| `data.job.createdAt` | string | Yes | - | format: date-time |
| `data.job.updatedAt` | string | Yes | - | format: date-time |
| `data.job.payload` | object | Yes | - | - |
| `data.job.result` | object | Yes | - | - |
| `data.job.items` | array<QuickBooksSyncJobItemSummary> | No | - | - |
| `data.job.items[]` | QuickBooksSyncJobItemSummary | No | - | - |
| `data.job.items[].itemId` | string | No | - | format: uuid |
| `data.job.items[].operation` | QuickBooksSyncOperation | No | - | one of: customer_invoice_create, customer_invoice_mark_paid, customer_payment_create, carrier_bill_create, carrier_bill_mark_paid, carrier_settlement_create, customer_invoice_update, carrier_bill_update |
| `data.job.items[].entityType` | string | No | - | - |
| `data.job.items[].entityId` | string \| null | No | - | - |
| `data.job.items[].entityKey` | string \| null | No | - | - |
| `data.job.items[].displayLabel` | string \| null | No | - | - |
| `data.job.items[].status` | string | No | - | one of: queued, processing, succeeded, skipped, retrying, failed, blocked |
| `data.job.items[].attemptCount` | integer | No | - | - |
| `data.job.items[].qboEntityType` | string \| null | No | - | - |
| `data.job.items[].qboEntityId` | string \| null | No | - | - |
| `data.job.items[].errorCode` | string \| null | No | - | - |
| `data.job.items[].errorMessage` | string \| null | No | - | - |
| `data.job.items[].actionMessage` | string \| null | No | - | - |
| `data.job.items[].startedAt` | string \| null | No | - | format: date-time |
| `data.job.items[].completedAt` | string \| null | No | - | format: date-time |
| `data.job.items[].createdAt` | string | No | - | format: date-time |
| `data.job.items[].updatedAt` | string | No | - | format: date-time |
| `data.previousStatus` | QuickBooksSyncJobStatus | Yes | - | one of: queued, enqueue_failed, processing, retrying, succeeded, partial_failed, failed, stuck, canceled |
| `data.resetItemCount` | integer | Yes | - | - |
| `data.messageId` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/load-board/dat/private-network-groups

`ark.list_dat_private_network_groups`

Lists DAT private-network groups available to the current user or organization credentials for load-board posting decisions.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.refresh` | boolean | No | When true, bypasses the short-lived DAT private-network group cache. | default: false |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/load-board/dat/private-network-groups' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

DAT private-network groups

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ListDatPrivateNetworkGroupsResult | Yes | - | - |
| `data.provider` | unknown | Yes | - | - |
| `data.authSource` | string | Yes | - | one of: user, organization |
| `data.groups` | array<DatPrivateNetworkGroup> | Yes | - | - |
| `data.groups[]` | DatPrivateNetworkGroup | Yes | - | - |
| `data.groups[].id` | string | Yes | - | - |
| `data.groups[].reference` | string | Yes | - | - |
| `data.groups[].networkId` | string | Yes | - | - |
| `data.groups[].name` | string | Yes | - | - |
| `data.groups[].contactsCount` | integer | Yes | - | min: 0 |
| `data.groups[].datUsersCount` | integer | Yes | - | min: 0 |
| `data.groups[].datCompaniesCount` | integer | Yes | - | min: 0 |
| `data.cacheStatus` | string | Yes | - | one of: hit, miss, refresh |
| `data.cacheExpiresAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 503 | External provider or worker queue could not be reached |

### GET /api/v1/load-board/postings

`ark.list_load_board_postings`

Lists DAT, Truckstop, and Sylectus posting readiness and summaries for visible load or spot-load IDs.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.source_ids` | string | Yes | Comma-separated load IDs, or spot-load IDs when source_type is spot_load. | - |
| `query.source_type` | string | No | - | one of: load, spot_load; default: "load" |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/load-board/postings?source_ids=<source_ids>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load board postings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.readiness` | object | Yes | - | - |
| `data.summaries` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/load-board/postings

`ark.perform_load_board_action`

Posts, refreshes, updates, or removes load-board postings for DAT, Truckstop, or Sylectus using the existing ARK load-board workflow.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | string | Yes | - | one of: dat, truckstop, sylectus |
| `action` | string | Yes | - | one of: post, refresh, update, remove |
| `sourceIds` | array<string> | Yes | - | min items: 1; max items: 2500 |
| `sourceIds[]` | string | Yes | - | format: uuid |
| `sourceType` | string | No | - | one of: load, spot_load; default: "load" |
| `draftOverridesByLoadId` | object | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/load-board/postings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "dat",
  "action": "post",
  "sourceIds": [
    "<sourceIds>"
  ]
}'
```

#### Success response shape

Load board action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.results` | array<object> | Yes | - | - |
| `data.results[]` | object | Yes | - | - |
| `data.summaries` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/load-board/postings/preview

`ark.get_load_board_posting_preview`

Returns DAT or Sylectus posting defaults and validation context before a load-board post or update action.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.source_id` | string | Yes | Load ID, or spot-load ID when source_type is spot_load. | format: uuid |
| `query.provider` | string | No | - | one of: dat, sylectus; default: "dat" |
| `query.source_type` | string | No | - | one of: load, spot_load; default: "load" |
| `query.mode` | string | No | - | one of: draft, update; default: "draft" |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/load-board/postings/preview?source_id=<source_id>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load board posting preview

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.sourceId` | string | Yes | - | format: uuid |
| `data.sourceType` | string | Yes | - | one of: load, spot_load |
| `data.provider` | string | Yes | - | one of: dat, sylectus |
| `data.mode` | string | Yes | - | one of: draft, update |
| `data.preview` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/load-board/postings/reconcile-preview

`ark.reconcile_load_board_posting_preview`

Persists or clears DAT/Sylectus draft-preview failure records after a load or spot quote is edited.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `sourceId` | string | Yes | - | format: uuid |
| `provider` | string | No | - | one of: dat, sylectus; default: "dat" |
| `sourceType` | string | No | - | one of: load, spot_load; default: "load" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/load-board/postings/reconcile-preview' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceId": "<sourceId>"
}'
```

#### Success response shape

Load board posting preview reconciliation result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.sourceId` | string | Yes | - | format: uuid |
| `data.sourceType` | string | Yes | - | one of: load, spot_load |
| `data.provider` | string | Yes | - | one of: dat, sylectus |
| `data.cleared` | boolean | Yes | - | - |
| `data.persisted` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/load-board/provider-setup

`ark.get_load_board_provider_setup`

Returns the current user DAT and Sylectus setup status, assigned seat identifiers, readiness state, and suggested identifiers used by load-board posting workflows.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.provider` | array<string> | No | Provider to inspect. Repeat this query parameter to inspect multiple providers. | min items: 1; max items: 2 |
| `query.providers` | string | No | Comma-separated provider list. Example: dat,sylectus. | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/load-board/provider-setup' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load board provider setup

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | GetLoadBoardProviderSetupResult | Yes | - | - |
| `data.providers` | array<LoadBoardProviderConnectionStatus> | Yes | - | - |
| `data.providers[]` | LoadBoardProviderConnectionStatus | Yes | - | - |
| `data.canEditCurrentUserSeat` | boolean | Yes | Whether the current user can change their assigned DAT username or Sylectus user ID. | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/load-board/user-connection

`ark.update_load_board_user_connection`

Validates or saves the current user DAT or Sylectus seat connection used by ARK load-board posting workflows.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `value` | UpdateLoadBoardUserConnectionRequest | Yes | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/load-board/user-connection' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "dat",
  "username": "<username>"
}'
```

#### Success response shape

Updated load board user connection

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateLoadBoardUserConnectionResult | Yes | - | - |
| `data.provider` | string | Yes | - | one of: dat, sylectus |
| `data.status` | LoadBoardProviderConnectionStatus | Yes | - | - |
| `data.canEditCurrentUserSeat` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 503 | External provider or worker queue could not be reached |

### GET /api/v1/load-board/user-mappings

`ark.list_load_board_user_mappings`

Lists active organization users and their DAT or Sylectus seat mappings for load-board posting setup.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.provider` | LoadBoardUserMappingProvider | Yes | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/load-board/user-mappings?provider=<provider>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load-board user mappings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ListLoadBoardUserMappingsResult | Yes | - | - |
| `data.provider` | LoadBoardUserMappingProvider | Yes | - | one of: dat, sylectus |
| `data.mappings` | array<LoadBoardUserMapping> | Yes | - | - |
| `data.mappings[]` | LoadBoardUserMapping | Yes | - | - |
| `data.mappings[].provider` | LoadBoardUserMappingProvider | Yes | - | one of: dat, sylectus |
| `data.mappings[].userId` | string | Yes | - | format: uuid |
| `data.mappings[].firstName` | string \| null | Yes | - | - |
| `data.mappings[].lastName` | string \| null | Yes | - | - |
| `data.mappings[].email` | string \| null | Yes | - | format: email |
| `data.mappings[].externalUserId` | string \| null | Yes | DAT username or Sylectus user ID saved for this ARK user. | - |
| `data.mappings[].suggestedExternalUserId` | string \| null | Yes | Suggested DAT username or Sylectus user ID derived from ARK user data. | - |
| `data.mappings[].active` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### PATCH /api/v1/load-board/user-mappings

`ark.update_load_board_user_mappings`

Saves DAT usernames or Sylectus user IDs for ARK users so posting workflows use the right load-board seat.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | LoadBoardUserMappingProvider | Yes | - | one of: dat, sylectus |
| `mappings` | array<UpdateLoadBoardUserMapping> | Yes | - | min items: 1; max items: 500 |
| `mappings[]` | UpdateLoadBoardUserMapping | Yes | - | - |
| `mappings[].userId` | string | Yes | - | format: uuid |
| `mappings[].externalUserId` | string | No | DAT username or Sylectus user ID. Use an empty string to clear the mapping. | default: ""; max length: 200 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/load-board/user-mappings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "dat",
  "mappings": [
    {
      "userId": "<userId>"
    }
  ]
}'
```

#### Success response shape

Updated load-board user mappings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateLoadBoardUserMappingsResult | Yes | - | - |
| `data.provider` | LoadBoardUserMappingProvider | Yes | - | one of: dat, sylectus |
| `data.mappings` | array<LoadBoardUserMapping> | Yes | - | - |
| `data.mappings[]` | LoadBoardUserMapping | Yes | - | - |
| `data.mappings[].provider` | LoadBoardUserMappingProvider | Yes | - | one of: dat, sylectus |
| `data.mappings[].userId` | string | Yes | - | format: uuid |
| `data.mappings[].firstName` | string \| null | Yes | - | - |
| `data.mappings[].lastName` | string \| null | Yes | - | - |
| `data.mappings[].email` | string \| null | Yes | - | format: email |
| `data.mappings[].externalUserId` | string \| null | Yes | DAT username or Sylectus user ID saved for this ARK user. | - |
| `data.mappings[].suggestedExternalUserId` | string \| null | Yes | Suggested DAT username or Sylectus user ID derived from ARK user data. | - |
| `data.mappings[].active` | boolean | Yes | - | - |
| `data.updatedCount` | integer | Yes | - | min: 0 |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/loads

`ark.search_loads`

Searches loads visible to the connected actor by load number, reference fields, customer, status, and team.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | No | - | min length: 1; max length: 100 |
| `query.status` | string | No | - | min length: 1; max length: 50 |
| `query.team_ids` | string | No | Comma-separated team IDs. Omit to use all teams visible to the connected user. | - |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Visible load search results

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.items` | array<object> | Yes | - | - |
| `data.items[]` | object | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].loadNumber` | string | Yes | - | - |
| `data.items[].status` | string \| null | Yes | - | - |
| `data.items[].teamId` | string \| null | Yes | - | format: uuid |
| `data.items[].customer` | object \| null | Yes | - | - |
| `data.items[].customer.id` | string | Yes | - | format: uuid |
| `data.items[].customer.name` | string \| null | Yes | - | - |
| `data.items[].pickupNumber` | string \| null | No | - | - |
| `data.items[].purchaseOrderNumber` | string \| null | No | - | - |
| `data.items[].billOfLading` | string \| null | No | - | - |
| `data.items[].product` | string \| null | No | - | - |
| `data.items[].description` | string \| null | No | - | - |
| `data.items[].createdAt` | string | Yes | - | format: date-time |
| `data.items[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.pagination` | object | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/loads

`ark.create_load`

Creates an available load with customer, team, equipment, route stops, references, and optional customer charges.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canCreateLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerId` | string | Yes | - | format: uuid |
| `teamId` | string | Yes | - | format: uuid |
| `brokerId` | string \| null | No | - | format: uuid |
| `customerServiceRepId` | string \| null | No | - | format: uuid |
| `temperature` | number \| null | No | - | - |
| `internalComments` | string | No | - | default: ""; max length: 5000 |
| `externalComments` | string | No | - | default: ""; max length: 5000 |
| `hotComments` | string | No | - | default: ""; max length: 5000 |
| `product` | string | No | - | default: ""; max length: 200 |
| `value` | number \| null | No | - | - |
| `description` | string | No | - | default: ""; max length: 5000 |
| `size` | string | No | - | default: ""; max length: 100 |
| `trailer` | string | Yes | - | min length: 1; max length: 100 |
| `weight` | number \| null | No | - | - |
| `weightUnit` | string | No | - | one of: lbs, kg; default: "lbs" |
| `length` | number \| null | No | - | - |
| `width` | number \| null | No | - | - |
| `height` | number \| null | No | - | - |
| `billOfLading` | string | No | - | default: ""; max length: 100 |
| `numberOfPieces` | integer \| null | No | - | min: 0 |
| `pickupNumber` | string | No | - | default: ""; max length: 100 |
| `purchaseOrderNumber` | string | No | - | default: ""; max length: 100 |
| `hazmat` | boolean | No | - | default: false |
| `docHigh` | boolean | No | - | default: false |
| `stackable` | boolean | No | - | default: false |
| `tsa` | boolean | No | - | default: false |
| `teamDriverRequired` | boolean | No | - | default: false |
| `miles` | number \| null | No | - | min: 0 |
| `customerCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `carrierCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `customerPay` | array<LoadCreateCustomerPayInput> | No | - | default: []; max items: 100 |
| `customerPay[]` | LoadCreateCustomerPayInput | No | - | - |
| `customerPay[].name` | string | No | - | min length: 1; max length: 200 |
| `customerPay[].price` | number \| null | No | - | - |
| `customerPay[].rateType` | string \| null | No | - | max length: 50 |
| `customerPay[].unitPrice` | number \| null | No | - | - |
| `customerPay[].quantity` | number \| null | No | - | - |
| `customerPay[].uom` | string \| null | No | - | max length: 50 |
| `stops` | array<LoadCreateStopInput> | Yes | - | min items: 2; max items: 50 |
| `stops[]` | LoadCreateStopInput | Yes | - | - |
| `stops[].locationId` | string | Yes | - | format: uuid |
| `stops[].index` | integer | Yes | - | min: 0 |
| `stops[].type` | string | Yes | - | min length: 1; max length: 50 |
| `stops[].referenceNumber` | string \| null | No | - | max length: 100 |
| `stops[].pieces` | integer \| null | No | - | min: 0 |
| `stops[].arrivalTime` | string \| null | No | - | format: date-time |
| `stops[].arrivalTime2` | string \| null | No | - | format: date-time |
| `stops[].weight` | number \| null | No | - | min: 0 |
| `stops[].comment` | string \| null | No | - | max length: 5000 |
| `stops[].schedulingType` | string \| null | No | - | one of: fcfs, appointment, null |
| `stops[].milesToNextStop` | number \| null | No | - | min: 0 |
| `stops[].durationToNextStopSeconds` | integer \| null | No | - | min: 0 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "<customerId>",
  "teamId": "<teamId>",
  "trailer": "<trailer>",
  "stops": [
    {
      "locationId": "<locationId>",
      "index": 0,
      "type": "<type>"
    },
    {
      "locationId": "<locationId>",
      "index": 0,
      "type": "<type>"
    }
  ]
}'
```

#### Success response shape

Created load

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | Load | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.loadNumber` | string | Yes | - | - |
| `data.status` | string \| null | Yes | - | - |
| `data.teamId` | string \| null | Yes | - | format: uuid |
| `data.customer` | object \| null | Yes | - | - |
| `data.customer.id` | string | Yes | - | format: uuid |
| `data.customer.name` | string \| null | Yes | - | - |
| `data.activeDispatch` | object \| null | Yes | - | - |
| `data.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.activeDispatch.status` | string \| null | Yes | - | - |
| `data.pickupNumber` | string \| null | Yes | - | - |
| `data.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.billOfLading` | string \| null | Yes | - | - |
| `data.product` | string \| null | Yes | - | - |
| `data.description` | string \| null | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### DELETE /api/v1/loads/{loadId}

`ark.delete_load`

Soft-deletes a visible load, cancels active dispatches, and stops active tracking sessions.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:delete` |
| ARK permissions | `canDeleteLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/loads/<loadId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deleted load

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.deleted` | unknown | Yes | - | - |
| `data.dispatchesCancelled` | integer | Yes | - | min: 0 |
| `data.loadBoardRemovalProcessed` | boolean | Yes | - | - |
| `data.trackingResult` | object \| null | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/loads/{loadId}

`ark.get_load`

Returns one visible load by ID.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Get load

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | Load | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.loadNumber` | string | Yes | - | - |
| `data.status` | string \| null | Yes | - | - |
| `data.teamId` | string \| null | Yes | - | format: uuid |
| `data.customer` | object \| null | Yes | - | - |
| `data.customer.id` | string | Yes | - | format: uuid |
| `data.customer.name` | string \| null | Yes | - | - |
| `data.activeDispatch` | object \| null | Yes | - | - |
| `data.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.activeDispatch.status` | string \| null | Yes | - | - |
| `data.pickupNumber` | string \| null | Yes | - | - |
| `data.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.billOfLading` | string \| null | Yes | - | - |
| `data.product` | string \| null | Yes | - | - |
| `data.description` | string \| null | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/loads/{loadId}

`ark.update_load_details`

Updates a visible load revision, including customer, team, reps, reference fields, commodity, dimensions, currencies, customer-pay lines, and optional full stop replacement.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerId` | string \| null | No | - | format: uuid |
| `teamId` | string | No | - | format: uuid |
| `brokerId` | string \| null | No | - | format: uuid |
| `customerServiceRepId` | string \| null | No | - | format: uuid |
| `temperature` | number \| null | No | - | - |
| `internalComments` | string \| null | No | - | max length: 5000 |
| `externalComments` | string \| null | No | - | max length: 5000 |
| `hotComments` | string \| null | No | - | max length: 5000 |
| `pickupNumber` | string \| null | No | - | max length: 100 |
| `purchaseOrderNumber` | string \| null | No | - | max length: 100 |
| `billOfLading` | string \| null | No | - | max length: 100 |
| `product` | string \| null | No | - | max length: 200 |
| `value` | number \| null | No | - | - |
| `description` | string \| null | No | - | max length: 5000 |
| `size` | string \| null | No | - | max length: 100 |
| `trailer` | string \| null | No | - | max length: 100 |
| `weight` | number \| null | No | - | - |
| `weightUnit` | string | No | - | one of: lbs, kg |
| `length` | number \| null | No | - | - |
| `width` | number \| null | No | - | - |
| `height` | number \| null | No | - | - |
| `numberOfPieces` | integer \| null | No | - | min: 0 |
| `hazmat` | boolean | No | - | - |
| `docHigh` | boolean | No | - | - |
| `stackable` | boolean | No | - | - |
| `tsa` | boolean | No | - | - |
| `teamDriverRequired` | boolean | No | - | - |
| `miles` | number \| null | No | - | min: 0 |
| `maximumBuyAmount` | number \| null | No | Maximum carrier buy amount for load-board and market-intelligence workflows. | min: 0 |
| `customerCurrency` | string | No | - | one of: USD, CAD, MXN |
| `carrierCurrency` | string | No | - | one of: USD, CAD, MXN |
| `customerPay` | array<LoadRevisionCustomerPayItem> | No | Replacement customer-pay lines. Omit to leave customer pay unchanged. | max items: 100 |
| `customerPay[]` | LoadRevisionCustomerPayItem | No | - | - |
| `customerPay[].id` | string | No | Existing customer-pay line ID. Omit to create a new line. | format: uuid |
| `customerPay[].name` | string | No | - | min length: 1; max length: 200 |
| `customerPay[].price` | number \| null | No | - | - |
| `customerPay[].rateType` | string \| null | No | - | max length: 50 |
| `customerPay[].unitPrice` | number \| null | No | - | - |
| `customerPay[].quantity` | number \| null | No | - | - |
| `customerPay[].uom` | string \| null | No | - | max length: 50 |
| `stops` | array<LoadRevisionStopItem> | No | Replacement stop list. Omit to leave stops unchanged. | min items: 2; max items: 50 |
| `stops[]` | LoadRevisionStopItem | No | - | - |
| `stops[].id` | string | No | Existing stop ID. Omit to create a new stop. | format: uuid |
| `stops[].locationId` | string | No | - | format: uuid |
| `stops[].index` | integer | No | - | min: 0 |
| `stops[].type` | string | No | - | min length: 1; max length: 50 |
| `stops[].referenceNumber` | string \| null | No | - | max length: 100 |
| `stops[].pieces` | integer \| null | No | - | min: 0 |
| `stops[].arrivalTime` | string \| null | No | - | format: date-time |
| `stops[].arrivalTime2` | string \| null | No | - | format: date-time |
| `stops[].weight` | number \| null | No | - | min: 0 |
| `stops[].comment` | string \| null | No | - | max length: 5000 |
| `stops[].schedulingType` | string \| null | No | - | one of: fcfs, appointment, null |
| `stops[].milesToNextStop` | number \| null | No | - | min: 0 |
| `stops[].durationToNextStopSeconds` | integer \| null | No | - | min: 0 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/loads/<loadId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated load

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | Load | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.loadNumber` | string | Yes | - | - |
| `data.status` | string \| null | Yes | - | - |
| `data.teamId` | string \| null | Yes | - | format: uuid |
| `data.customer` | object \| null | Yes | - | - |
| `data.customer.id` | string | Yes | - | format: uuid |
| `data.customer.name` | string \| null | Yes | - | - |
| `data.activeDispatch` | object \| null | Yes | - | - |
| `data.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.activeDispatch.status` | string \| null | Yes | - | - |
| `data.pickupNumber` | string \| null | Yes | - | - |
| `data.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.billOfLading` | string \| null | Yes | - | - |
| `data.product` | string \| null | Yes | - | - |
| `data.description` | string \| null | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/archive

`ark.archive_load`

Archives a visible load, blocking delivered loads that must first be undelivered from Billing.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:delete` |
| ARK permissions | `canDeleteLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/archive' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Archived load

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |

#### Errors

_No operation-specific error responses._

### POST /api/v1/loads/{loadId}/assign-carrier

`ark.assign_carrier`

Books an active carrier on a visible load using ARK's dispatch workflow, dispatcher/driver contact handling, carrier pay, currency, optional bid acceptance, booking snapshots, audit events, and load status update.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierId` | string | Yes | - | format: uuid |
| `bidId` | string | No | - | format: uuid |
| `dispatcher` | DispatchContactInput | Yes | - | - |
| `dispatcher.id` | string \| null | No | - | format: uuid |
| `dispatcher.firstName` | string | Yes | - | min length: 1; max length: 100 |
| `dispatcher.lastName` | string \| null | No | - | max length: 100 |
| `dispatcher.email` | string | Yes | - | format: email; max length: 500 |
| `dispatcher.phone` | string \| null | No | - | max length: 50 |
| `driver` | DispatchDriverInput | No | - | - |
| `driver.id` | string \| null | No | - | format: uuid |
| `driver.firstName` | string \| null | No | - | max length: 100 |
| `driver.lastName` | string \| null | No | - | max length: 100 |
| `driver.email` | string \| null | No | - | format: email; max length: 500 |
| `driver.phone` | string \| null | No | - | max length: 50 |
| `truckNumber` | string \| null | No | - | max length: 100 |
| `trailerNumber` | string \| null | No | - | max length: 100 |
| `carrierCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `dispatchPay` | array<DispatchPayInput> | No | - | default: []; max items: 100 |
| `dispatchPay[]` | DispatchPayInput | No | - | - |
| `dispatchPay[].id` | string | No | - | format: uuid |
| `dispatchPay[].name` | string | No | - | min length: 1; max length: 200 |
| `dispatchPay[].price` | number \| null | No | - | - |
| `dispatchPay[].rateType` | string \| null | No | - | max length: 50 |
| `dispatchPay[].unitPrice` | number \| null | No | - | - |
| `dispatchPay[].quantity` | number \| null | No | - | - |
| `dispatchPay[].uom` | string \| null | No | - | max length: 50 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/assign-carrier' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "carrierId": "<carrierId>",
  "dispatcher": {
    "firstName": "<firstName>",
    "email": "<email>"
  }
}'
```

#### Success response shape

Assigned carrier and created dispatch

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatch` | AssignedDispatch | Yes | - | - |
| `data.dispatch.id` | string | Yes | - | format: uuid |
| `data.dispatch.loadId` | string | Yes | - | format: uuid |
| `data.dispatch.carrierId` | string | Yes | - | format: uuid |
| `data.dispatch.carrier` | object | Yes | - | - |
| `data.dispatch.carrier.id` | string | Yes | - | format: uuid |
| `data.dispatch.carrier.name` | string \| null | Yes | - | - |
| `data.dispatch.active` | boolean | Yes | - | - |
| `data.dispatch.status` | string \| null | Yes | - | - |
| `data.dispatch.truckNumber` | string \| null | Yes | - | - |
| `data.dispatch.trailerNumber` | string \| null | Yes | - | - |
| `data.dispatch.totalDispatchPay` | number \| null | Yes | - | - |
| `data.bidAccepted` | boolean | Yes | - | - |
| `data.brokerAssignedToCurrentUser` | boolean | Yes | - | - |
| `data.loadBoardRemovalProcessed` | boolean | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/loads/{loadId}/bids

`ark.list_load_bids`

Lists carrier bids for a visible load with carrier, amount, status, rejection reason, notes, expiration, and creator context.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `query.include_expired` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0; max: 10000 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/bids' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load bids

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.items` | array<LoadBid> | Yes | - | - |
| `data.items[]` | LoadBid | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].loadId` | string | Yes | - | format: uuid |
| `data.items[].carrierId` | string | Yes | - | format: uuid |
| `data.items[].carrier` | object | Yes | - | - |
| `data.items[].carrier.id` | string | Yes | - | format: uuid |
| `data.items[].carrier.name` | string \| null | Yes | - | - |
| `data.items[].carrier.mcNumber` | string \| null | Yes | - | - |
| `data.items[].bidAmount` | string | Yes | Decimal carrier bid amount as a string to preserve precision. | - |
| `data.items[].equipmentType` | string \| null | Yes | - | - |
| `data.items[].status` | string | Yes | - | one of: pending, accepted, rejected, expired, withdrawn |
| `data.items[].rejectionReason` | string \| null | Yes | - | - |
| `data.items[].notes` | string \| null | Yes | - | - |
| `data.items[].expiresAt` | string \| null | Yes | - | format: date-time |
| `data.items[].createdAt` | string | Yes | - | format: date-time |
| `data.items[].updatedAt` | string | Yes | - | format: date-time |
| `data.items[].createdBy` | string \| null | Yes | - | format: uuid |
| `data.items[].createdByName` | string \| null | Yes | - | - |
| `data.pagination` | object | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.offset` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/loads/{loadId}/bids/{bidId}/reject

`ark.reject_load_bid`

Rejects a pending carrier bid for a visible load with a broker-provided reason.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `one of: canEditLoad`, `one of: canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.bidId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `rejectionReason` | string | Yes | - | min length: 1; max length: 500 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/bids/<bidId>/reject' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "rejectionReason": "<rejectionReason>"
}'
```

#### Success response shape

Rejected load bid

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.bid` | LoadBid | Yes | - | - |
| `data.bid.id` | string | Yes | - | format: uuid |
| `data.bid.loadId` | string | Yes | - | format: uuid |
| `data.bid.carrierId` | string | Yes | - | format: uuid |
| `data.bid.carrier` | object | Yes | - | - |
| `data.bid.carrier.id` | string | Yes | - | format: uuid |
| `data.bid.carrier.name` | string \| null | Yes | - | - |
| `data.bid.carrier.mcNumber` | string \| null | Yes | - | - |
| `data.bid.bidAmount` | string | Yes | Decimal carrier bid amount as a string to preserve precision. | - |
| `data.bid.equipmentType` | string \| null | Yes | - | - |
| `data.bid.status` | string | Yes | - | one of: pending, accepted, rejected, expired, withdrawn |
| `data.bid.rejectionReason` | string \| null | Yes | - | - |
| `data.bid.notes` | string \| null | Yes | - | - |
| `data.bid.expiresAt` | string \| null | Yes | - | format: date-time |
| `data.bid.createdAt` | string | Yes | - | format: date-time |
| `data.bid.updatedAt` | string | Yes | - | format: date-time |
| `data.bid.createdBy` | string \| null | Yes | - | format: uuid |
| `data.bid.createdByName` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/bids/manual

`ark.create_manual_load_bid`

Creates or updates a pending manual carrier bid for a visible load, matching the manual bid entry workflow on the load market intelligence tab.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `one of: canEditLoad`, `one of: canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierId` | string | Yes | - | format: uuid |
| `bidAmount` | number | Yes | - | - |
| `notes` | string \| null | No | - | max length: 1000 |
| `contactMethod` | string | No | - | one of: phone, email; default: "phone" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/bids/manual' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "carrierId": "<carrierId>",
  "bidAmount": 1
}'
```

#### Success response shape

Created or updated manual load bid

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.bid` | LoadBid | Yes | - | - |
| `data.bid.id` | string | Yes | - | format: uuid |
| `data.bid.loadId` | string | Yes | - | format: uuid |
| `data.bid.carrierId` | string | Yes | - | format: uuid |
| `data.bid.carrier` | object | Yes | - | - |
| `data.bid.carrier.id` | string | Yes | - | format: uuid |
| `data.bid.carrier.name` | string \| null | Yes | - | - |
| `data.bid.carrier.mcNumber` | string \| null | Yes | - | - |
| `data.bid.bidAmount` | string | Yes | Decimal carrier bid amount as a string to preserve precision. | - |
| `data.bid.equipmentType` | string \| null | Yes | - | - |
| `data.bid.status` | string | Yes | - | one of: pending, accepted, rejected, expired, withdrawn |
| `data.bid.rejectionReason` | string \| null | Yes | - | - |
| `data.bid.notes` | string \| null | Yes | - | - |
| `data.bid.expiresAt` | string \| null | Yes | - | format: date-time |
| `data.bid.createdAt` | string | Yes | - | format: date-time |
| `data.bid.updatedAt` | string | Yes | - | format: date-time |
| `data.bid.createdBy` | string \| null | Yes | - | format: uuid |
| `data.bid.createdByName` | string \| null | Yes | - | - |
| `data.updatedExisting` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/bill-of-lading/generate

`ark.generate_bill_of_lading`

Generates and stores a bill of lading PDF for a visible load, persists the effective BOL number, and attaches the PDF to load files.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `bolNumber` | string | No | Optional BOL number. Defaults to the stored BOL or load number. | min length: 1; max length: 100 |
| `fileName` | string | No | Optional PDF file name. A .pdf extension is added when omitted. | min length: 1; max length: 200 |
| `comment` | string \| null | No | Optional special instructions to print on the BOL. | max length: 5000 |
| `items` | array<BillOfLadingItemInput> | No | Optional commodity lines. Omit to use load product, description, pieces, and weight. | min items: 1; max items: 100 |
| `items[]` | BillOfLadingItemInput | No | - | - |
| `items[].product` | string \| null | No | - | max length: 200 |
| `items[].description` | string \| null | No | - | max length: 5000 |
| `items[].quantity` | number | No | - | min: 0 |
| `items[].weight` | number | No | - | min: 0 |
| `items[].length` | number \| null | No | - | min: 0 |
| `items[].width` | number \| null | No | - | min: 0 |
| `items[].height` | number \| null | No | - | min: 0 |
| `items[].nmfc` | string \| null | No | - | max length: 100 |
| `items[].hazmat` | boolean | No | - | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/bill-of-lading/generate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Generated bill of lading

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | BillOfLadingGenerateResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.bolNumber` | string | Yes | - | - |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.file` | LoadFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/billing-adjustment

`ark.update_billed_load_details`

Updates a visible load after customer billing has started, then regenerates the revised customer invoice and optionally queues a QuickBooks customer invoice update for READY or INVOICED payments.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `loads:write`, `billing:write` |
| ARK permissions | `canViewLoads`, `canEditLoad`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerId` | string \| null | No | - | format: uuid |
| `teamId` | string | No | - | format: uuid |
| `brokerId` | string \| null | No | - | format: uuid |
| `customerServiceRepId` | string \| null | No | - | format: uuid |
| `temperature` | number \| null | No | - | - |
| `internalComments` | string \| null | No | - | max length: 5000 |
| `externalComments` | string \| null | No | - | max length: 5000 |
| `hotComments` | string \| null | No | - | max length: 5000 |
| `pickupNumber` | string \| null | No | - | max length: 100 |
| `purchaseOrderNumber` | string \| null | No | - | max length: 100 |
| `billOfLading` | string \| null | No | - | max length: 100 |
| `product` | string \| null | No | - | max length: 200 |
| `value` | number \| null | No | - | - |
| `description` | string \| null | No | - | max length: 5000 |
| `size` | string \| null | No | - | max length: 100 |
| `trailer` | string \| null | No | - | max length: 100 |
| `weight` | number \| null | No | - | - |
| `weightUnit` | string | No | - | one of: lbs, kg |
| `length` | number \| null | No | - | - |
| `width` | number \| null | No | - | - |
| `height` | number \| null | No | - | - |
| `numberOfPieces` | integer \| null | No | - | min: 0 |
| `hazmat` | boolean | No | - | - |
| `docHigh` | boolean | No | - | - |
| `stackable` | boolean | No | - | - |
| `tsa` | boolean | No | - | - |
| `teamDriverRequired` | boolean | No | - | - |
| `miles` | number \| null | No | - | min: 0 |
| `maximumBuyAmount` | number \| null | No | Maximum carrier buy amount for load-board and market-intelligence workflows. | min: 0 |
| `customerCurrency` | string | No | - | one of: USD, CAD, MXN |
| `carrierCurrency` | string | No | - | one of: USD, CAD, MXN |
| `customerPay` | array<LoadRevisionCustomerPayItem> | No | Replacement customer-pay lines. Omit to leave customer pay unchanged. | max items: 100 |
| `customerPay[]` | LoadRevisionCustomerPayItem | No | - | - |
| `customerPay[].id` | string | No | Existing customer-pay line ID. Omit to create a new line. | format: uuid |
| `customerPay[].name` | string | No | - | min length: 1; max length: 200 |
| `customerPay[].price` | number \| null | No | - | - |
| `customerPay[].rateType` | string \| null | No | - | max length: 50 |
| `customerPay[].unitPrice` | number \| null | No | - | - |
| `customerPay[].quantity` | number \| null | No | - | - |
| `customerPay[].uom` | string \| null | No | - | max length: 50 |
| `stops` | array<LoadRevisionStopItem> | No | Replacement stop list. Omit to leave stops unchanged. | min items: 2; max items: 50 |
| `stops[]` | LoadRevisionStopItem | No | - | - |
| `stops[].id` | string | No | Existing stop ID. Omit to create a new stop. | format: uuid |
| `stops[].locationId` | string | No | - | format: uuid |
| `stops[].index` | integer | No | - | min: 0 |
| `stops[].type` | string | No | - | min length: 1; max length: 50 |
| `stops[].referenceNumber` | string \| null | No | - | max length: 100 |
| `stops[].pieces` | integer \| null | No | - | min: 0 |
| `stops[].arrivalTime` | string \| null | No | - | format: date-time |
| `stops[].arrivalTime2` | string \| null | No | - | format: date-time |
| `stops[].weight` | number \| null | No | - | min: 0 |
| `stops[].comment` | string \| null | No | - | max length: 5000 |
| `stops[].schedulingType` | string \| null | No | - | one of: fcfs, appointment, null |
| `stops[].milesToNextStop` | number \| null | No | - | min: 0 |
| `stops[].durationToNextStopSeconds` | integer \| null | No | - | min: 0 |
| `refreshCustomerBilling` | boolean | No | When true, regenerate the revised invoice for READY or INVOICED customer payments. | default: true |
| `queueQuickBooksSync` | boolean | No | When true, queue a QuickBooks customer_invoice_update job after the load update. | default: true |
| `invoiceRemitProfileId` | string | No | Optional invoice remit profile ID for the regenerated revised invoice. | format: uuid |
| `invoiceFileName` | string | No | Optional regenerated revised invoice PDF file name. | max length: 200 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/billing-adjustment' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated billed load details

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | BilledLoadUpdateData | Yes | - | - |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.billingRefresh` | BilledLoadBillingRefresh | Yes | - | - |
| `data.billingRefresh.status` | string | Yes | - | one of: not_requested, skipped, refreshed, partial, failed |
| `data.billingRefresh.customerPaymentId` | string \| null | Yes | - | format: uuid |
| `data.billingRefresh.customerPaymentStatus` | string \| null | Yes | - | - |
| `data.billingRefresh.invoice` | BilledLoadInvoiceRefreshResult | Yes | - | - |
| `data.billingRefresh.invoice.generated` | boolean | Yes | - | - |
| `data.billingRefresh.invoice.fileId` | string \| null | Yes | - | format: uuid |
| `data.billingRefresh.invoice.fileName` | string \| null | Yes | - | - |
| `data.billingRefresh.invoice.error` | BilledLoadRefreshChildError \| null | Yes | - | - |
| `data.billingRefresh.quickBooksSync` | BilledLoadQuickBooksRefreshResult | Yes | - | - |
| `data.billingRefresh.quickBooksSync.requested` | boolean | Yes | - | - |
| `data.billingRefresh.quickBooksSync.queued` | boolean | Yes | - | - |
| `data.billingRefresh.quickBooksSync.jobId` | string \| null | Yes | - | format: uuid |
| `data.billingRefresh.quickBooksSync.status` | string \| null | Yes | - | one of: queued, skipped, failed, not_requested, null |
| `data.billingRefresh.quickBooksSync.message` | string \| null | Yes | - | - |
| `data.billingRefresh.quickBooksSync.error` | BilledLoadRefreshChildError \| null | Yes | - | - |
| `data.billingRefresh.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/loads/{loadId}/billing-readiness

`ark.get_load_billing_readiness`

Returns billing readiness for a visible load, including required file coverage, missing document types, customer payment state, and blocking reasons.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/billing-readiness' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load billing readiness

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | LoadBillingReadiness | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status` | string \| null | Yes | - | - |
| `data.loadSize` | string \| null | Yes | - | - |
| `data.requiredFileTypes` | array<string> | Yes | - | - |
| `data.requiredFileTypes[]` | string | Yes | - | - |
| `data.presentFileTypes` | array<string> | Yes | - | - |
| `data.presentFileTypes[]` | string | Yes | - | - |
| `data.missingRequiredFileTypes` | array<string> | Yes | - | - |
| `data.missingRequiredFileTypes[]` | string | Yes | - | - |
| `data.podRequirementExempt` | boolean | Yes | - | - |
| `data.files` | array<LoadBillingReadinessFile> | Yes | - | - |
| `data.files[]` | LoadBillingReadinessFile | Yes | - | - |
| `data.files[].id` | string | Yes | - | format: uuid |
| `data.files[].name` | string | Yes | - | - |
| `data.files[].type` | string | Yes | - | - |
| `data.files[].mime` | string \| null | Yes | - | - |
| `data.files[].path` | string | Yes | - | - |
| `data.files[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.files[].systemGenerated` | boolean | Yes | - | - |
| `data.dispatchStatuses` | array<string> | Yes | - | - |
| `data.dispatchStatuses[]` | string | Yes | - | - |
| `data.customerPayment` | LoadBillingReadinessCustomerPayment | Yes | - | - |
| `data.customerPayment.id` | string | Yes | - | format: uuid |
| `data.customerPayment.status` | string \| null | Yes | - | - |
| `data.customerPayment.onHold` | boolean | Yes | - | - |
| `data.customerPayment.packetFileId` | string \| null | Yes | - | format: uuid |
| `data.customerPayment.invoicedDate` | string \| null | Yes | - | format: date-time |
| `data.customerPayment.paidDate` | string \| null | Yes | - | format: date-time |
| `data.customerPayment.invoiceNumber` | number \| null | Yes | - | - |
| `data.customerPayment.docNumber` | string \| null | Yes | - | - |
| `data.customerPayment.paymentAmount` | number \| null | Yes | - | - |
| `data.customerPayment.currency` | string \| null | Yes | - | - |
| `data.readyForBillingPacket` | boolean | Yes | - | - |
| `data.blockingReasons` | array<string> | Yes | - | - |
| `data.blockingReasons[]` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/loads/{loadId}/billing/customer-payment/delivered

`ark.move_customer_payment_back_to_delivered`

Moves a ready customer payment back to DELIVERED, clears billing packet and payment amount, and releases linked customer pay rows.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerPaymentId` | string | Yes | Customer payment ID to move back from READY to DELIVERED. | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/billing/customer-payment/delivered' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "customerPaymentId": "<customerPaymentId>"
}'
```

#### Success response shape

Moved customer payment back to delivered

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | MoveCustomerPaymentBackToDeliveredResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.customerPaymentId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status` | string | Yes | - | one of: DELIVERED |
| `data.customerPayRowsReleased` | integer | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/billing/customer-payment/record

`ark.record_customer_payment`

Records an invoiced or factored customer payment as paid for a visible load, including paid date and optional reference number.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerPaymentId` | string | No | Optional customer payment ID. Omit to use the latest payment for the load. | format: uuid |
| `referenceNumber` | string \| null | No | Optional payment reference number. | max length: 100 |
| `paidDate` | string | Yes | Payment date in YYYY-MM-DD format. | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/billing/customer-payment/record' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "paidDate": "<paidDate>"
}'
```

#### Success response shape

Recorded customer payment

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RecordCustomerPaymentResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.customerPaymentId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status` | string | Yes | - | one of: PAID |
| `data.paidDate` | string | Yes | - | format: date |
| `data.referenceNumber` | string \| null | Yes | - | - |
| `data.paymentAmount` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/billing/invoice/generate

`ark.generate_customer_invoice`

Generates and stores a customer invoice PDF for a visible load using customer pay and the selected or locked invoice remit profile.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerPaymentId` | string | No | Optional customer payment ID. Omit to use the latest customer payment for the load. | format: uuid |
| `invoiceRemitProfileId` | string | No | Optional invoice remit profile ID. Omit to use the locked/default profile. | format: uuid |
| `fileName` | string | No | Optional PDF file name. A .pdf extension is added when omitted. | min length: 1; max length: 200 |
| `revised` | boolean | No | Mark the generated PDF as a revised invoice. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/billing/invoice/generate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Generated customer invoice

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | GenerateCustomerInvoiceResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.customerPaymentId` | string | Yes | - | format: uuid |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.file` | LoadFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.revised` | boolean | Yes | - | - |
| `data.invoiceRemitProfile` | InvoiceRemitProfileSnapshot | Yes | - | - |
| `data.invoiceRemitProfile.id` | string | Yes | - | format: uuid |
| `data.invoiceRemitProfile.organization_id` | string \| null | No | - | format: uuid |
| `data.invoiceRemitProfile.version_number` | number | Yes | - | - |
| `data.invoiceRemitProfile.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.invoiceRemitProfile.name` | string | Yes | - | - |
| `data.invoiceRemitProfile.remit_email` | string \| null | No | - | - |
| `data.invoiceRemitProfile.send_to_remit_email` | boolean | Yes | - | - |
| `data.invoiceRemitProfile.invoice_instructions` | string \| null | No | - | - |
| `data.invoiceRemitProfile.address` | object \| null | No | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/billing/invoice/send

`ark.send_customer_invoice`

Sends the customer invoice email using the attached billing packet, marks the customer payment invoiced, and can optionally queue QuickBooks invoice sync.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerPaymentId` | string | No | Optional customer payment ID. Omit to use the latest customer payment for the load. | format: uuid |
| `queueQuickBooksSync` | boolean | No | Queue QuickBooks customer invoice sync after the invoice email is sent. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/billing/invoice/send' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Sent customer invoice

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SendCustomerInvoiceResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.customerPaymentId` | string | Yes | - | format: uuid |
| `data.packetFileId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.deliveryMode` | string | Yes | - | one of: direct, queued |
| `data.emailMessageId` | string \| null | Yes | - | format: uuid |
| `data.recipientMode` | string | Yes | - | one of: customer_billing, remit_profile |
| `data.recipientEmail` | string | Yes | - | format: email |
| `data.sentAt` | string | Yes | - | format: date-time |
| `data.status` | string | Yes | - | one of: INVOICED |
| `data.invoiceRemitProfile` | InvoiceRemitProfileSnapshot | Yes | - | - |
| `data.invoiceRemitProfile.id` | string | Yes | - | format: uuid |
| `data.invoiceRemitProfile.organization_id` | string \| null | No | - | format: uuid |
| `data.invoiceRemitProfile.version_number` | number | Yes | - | - |
| `data.invoiceRemitProfile.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.invoiceRemitProfile.name` | string | Yes | - | - |
| `data.invoiceRemitProfile.remit_email` | string \| null | No | - | - |
| `data.invoiceRemitProfile.send_to_remit_email` | boolean | Yes | - | - |
| `data.invoiceRemitProfile.invoice_instructions` | string \| null | No | - | - |
| `data.invoiceRemitProfile.address` | object \| null | No | - | - |
| `data.quickBooksSync` | SendCustomerInvoiceQuickBooksSync | Yes | - | - |
| `data.quickBooksSync.requested` | boolean | Yes | - | - |
| `data.quickBooksSync.queued` | boolean | Yes | - | - |
| `data.quickBooksSync.status` | string \| null | Yes | - | - |
| `data.quickBooksSync.jobId` | string \| null | Yes | - | format: uuid |
| `data.quickBooksSync.error` | string \| null | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/billing/packet/generate

`ark.generate_customer_billing_packet`

Generates and stores a customer billing packet PDF for a visible load by combining a generated or custom invoice with selected supporting documents, then optionally attaches it to the customer payment.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerPaymentId` | string | No | Optional customer payment ID. Omit to use the latest customer payment for the load. | format: uuid |
| `invoiceRemitProfileId` | string | No | Optional invoice remit profile ID. Omit to use the locked/default profile. | format: uuid |
| `supportingFileIds` | array<string> | No | Supporting load file IDs to merge after the invoice. | default: []; max items: 100 |
| `supportingFileIds[]` | string | No | - | format: uuid |
| `customInvoiceFileId` | string | No | Optional custom invoice PDF file ID. | format: uuid |
| `customInvoiceMode` | string | No | Whether the custom invoice replaces or is merged before the generated invoice. | one of: replace_generated, include_with_generated; default: "replace_generated" |
| `fileName` | string | No | Optional billing packet PDF file name. A .pdf extension is added when omitted. | min length: 1; max length: 200 |
| `revisedInvoice` | boolean | No | Mark the generated invoice portion as revised. | default: false |
| `attachToCustomerPayment` | boolean | No | Attach the generated packet to the customer payment and mark it READY. | default: true |
| `markCarrierPaymentsReady` | boolean | No | Also mark delivered carrier payments on the load READY. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/billing/packet/generate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Generated customer billing packet

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | GenerateCustomerBillingPacketResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.customerPaymentId` | string | Yes | - | format: uuid |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.file` | LoadFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.includedFiles` | array<LoadFile> | Yes | - | - |
| `data.includedFiles[]` | LoadFile | Yes | - | - |
| `data.includedFiles[].id` | string | Yes | - | format: uuid |
| `data.includedFiles[].name` | string | Yes | - | - |
| `data.includedFiles[].path` | string | Yes | - | - |
| `data.includedFiles[].mime` | string \| null | Yes | - | - |
| `data.includedFiles[].type` | string | Yes | - | - |
| `data.includedFiles[].loadId` | string \| null | Yes | - | format: uuid |
| `data.includedFiles[].dispatchId` | string \| null | Yes | - | format: uuid |
| `data.includedFiles[].organizationId` | string | Yes | - | format: uuid |
| `data.includedFiles[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.includedFiles[].createdBy` | string \| null | Yes | - | format: uuid |
| `data.includedFiles[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.includedFiles[].systemGenerated` | boolean | Yes | - | - |
| `data.invoiceSource` | string | Yes | - | one of: generated_invoice, custom_invoice, custom_and_generated_invoice |
| `data.invoiceRemitProfile` | InvoiceRemitProfileSnapshot | Yes | - | - |
| `data.invoiceRemitProfile.id` | string | Yes | - | format: uuid |
| `data.invoiceRemitProfile.organization_id` | string \| null | No | - | format: uuid |
| `data.invoiceRemitProfile.version_number` | number | Yes | - | - |
| `data.invoiceRemitProfile.type` | string | Yes | - | one of: standard, factoring, subsidiary, other |
| `data.invoiceRemitProfile.name` | string | Yes | - | - |
| `data.invoiceRemitProfile.remit_email` | string \| null | No | - | - |
| `data.invoiceRemitProfile.send_to_remit_email` | boolean | Yes | - | - |
| `data.invoiceRemitProfile.invoice_instructions` | string \| null | No | - | - |
| `data.invoiceRemitProfile.address` | object \| null | No | - | - |
| `data.attachedToCustomerPayment` | boolean | Yes | - | - |
| `data.carrierPaymentsMarkedReady` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/billing/undeliver

`ark.undeliver_billing_load`

Moves a delivered load back out of Billing when billing state is still unadvanced.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/billing/undeliver' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Moved load back out of Billing

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |

#### Errors

_No operation-specific error responses._

### POST /api/v1/loads/{loadId}/deliver

`ark.mark_load_delivered`

Marks a visible dispatched load delivered using ARK's deliver-and-bill workflow, creates delivery billing records, closes the active dispatch, and runs configured delivery side effects.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `one of: canEditLoad`, `one of: canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/deliver' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Marked load delivered

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatch` | DeliveryDispatchSnapshot \| null | Yes | - | - |
| `data.project44Result` | object \| null | Yes | - | - |
| `data.trackingResult` | object \| null | Yes | - | - |
| `data.auditEventRecorded` | boolean | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### PATCH /api/v1/loads/{loadId}/dispatches/{dispatchId}

`ark.update_dispatch`

Updates a visible dispatch carrier, dispatcher, driver, equipment, carrier currency, and optional dispatch pay through ARK's dispatch edit workflow, then reconciles tracking and QuickBooks side effects when applicable.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierId` | string | Yes | - | format: uuid |
| `dispatcher` | DispatchContactInput | Yes | - | - |
| `dispatcher.id` | string \| null | No | - | format: uuid |
| `dispatcher.firstName` | string | Yes | - | min length: 1; max length: 100 |
| `dispatcher.lastName` | string \| null | No | - | max length: 100 |
| `dispatcher.email` | string | Yes | - | format: email; max length: 500 |
| `dispatcher.phone` | string \| null | No | - | max length: 50 |
| `driver` | DispatchDriverInput \| null | Yes | Current driver details, or null to explicitly clear the driver. | - |
| `truckNumber` | string \| null | Yes | - | max length: 100 |
| `trailerNumber` | string \| null | Yes | - | max length: 100 |
| `carrierCurrency` | string | Yes | Current carrier currency to preserve or explicitly change. | one of: USD, CAD, MXN |
| `dispatchPay` | array<DispatchPayInput> | No | Optional replacement dispatch pay items. Omit to leave dispatch pay unchanged. | max items: 100 |
| `dispatchPay[]` | DispatchPayInput | No | - | - |
| `dispatchPay[].id` | string | No | - | format: uuid |
| `dispatchPay[].name` | string | No | - | min length: 1; max length: 200 |
| `dispatchPay[].price` | number \| null | No | - | - |
| `dispatchPay[].rateType` | string \| null | No | - | max length: 50 |
| `dispatchPay[].unitPrice` | number \| null | No | - | - |
| `dispatchPay[].quantity` | number \| null | No | - | - |
| `dispatchPay[].uom` | string \| null | No | - | max length: 50 |
| `updateTracking` | boolean | No | - | default: false |
| `queueQuickBooksSync` | boolean | No | - | default: false |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "carrierId": "<carrierId>",
  "dispatcher": {
    "firstName": "<firstName>",
    "email": "<email>"
  },
  "driver": {},
  "truckNumber": "<truckNumber>",
  "trailerNumber": "<trailerNumber>",
  "carrierCurrency": "USD"
}'
```

#### Success response shape

Updated dispatch

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatch` | AssignedDispatch | Yes | - | - |
| `data.dispatch.id` | string | Yes | - | format: uuid |
| `data.dispatch.loadId` | string | Yes | - | format: uuid |
| `data.dispatch.carrierId` | string | Yes | - | format: uuid |
| `data.dispatch.carrier` | object | Yes | - | - |
| `data.dispatch.carrier.id` | string | Yes | - | format: uuid |
| `data.dispatch.carrier.name` | string \| null | Yes | - | - |
| `data.dispatch.active` | boolean | Yes | - | - |
| `data.dispatch.status` | string \| null | Yes | - | - |
| `data.dispatch.truckNumber` | string \| null | Yes | - | - |
| `data.dispatch.trailerNumber` | string \| null | Yes | - | - |
| `data.dispatch.totalDispatchPay` | number \| null | Yes | - | - |
| `data.trackingUpdateResult` | DispatchUpdateTrackingResult | Yes | - | - |
| `data.quickBooksSyncResult` | DispatchUpdateQuickBooksResult | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/billing/carrier-payment/record

`ark.record_carrier_payment`

Records a ready or invoiced carrier payment as paid for a visible load dispatch, assigning or reusing its settlement number and saving paid date/reference details.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierPaymentId` | string | No | Optional carrier payment ID. Omit to use the carrier payment for the load dispatch. | format: uuid |
| `referenceNumber` | string \| null | No | Optional payment reference number. | max length: 100 |
| `paidDate` | string | Yes | Payment date in YYYY-MM-DD format. | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/billing/carrier-payment/record' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "paidDate": "<paidDate>"
}'
```

#### Success response shape

Recorded carrier payment

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RecordCarrierPaymentResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.carrierPaymentId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status` | string | Yes | - | one of: PAID |
| `data.paidDate` | string | Yes | - | format: date |
| `data.referenceNumber` | string \| null | Yes | - | - |
| `data.paymentAmount` | string \| null | Yes | - | - |
| `data.dueDate` | string \| null | Yes | - | format: date-time |
| `data.settlementNumber` | integer \| null | Yes | - | - |
| `data.factoringId` | string \| null | Yes | - | format: uuid |
| `data.currency` | string | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/billing/delivered

`ark.move_carrier_payment_back_to_delivered`

Moves a ready carrier payment back to DELIVERED, clears dispatch pay assignment, and removes local QuickBooks carrier bill mappings.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierPaymentId` | string | No | Optional carrier payment ID. Omit to use the carrier payment for the load dispatch. | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/billing/delivered' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Moved carrier payment back to delivered

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | MoveCarrierPaymentBackToDeliveredResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.carrierPaymentId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status` | string | Yes | - | one of: DELIVERED |
| `data.dispatchPayRowsReleased` | integer | Yes | - | - |
| `data.quickBooksMappingsDeleted` | integer | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### PATCH /api/v1/loads/{loadId}/dispatches/{dispatchId}/billing/due-date

`ark.update_carrier_payment_due_date`

Updates the due date for an unpaid carrier payment tied to a visible load dispatch.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierPaymentId` | string | No | Optional carrier payment ID. Omit to use the carrier payment for the load dispatch. | format: uuid |
| `dueDate` | string | Yes | New carrier payment due date in YYYY-MM-DD format. | - |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/billing/due-date' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "dueDate": "<dueDate>"
}'
```

#### Success response shape

Updated carrier payment due date

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateCarrierPaymentDueDateResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.carrierPaymentId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dueDate` | string | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/billing/packet/generate

`ark.generate_carrier_payment_packet`

Generates and stores a carrier payment packet PDF for a visible load dispatch by combining selected supporting documents, then optionally attaches it to the carrier payment and marks it invoiced.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierPaymentId` | string | No | Optional carrier payment ID. Omit to use the carrier payment for the load dispatch. | format: uuid |
| `sourceFileIds` | array<string> | Yes | Load file IDs to merge into the carrier payment packet. | min items: 1; max items: 100 |
| `sourceFileIds[]` | string | Yes | - | format: uuid |
| `fileName` | string | No | Optional payment packet PDF file name. A .pdf extension is added when omitted. | min length: 1; max length: 200 |
| `attachToCarrierPayment` | boolean | No | Attach the generated packet to the carrier payment and mark it INVOICED. | default: true |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/billing/packet/generate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceFileIds": [
    "<sourceFileIds>"
  ]
}'
```

#### Success response shape

Generated carrier payment packet

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | GenerateCarrierPaymentPacketResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.carrierPaymentId` | string | Yes | - | format: uuid |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.file` | LoadFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.includedFiles` | array<LoadFile> | Yes | - | - |
| `data.includedFiles[]` | LoadFile | Yes | - | - |
| `data.includedFiles[].id` | string | Yes | - | format: uuid |
| `data.includedFiles[].name` | string | Yes | - | - |
| `data.includedFiles[].path` | string | Yes | - | - |
| `data.includedFiles[].mime` | string \| null | Yes | - | - |
| `data.includedFiles[].type` | string | Yes | - | - |
| `data.includedFiles[].loadId` | string \| null | Yes | - | format: uuid |
| `data.includedFiles[].dispatchId` | string \| null | Yes | - | format: uuid |
| `data.includedFiles[].organizationId` | string | Yes | - | format: uuid |
| `data.includedFiles[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.includedFiles[].createdBy` | string \| null | Yes | - | format: uuid |
| `data.includedFiles[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.includedFiles[].systemGenerated` | boolean | Yes | - | - |
| `data.attachedToCarrierPayment` | boolean | Yes | - | - |
| `data.status` | string \| null | Yes | - | - |
| `data.paymentAmount` | string \| null | Yes | - | - |
| `data.dueDate` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/billing/ready

`ark.mark_carrier_payment_ready`

Moves a delivered carrier payment to READY after validating hold, billing info, and POD readiness, optionally saving a vendor invoice number.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierPaymentId` | string | No | Optional carrier payment ID. Omit to use the carrier payment for the load dispatch. | format: uuid |
| `vendorInvoiceNumber` | string \| null | No | Optional vendor invoice number to save before moving the payment to READY. | max length: 100 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/billing/ready' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Marked carrier payment ready

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | MarkCarrierPaymentReadyResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.carrierPaymentId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status` | string | Yes | - | one of: READY |
| `data.paymentAmount` | string | Yes | - | - |
| `data.dueDate` | string \| null | Yes | - | format: date-time |
| `data.vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.hasBillingInfo` | boolean | Yes | - | - |
| `data.hasPod` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### PATCH /api/v1/loads/{loadId}/dispatches/{dispatchId}/billing/vendor-invoice-number

`ark.update_carrier_vendor_invoice_number`

Updates the vendor invoice number for a delivered or ready carrier payment tied to a visible load dispatch.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierPaymentId` | string | No | Optional carrier payment ID. Omit to use the carrier payment for the load dispatch. | format: uuid |
| `vendorInvoiceNumber` | string \| null | Yes | Vendor invoice number to save. Use null to clear it. | max length: 100 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/billing/vendor-invoice-number' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "vendorInvoiceNumber": "<vendorInvoiceNumber>"
}'
```

#### Success response shape

Updated carrier vendor invoice number

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | UpdateCarrierVendorInvoiceNumberResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.carrierPaymentId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status` | string \| null | Yes | - | - |
| `data.vendorInvoiceNumber` | string \| null | Yes | - | - |
| `data.dueDate` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/cancel

`ark.cancel_dispatch`

Cancels an active dispatch for a visible load, returns the load to Available, clears dispatched stop actuals, and stops configured tracking sessions.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/cancel' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Cancelled dispatch

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.action` | string | Yes | - | one of: cancel_dispatch, tonu_deliver, tonu_recover, repower |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatch` | DispatchLifecycleDispatch | Yes | - | - |
| `data.dispatch.id` | string | Yes | - | format: uuid |
| `data.dispatch.loadId` | string \| null | Yes | - | format: uuid |
| `data.dispatch.carrierId` | string \| null | Yes | - | format: uuid |
| `data.dispatch.carrier` | object \| null | Yes | - | - |
| `data.dispatch.carrier.id` | string | Yes | - | format: uuid |
| `data.dispatch.carrier.name` | string \| null | Yes | - | - |
| `data.dispatch.active` | boolean | Yes | - | - |
| `data.dispatch.status` | string \| null | Yes | - | - |
| `data.trackingResult` | InactiveDispatchTrackingResult | Yes | - | - |
| `data.dispatchPayId` | string \| null | Yes | - | format: uuid |
| `data.repower` | DispatchRepowerResult | Yes | - | - |
| `data.repower.stopId` | string \| null | Yes | - | format: uuid |
| `data.repower.locationId` | string \| null | Yes | - | format: uuid |
| `data.repower.addressId` | string \| null | Yes | - | format: uuid |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/locations

`ark.add_manual_dispatch_location`

Adds a manual dispatch location history entry for a visible load dispatch and can send the configured location-update notification in the same workflow.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `one of: canEditLoad`, `one of: canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `city` | string | Yes | - | min length: 1; max length: 200 |
| `state` | string | Yes | - | min length: 1; max length: 6 |
| `country` | string | No | - | one of: USA, CAN, MEX; default: "USA" |
| `latitude` | number \| null | No | - | min: -90; max: 90 |
| `longitude` | number \| null | No | - | min: -180; max: 180 |
| `timezoneId` | string \| null | No | - | max length: 100 |
| `locationDateTime` | string | No | - | format: date-time |
| `sendNotification` | boolean | No | - | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/locations' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "city": "<city>",
  "state": "<state>"
}'
```

#### Success response shape

Added manual dispatch location

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ManualDispatchLocationData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | object | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.dispatch` | object | Yes | - | - |
| `data.dispatch.id` | string | Yes | - | format: uuid |
| `data.dispatch.loadId` | string | Yes | - | format: uuid |
| `data.dispatch.status` | string \| null | Yes | - | - |
| `data.dispatch.active` | boolean | Yes | - | - |
| `data.location` | ManualDispatchLocation | Yes | - | - |
| `data.location.id` | string | Yes | - | format: uuid |
| `data.location.dispatchId` | string | Yes | - | format: uuid |
| `data.location.city` | string | Yes | - | - |
| `data.location.state` | string | Yes | - | - |
| `data.location.country` | string | Yes | - | one of: USA, CAN, MEX |
| `data.location.latitude` | number \| null | Yes | - | - |
| `data.location.longitude` | number \| null | Yes | - | - |
| `data.location.timezoneId` | string \| null | Yes | - | - |
| `data.location.locationDateTime` | string \| null | Yes | - | format: date-time |
| `data.location.createdAt` | string | Yes | - | format: date-time |
| `data.location.createdBy` | string \| null | Yes | - | format: uuid |
| `data.location.dataSource` | string \| null | Yes | - | - |
| `data.notificationResult` | LoadNotificationSendResult \| null | Yes | - | - |
| `data.notificationSent` | boolean | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/loads/{loadId}/dispatches/{dispatchId}/notes

`ark.list_dispatch_notes`

Lists broker-entered notes for a visible load dispatch with creator context and newest-first pagination.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |
| `query.cursor` | string | No | Opaque cursor returned by the previous page. Prefer this over before_created_at. | - |
| `query.before_created_at` | string | No | - | format: date-time |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/notes' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Dispatch notes

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.items` | array<DispatchNote> | Yes | - | - |
| `data.items[]` | DispatchNote | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].dispatchId` | string | Yes | - | format: uuid |
| `data.items[].message` | string | Yes | - | - |
| `data.items[].createdAt` | string | Yes | - | format: date-time |
| `data.items[].createdBy` | string \| null | Yes | - | format: uuid |
| `data.items[].createdByName` | string \| null | Yes | - | - |
| `data.items[].createdByEmail` | string \| null | Yes | - | format: email |
| `data.pagination` | object | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |
| `data.pagination.nextBeforeCreatedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/notes

`ark.add_dispatch_note`

Adds a broker-visible note to an active visible dispatch for calls, exceptions, and follow-up context.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `message` | string | Yes | - | min length: 1; max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/notes' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "<message>"
}'
```

#### Success response shape

Added dispatch note

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.note` | DispatchNote | Yes | - | - |
| `data.note.id` | string | Yes | - | format: uuid |
| `data.note.dispatchId` | string | Yes | - | format: uuid |
| `data.note.message` | string | Yes | - | - |
| `data.note.createdAt` | string | Yes | - | format: date-time |
| `data.note.createdBy` | string \| null | Yes | - | format: uuid |
| `data.note.createdByName` | string \| null | Yes | - | - |
| `data.note.createdByEmail` | string \| null | Yes | - | format: email |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/rate-confirmation/create-and-send

`ark.create_and_send_rate_confirmation`

Generates a rate confirmation PDF for a visible dispatch and sends it to the dispatch contact, optionally using ARK e-sign.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `fileName` | string | No | Optional PDF file name. A .pdf extension is added when omitted. | min length: 1; max length: 200 |
| `esign` | boolean | No | When true, send an e-sign link instead of a PDF attachment. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/rate-confirmation/create-and-send' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Generated and sent rate confirmation

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RateConfirmationCreateAndSendResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.file` | LoadFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.send` | RateConfirmationSendResult | Yes | - | - |
| `data.send.loadId` | string | Yes | - | format: uuid |
| `data.send.dispatchId` | string | Yes | - | format: uuid |
| `data.send.fileId` | string | Yes | - | format: uuid |
| `data.send.load` | Load | Yes | - | - |
| `data.send.load.id` | string | Yes | - | format: uuid |
| `data.send.load.loadNumber` | string | Yes | - | - |
| `data.send.load.status` | string \| null | Yes | - | - |
| `data.send.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.send.load.customer` | object \| null | Yes | - | - |
| `data.send.load.customer.id` | string | Yes | - | format: uuid |
| `data.send.load.customer.name` | string \| null | Yes | - | - |
| `data.send.load.activeDispatch` | object \| null | Yes | - | - |
| `data.send.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.send.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.send.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.send.load.pickupNumber` | string \| null | Yes | - | - |
| `data.send.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.send.load.billOfLading` | string \| null | Yes | - | - |
| `data.send.load.product` | string \| null | Yes | - | - |
| `data.send.load.description` | string \| null | Yes | - | - |
| `data.send.load.createdAt` | string | Yes | - | format: date-time |
| `data.send.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.send.esign` | boolean | Yes | - | - |
| `data.send.esignId` | string \| null | Yes | - | format: uuid |
| `data.send.recipientEmail` | string | Yes | - | - |
| `data.send.brokerEmail` | string | Yes | - | - |
| `data.send.message` | string | Yes | - | - |
| `data.send.loadStatusUpdated` | boolean | Yes | - | - |
| `data.send.loadBoardRemovalProcessed` | boolean | Yes | - | - |
| `data.send.sideEffectError` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 402 | Organization does not currently have product access for this operation |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/rate-confirmation/generate

`ark.generate_rate_confirmation`

Generates and stores a rate confirmation PDF for a visible dispatched load without sending it.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `fileName` | string | No | Optional PDF file name. A .pdf extension is added when omitted. | min length: 1; max length: 200 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/rate-confirmation/generate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Generated rate confirmation

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RateConfirmationGenerateResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.file` | LoadFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/rate-confirmation/send

`ark.send_rate_confirmation`

Sends an existing rate confirmation file to the dispatch contact, optionally using ARK e-sign.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `fileId` | string | Yes | - | format: uuid |
| `esign` | boolean | No | When true, send an e-sign link instead of a PDF attachment. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/rate-confirmation/send' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "<fileId>"
}'
```

#### Success response shape

Sent rate confirmation

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RateConfirmationSendResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.esign` | boolean | Yes | - | - |
| `data.esignId` | string \| null | Yes | - | format: uuid |
| `data.recipientEmail` | string | Yes | - | - |
| `data.brokerEmail` | string | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.loadStatusUpdated` | boolean | Yes | - | - |
| `data.loadBoardRemovalProcessed` | boolean | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 402 | Organization does not currently have product access for this operation |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/repower

`ark.repower_load`

Repowers a visible load by closing the active dispatch, inserting a repower pickup stop, returning the load to Available, and stopping configured tracking sessions.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `address` | string | Yes | - | min length: 1; max length: 500 |
| `city` | string | Yes | - | min length: 1; max length: 200 |
| `state` | string | Yes | - | min length: 1; max length: 20 |
| `zip` | string | Yes | - | min length: 1; max length: 30 |
| `comment` | string | No | - | default: ""; max length: 5000 |
| `latitude` | number \| null | No | - | - |
| `longitude` | number \| null | No | - | - |
| `timezoneId` | string \| null | No | - | max length: 100 |
| `country` | string | No | - | one of: USA, CAN, MEX; default: "USA" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/repower' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "<address>",
  "city": "<city>",
  "state": "<state>",
  "zip": "<zip>"
}'
```

#### Success response shape

Repowered load

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.action` | string | Yes | - | one of: cancel_dispatch, tonu_deliver, tonu_recover, repower |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatch` | DispatchLifecycleDispatch | Yes | - | - |
| `data.dispatch.id` | string | Yes | - | format: uuid |
| `data.dispatch.loadId` | string \| null | Yes | - | format: uuid |
| `data.dispatch.carrierId` | string \| null | Yes | - | format: uuid |
| `data.dispatch.carrier` | object \| null | Yes | - | - |
| `data.dispatch.carrier.id` | string | Yes | - | format: uuid |
| `data.dispatch.carrier.name` | string \| null | Yes | - | - |
| `data.dispatch.active` | boolean | Yes | - | - |
| `data.dispatch.status` | string \| null | Yes | - | - |
| `data.trackingResult` | InactiveDispatchTrackingResult | Yes | - | - |
| `data.dispatchPayId` | string \| null | Yes | - | format: uuid |
| `data.repower` | DispatchRepowerResult | Yes | - | - |
| `data.repower.stopId` | string \| null | Yes | - | format: uuid |
| `data.repower.locationId` | string \| null | Yes | - | format: uuid |
| `data.repower.addressId` | string \| null | Yes | - | format: uuid |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/tonu-deliver

`ark.mark_dispatch_tonu_delivered`

Marks an active dispatch TONU and delivered, sets TONU fees, runs ARK's deliver-and-bill workflow, and stops configured tracking sessions.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierTonuFee` | number | Yes | - | min: 0 |
| `customerTonuFee` | number \| null | No | - | min: 0 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/tonu-deliver' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "carrierTonuFee": 0
}'
```

#### Success response shape

Marked dispatch TONU delivered

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.action` | string | Yes | - | one of: cancel_dispatch, tonu_deliver, tonu_recover, repower |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatch` | DispatchLifecycleDispatch | Yes | - | - |
| `data.dispatch.id` | string | Yes | - | format: uuid |
| `data.dispatch.loadId` | string \| null | Yes | - | format: uuid |
| `data.dispatch.carrierId` | string \| null | Yes | - | format: uuid |
| `data.dispatch.carrier` | object \| null | Yes | - | - |
| `data.dispatch.carrier.id` | string | Yes | - | format: uuid |
| `data.dispatch.carrier.name` | string \| null | Yes | - | - |
| `data.dispatch.active` | boolean | Yes | - | - |
| `data.dispatch.status` | string \| null | Yes | - | - |
| `data.trackingResult` | InactiveDispatchTrackingResult | Yes | - | - |
| `data.dispatchPayId` | string \| null | Yes | - | format: uuid |
| `data.repower` | DispatchRepowerResult | Yes | - | - |
| `data.repower.stopId` | string \| null | Yes | - | format: uuid |
| `data.repower.locationId` | string \| null | Yes | - | format: uuid |
| `data.repower.addressId` | string \| null | Yes | - | format: uuid |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/dispatches/{dispatchId}/tonu-recover

`ark.mark_dispatch_tonu_recovered`

Marks an active dispatch TONU and recovered, sets TONU fees, returns the load to Available, and stops configured tracking sessions.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.dispatchId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierTonuFee` | number | Yes | - | min: 0 |
| `customerTonuFee` | number \| null | No | - | min: 0 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/dispatches/<dispatchId>/tonu-recover' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "carrierTonuFee": 0
}'
```

#### Success response shape

Marked dispatch TONU recovered

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.action` | string | Yes | - | one of: cancel_dispatch, tonu_deliver, tonu_recover, repower |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatch` | DispatchLifecycleDispatch | Yes | - | - |
| `data.dispatch.id` | string | Yes | - | format: uuid |
| `data.dispatch.loadId` | string \| null | Yes | - | format: uuid |
| `data.dispatch.carrierId` | string \| null | Yes | - | format: uuid |
| `data.dispatch.carrier` | object \| null | Yes | - | - |
| `data.dispatch.carrier.id` | string | Yes | - | format: uuid |
| `data.dispatch.carrier.name` | string \| null | Yes | - | - |
| `data.dispatch.active` | boolean | Yes | - | - |
| `data.dispatch.status` | string \| null | Yes | - | - |
| `data.trackingResult` | InactiveDispatchTrackingResult | Yes | - | - |
| `data.dispatchPayId` | string \| null | Yes | - | format: uuid |
| `data.repower` | DispatchRepowerResult | Yes | - | - |
| `data.repower.stopId` | string \| null | Yes | - | format: uuid |
| `data.repower.locationId` | string \| null | Yes | - | format: uuid |
| `data.repower.addressId` | string \| null | Yes | - | format: uuid |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/loads/{loadId}/files

`ark.list_load_files`

Lists files and documents attached to a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `query.type` | string | No | Optional document type filter, such as POD, BOL, or Other. | - |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/files' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load files

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.items` | array<LoadFile> | Yes | - | - |
| `data.items[]` | LoadFile | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].name` | string | Yes | - | - |
| `data.items[].path` | string | Yes | - | - |
| `data.items[].mime` | string \| null | Yes | - | - |
| `data.items[].type` | string | Yes | - | - |
| `data.items[].loadId` | string \| null | Yes | - | format: uuid |
| `data.items[].dispatchId` | string \| null | Yes | - | format: uuid |
| `data.items[].organizationId` | string | Yes | - | format: uuid |
| `data.items[].carrierId` | string \| null | Yes | - | format: uuid |
| `data.items[].createdBy` | string \| null | Yes | - | format: uuid |
| `data.items[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.items[].systemGenerated` | boolean | Yes | - | - |
| `data.pagination` | object | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### DELETE /api/v1/loads/{loadId}/files/{fileId}

`ark.delete_load_file`

Deletes a user-uploaded load file from storage and the files table. System-generated files are protected.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.fileId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/loads/<loadId>/files/<fileId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deleted file

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.fileId` | string | Yes | - | format: uuid |
| `data.deleted` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/loads/{loadId}/files/{fileId}/download-url

`ark.get_load_file_download_url`

Creates a short-lived signed download URL for a visible load file.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.fileId` | string | Yes | - | format: uuid |
| `query.expires_in_seconds` | integer | No | - | default: 3600; min: 60; max: 86400 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/files/<fileId>/download-url' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Signed download URL

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.file` | LoadFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.signedUrl` | string | Yes | - | - |
| `data.expiresInSeconds` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/loads/{loadId}/files/finalize-upload

`ark.finalize_load_file_upload`

Finalizes a prepared upload by inserting the file record, clearing the pending upload, updating POD signature comments, and sending POD upload notifications when applicable.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `filePath` | string | Yes | - | min length: 1; max length: 2000 |
| `fileName` | string | No | - | min length: 1; max length: 255 |
| `fileType` | string | Yes | - | min length: 1; max length: 100 |
| `mimeType` | string | Yes | - | min length: 1; max length: 255 |
| `dispatchId` | string | No | - | format: uuid |
| `podSignedBy` | string \| null | No | - | max length: 200 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/files/finalize-upload' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "filePath": "<filePath>",
  "fileType": "<fileType>",
  "mimeType": "<mimeType>"
}'
```

#### Success response shape

Finalized upload

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.file` | LoadFile | Yes | - | - |
| `data.file.id` | string | Yes | - | format: uuid |
| `data.file.name` | string | Yes | - | - |
| `data.file.path` | string | Yes | - | - |
| `data.file.mime` | string \| null | Yes | - | - |
| `data.file.type` | string | Yes | - | - |
| `data.file.loadId` | string \| null | Yes | - | format: uuid |
| `data.file.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.file.organizationId` | string | Yes | - | format: uuid |
| `data.file.carrierId` | string \| null | Yes | - | format: uuid |
| `data.file.createdBy` | string \| null | Yes | - | format: uuid |
| `data.file.createdAt` | string \| null | Yes | - | format: date-time |
| `data.file.systemGenerated` | boolean | Yes | - | - |
| `data.podNotificationSent` | boolean | Yes | - | - |
| `data.podSignatureCommentUpdated` | boolean | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/files/prepare-upload

`ark.prepare_load_file_upload`

Creates a signed upload URL and pending upload record for attaching a file to a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `fileName` | string | Yes | - | min length: 1; max length: 255 |
| `fileType` | string | Yes | - | min length: 1; max length: 100 |
| `mimeType` | string | Yes | - | min length: 1; max length: 255 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/files/prepare-upload' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "<fileName>",
  "fileType": "<fileType>",
  "mimeType": "<mimeType>"
}'
```

#### Success response shape

Prepared upload

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.fileName` | string | Yes | - | - |
| `data.fileType` | string | Yes | - | - |
| `data.mimeType` | string | Yes | - | - |
| `data.filePath` | string | Yes | - | - |
| `data.pendingUploadId` | string | Yes | - | format: uuid |
| `data.signedUrl` | string | Yes | - | - |
| `data.token` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/lock

`ark.lock_load`

Locks a visible available load for dispatch or manual editing by the connected actor.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `trigger` | string | No | - | one of: manual, auto_dispatch_open; default: "manual" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/lock' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Load lock result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.message` | string \| null | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.lockedBy` | string \| null | Yes | - | format: uuid |
| `data.lockedByName` | string \| null | Yes | - | - |
| `data.lockedAt` | string \| null | Yes | - | format: date-time |
| `data.lockExpiresAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/miles/calculate

`ark.calculate_load_miles`

Calculates truck route miles for a visible load using stop coordinates, stores total/per-stop miles, and refreshes route geometry segments.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `stops` | array<RouteCoordinateStopInput> | Yes | Stop coordinates ordered by stopIndex. Count must match the persisted stops. | min items: 2; max items: 25 |
| `stops[]` | RouteCoordinateStopInput | Yes | - | - |
| `stops[].lat` | number | Yes | - | min: -90; max: 90 |
| `stops[].lng` | number | Yes | - | min: -180; max: 180 |
| `stops[].stopIndex` | integer | Yes | - | min: 0 |
| `trailer` | string | No | - | min length: 1; max length: 100 |
| `size` | string | No | - | min length: 1; max length: 50 |
| `dimensions` | RouteDimensionsInput | No | - | - |
| `dimensions.length` | number | No | - | - |
| `dimensions.width` | number | No | - | - |
| `dimensions.height` | number | No | - | - |
| `dimensions.weight` | number | No | - | - |
| `hazmat` | boolean | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/miles/calculate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "stops": [
    {
      "lat": -90,
      "lng": -180,
      "stopIndex": 0
    },
    {
      "lat": -90,
      "lng": -180,
      "stopIndex": 0
    }
  ]
}'
```

#### Success response shape

Calculated load miles

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RouteMilesResult | Yes | - | - |
| `data.loadId` | string | No | - | format: uuid |
| `data.spotQuoteId` | string | No | - | format: uuid |
| `data.totalMiles` | number | Yes | - | - |
| `data.perStopMiles` | array<number> | Yes | - | - |
| `data.perStopMiles[]` | number | Yes | - | - |
| `data.durationSeconds` | integer | Yes | - | - |
| `data.typicalDurationSeconds` | integer \| null | Yes | - | - |
| `data.routeParamsHash` | string | Yes | - | - |
| `data.segmentCount` | integer | Yes | - | min: 0 |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### DELETE /api/v1/loads/{loadId}/notifications

`ark.delete_load_notification_settings`

Deletes tracking notification settings for a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/loads/<loadId>/notifications' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deleted load notification settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.deleted` | unknown | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/loads/{loadId}/notifications

`ark.get_load_notification_settings`

Returns tracking notification settings for a visible load, including recipients, event toggles, throttle interval, and last sent timestamp.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/notifications' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load notification settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | LoadNotificationSettingsData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | object | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.settings` | LoadNotificationSettings | Yes | - | - |
| `data.settings.id` | string \| null | Yes | - | - |
| `data.settings.loadId` | string | Yes | - | format: uuid |
| `data.settings.organizationId` | string | Yes | - | format: uuid |
| `data.settings.emails` | array<string> | Yes | - | - |
| `data.settings.emails[]` | string | Yes | - | format: email |
| `data.settings.enabled` | boolean | Yes | - | - |
| `data.settings.notifyOnArrival` | boolean | Yes | - | - |
| `data.settings.notifyOnDeparture` | boolean | Yes | - | - |
| `data.settings.notificationIntervalMinutes` | integer | Yes | - | min: 15; max: 1440 |
| `data.settings.lastSentAt` | string \| null | Yes | - | format: date-time |
| `data.settings.notes` | string \| null | Yes | - | - |
| `data.settings.exists` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PUT /api/v1/loads/{loadId}/notifications

`ark.set_load_notification_settings`

Creates or updates tracking notification settings for a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `emails` | array<string> | Yes | - | min items: 1; max items: 50 |
| `emails[]` | string | Yes | - | format: email; max length: 500 |
| `enabled` | boolean | Yes | - | - |
| `notifyOnArrival` | boolean | No | - | default: true |
| `notifyOnDeparture` | boolean | No | - | default: true |
| `notificationIntervalMinutes` | integer | No | - | default: 120; min: 15; max: 1440 |
| `notes` | string \| null | No | - | max length: 5000 |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/loads/<loadId>/notifications' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "<emails>"
  ],
  "enabled": false
}'
```

#### Success response shape

Saved load notification settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | LoadNotificationSettingsData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | object | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.settings` | LoadNotificationSettings | Yes | - | - |
| `data.settings.id` | string \| null | Yes | - | - |
| `data.settings.loadId` | string | Yes | - | format: uuid |
| `data.settings.organizationId` | string | Yes | - | format: uuid |
| `data.settings.emails` | array<string> | Yes | - | - |
| `data.settings.emails[]` | string | Yes | - | format: email |
| `data.settings.enabled` | boolean | Yes | - | - |
| `data.settings.notifyOnArrival` | boolean | Yes | - | - |
| `data.settings.notifyOnDeparture` | boolean | Yes | - | - |
| `data.settings.notificationIntervalMinutes` | integer | Yes | - | min: 15; max: 1440 |
| `data.settings.lastSentAt` | string \| null | Yes | - | format: date-time |
| `data.settings.notes` | string \| null | Yes | - | - |
| `data.settings.exists` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/pay-holds

`ark.create_pay_hold`

Creates a pay hold or claim for a visible load so billing can pause payment until the issue is resolved.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canMakeAdjustments`, `one of: canViewBilling`, `one of: canViewPayHoldsReport`, `one of: canEditLoad`, `one of: canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `value` | number \| null | No | Optional claim value. Required when isClaim is true. | max: 99999999.99 |
| `notes` | string | No | Operational notes explaining why the load is being held. | max length: 5000 |
| `isClaim` | boolean | No | Set true when the hold represents a claim amount. | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/pay-holds' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Created pay hold

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | PayHoldOperationResult | Yes | - | - |
| `data.payHoldId` | string | Yes | - | format: uuid |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.value` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.isClaim` | boolean | Yes | - | - |
| `data.status` | string | Yes | - | one of: active, resolved |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.createdBy` | string \| null | Yes | - | - |
| `data.resolvedAt` | string \| null | Yes | - | format: date-time |
| `data.resolvedBy` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/pay-holds/resolve

`ark.resolve_pay_hold`

Resolves an active pay hold or claim for a visible load after the billing issue has been cleared.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:write` |
| ARK permissions | `canViewLoads`, `canMakeAdjustments`, `one of: canViewBilling`, `one of: canViewPayHoldsReport`, `one of: canEditLoad`, `one of: canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `payHoldId` | string | Yes | Exact active pay hold ID to resolve. | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/pay-holds/resolve' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "payHoldId": "<payHoldId>"
}'
```

#### Success response shape

Resolved pay hold

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | PayHoldOperationResult | Yes | - | - |
| `data.payHoldId` | string | Yes | - | format: uuid |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.value` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.isClaim` | boolean | Yes | - | - |
| `data.status` | string | Yes | - | one of: active, resolved |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.createdBy` | string \| null | Yes | - | - |
| `data.resolvedAt` | string \| null | Yes | - | format: date-time |
| `data.resolvedBy` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/loads/{loadId}/restore

`ark.restore_load`

Restores an archived visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canDeleteLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/restore' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Restored load

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |

#### Errors

_No operation-specific error responses._

### PUT /api/v1/loads/{loadId}/route-segments

`ark.save_load_route_segments`

Replaces stored route geometry segments for a visible load using precomputed section mileage, duration, and encoded polyline data.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `routeParamsHash` | string \| null | No | Stable hash of the route parameters. Required when sections are provided. | min length: 1 |
| `sections` | array<RouteSectionInput> | No | - | default: []; max items: 25 |
| `sections[]` | RouteSectionInput | No | - | - |
| `sections[].miles` | number | No | - | min: 0 |
| `sections[].durationSeconds` | integer | No | - | min: 0 |
| `sections[].typicalDurationSeconds` | integer \| null | No | - | min: 0 |
| `sections[].encodedPolyline` | string | No | - | min length: 1 |
| `clearExisting` | boolean | No | - | default: false |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/loads/<loadId>/route-segments' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Saved load route segments

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SaveLoadRouteSegmentsResult | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.segmentCount` | integer | Yes | - | min: 0 |
| `data.clearedExisting` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/status

`ark.override_load_status`

Overrides a visible load from Pending to Dispatched using the existing status override rule.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canOverrideLoadStatus` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `fromStatus` | string | Yes | - | one of: Pending |
| `toStatus` | string | Yes | - | one of: Dispatched |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/status' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "fromStatus": "Pending",
  "toStatus": "Dispatched"
}'
```

#### Success response shape

Updated load

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | Load | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.loadNumber` | string | Yes | - | - |
| `data.status` | string \| null | Yes | - | - |
| `data.teamId` | string \| null | Yes | - | format: uuid |
| `data.customer` | object \| null | Yes | - | - |
| `data.customer.id` | string | Yes | - | format: uuid |
| `data.customer.name` | string \| null | Yes | - | - |
| `data.activeDispatch` | object \| null | Yes | - | - |
| `data.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.activeDispatch.status` | string \| null | Yes | - | - |
| `data.pickupNumber` | string \| null | Yes | - | - |
| `data.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.billOfLading` | string \| null | Yes | - | - |
| `data.product` | string \| null | Yes | - | - |
| `data.description` | string \| null | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Current load status did not match fromStatus |

### GET /api/v1/loads/{loadId}/stops

`ark.list_load_stops`

Returns visible pickup, delivery, and intermediate stops for a load, including scheduled and actual timing fields.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `query.limit` | integer | No | - | default: 100; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/stops' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Load stops

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.stops` | array<LoadStop> | Yes | - | - |
| `data.stops[]` | LoadStop | Yes | - | - |
| `data.stops[].id` | string | Yes | - | format: uuid |
| `data.stops[].loadId` | string \| null | Yes | - | format: uuid |
| `data.stops[].locationId` | string \| null | Yes | - | format: uuid |
| `data.stops[].index` | integer \| null | Yes | - | - |
| `data.stops[].type` | string \| null | Yes | - | - |
| `data.stops[].referenceNum` | string \| null | Yes | - | - |
| `data.stops[].pieces` | integer \| null | Yes | - | - |
| `data.stops[].weight` | number \| null | Yes | - | - |
| `data.stops[].comment` | string \| null | Yes | - | - |
| `data.stops[].dispatchId` | string \| null | Yes | - | format: uuid |
| `data.stops[].schedulingType` | string \| null | Yes | - | one of: fcfs, appointment, null |
| `data.stops[].arrivalTime` | string \| null | Yes | - | format: date-time |
| `data.stops[].arrivalTime2` | string \| null | Yes | - | format: date-time |
| `data.stops[].inTime` | string \| null | Yes | - | format: date-time |
| `data.stops[].outTime` | string \| null | Yes | - | format: date-time |
| `data.stops[].inTimeSetByUserId` | string \| null | Yes | - | format: uuid |
| `data.stops[].inTimeSetBySystem` | string \| null | Yes | - | - |
| `data.stops[].inTimeSetAt` | string \| null | Yes | - | format: date-time |
| `data.stops[].outTimeSetByUserId` | string \| null | Yes | - | format: uuid |
| `data.stops[].outTimeSetBySystem` | string \| null | Yes | - | - |
| `data.stops[].outTimeSetAt` | string \| null | Yes | - | format: date-time |
| `data.stops[].onTimeCounted` | boolean | Yes | - | - |
| `data.stops[].milesToNextStop` | number \| null | Yes | - | - |
| `data.stops[].durationToNextStopSeconds` | integer \| null | Yes | - | - |
| `data.stops[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.stops[].location` | LoadStopLocation | Yes | - | - |
| `data.stops[].location.id` | string \| null | Yes | - | format: uuid |
| `data.stops[].location.name` | string \| null | Yes | - | - |
| `data.stops[].location.address` | LocationAddress | Yes | - | - |
| `data.stops[].location.address.id` | string \| null | Yes | - | format: uuid |
| `data.stops[].location.address.company` | string \| null | Yes | - | - |
| `data.stops[].location.address.name` | string \| null | Yes | - | - |
| `data.stops[].location.address.address` | string \| null | Yes | - | - |
| `data.stops[].location.address.address2` | string \| null | Yes | - | - |
| `data.stops[].location.address.city` | string \| null | Yes | - | - |
| `data.stops[].location.address.state` | string \| null | Yes | - | - |
| `data.stops[].location.address.zip` | string \| null | Yes | - | - |
| `data.stops[].location.address.phone` | string \| null | Yes | - | - |
| `data.stops[].location.address.email` | string \| null | Yes | - | - |
| `data.stops[].location.address.latitude` | number \| null | Yes | - | - |
| `data.stops[].location.address.longitude` | number \| null | Yes | - | - |
| `data.stops[].location.address.timezoneId` | string \| null | Yes | - | - |
| `data.stops[].location.address.country` | string \| null | Yes | - | one of: USA, CAN, MEX, null |
| `data.stops[].location.customer` | LocationCustomerRef | Yes | - | - |
| `data.stops[].location.customer.id` | string | Yes | - | format: uuid |
| `data.stops[].location.customer.name` | string \| null | Yes | - | - |
| `data.stops[].location.customer.code` | string \| null | Yes | - | - |
| `data.truncated` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/loads/{loadId}/stops/{stopId}

`ark.update_load_stop`

Updates scheduled stop times, scheduling type, reference number, pieces, weight, or comment for a visible load stop. Actual arrival and departure event recording is intentionally handled by a separate workflow action.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.stopId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `arrivalTime` | string \| null | No | - | format: date-time |
| `arrivalTime2` | string \| null | No | - | format: date-time |
| `schedulingType` | string \| null | No | - | one of: fcfs, appointment, null |
| `referenceNum` | string \| null | No | - | max length: 100 |
| `pieces` | integer \| null | No | - | min: 0 |
| `weight` | number \| null | No | - | min: 0 |
| `comment` | string \| null | No | - | max length: 5000 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/loads/<loadId>/stops/<stopId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated load stop

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.stop` | LoadStop | Yes | - | - |
| `data.stop.id` | string | Yes | - | format: uuid |
| `data.stop.loadId` | string \| null | Yes | - | format: uuid |
| `data.stop.locationId` | string \| null | Yes | - | format: uuid |
| `data.stop.index` | integer \| null | Yes | - | - |
| `data.stop.type` | string \| null | Yes | - | - |
| `data.stop.referenceNum` | string \| null | Yes | - | - |
| `data.stop.pieces` | integer \| null | Yes | - | - |
| `data.stop.weight` | number \| null | Yes | - | - |
| `data.stop.comment` | string \| null | Yes | - | - |
| `data.stop.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.stop.schedulingType` | string \| null | Yes | - | one of: fcfs, appointment, null |
| `data.stop.arrivalTime` | string \| null | Yes | - | format: date-time |
| `data.stop.arrivalTime2` | string \| null | Yes | - | format: date-time |
| `data.stop.inTime` | string \| null | Yes | - | format: date-time |
| `data.stop.outTime` | string \| null | Yes | - | format: date-time |
| `data.stop.inTimeSetByUserId` | string \| null | Yes | - | format: uuid |
| `data.stop.inTimeSetBySystem` | string \| null | Yes | - | - |
| `data.stop.inTimeSetAt` | string \| null | Yes | - | format: date-time |
| `data.stop.outTimeSetByUserId` | string \| null | Yes | - | format: uuid |
| `data.stop.outTimeSetBySystem` | string \| null | Yes | - | - |
| `data.stop.outTimeSetAt` | string \| null | Yes | - | format: date-time |
| `data.stop.onTimeCounted` | boolean | Yes | - | - |
| `data.stop.milesToNextStop` | number \| null | Yes | - | - |
| `data.stop.durationToNextStopSeconds` | integer \| null | Yes | - | - |
| `data.stop.createdAt` | string \| null | Yes | - | format: date-time |
| `data.stop.location` | LoadStopLocation | Yes | - | - |
| `data.stop.location.id` | string \| null | Yes | - | format: uuid |
| `data.stop.location.name` | string \| null | Yes | - | - |
| `data.stop.location.address` | LocationAddress | Yes | - | - |
| `data.stop.location.address.id` | string \| null | Yes | - | format: uuid |
| `data.stop.location.address.company` | string \| null | Yes | - | - |
| `data.stop.location.address.name` | string \| null | Yes | - | - |
| `data.stop.location.address.address` | string \| null | Yes | - | - |
| `data.stop.location.address.address2` | string \| null | Yes | - | - |
| `data.stop.location.address.city` | string \| null | Yes | - | - |
| `data.stop.location.address.state` | string \| null | Yes | - | - |
| `data.stop.location.address.zip` | string \| null | Yes | - | - |
| `data.stop.location.address.phone` | string \| null | Yes | - | - |
| `data.stop.location.address.email` | string \| null | Yes | - | - |
| `data.stop.location.address.latitude` | number \| null | Yes | - | - |
| `data.stop.location.address.longitude` | number \| null | Yes | - | - |
| `data.stop.location.address.timezoneId` | string \| null | Yes | - | - |
| `data.stop.location.address.country` | string \| null | Yes | - | one of: USA, CAN, MEX, null |
| `data.stop.location.customer` | LocationCustomerRef | Yes | - | - |
| `data.stop.location.customer.id` | string | Yes | - | format: uuid |
| `data.stop.location.customer.name` | string \| null | Yes | - | - |
| `data.stop.location.customer.code` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/stops/{stopId}/event

`ark.record_load_stop_event`

Records or clears an actual arrival or departure time for a visible dispatched load stop and runs configured milestone side effects.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `one of: canEditLoad`, `one of: canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.stopId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `eventType` | string | Yes | - | one of: arrival, departure |
| `action` | string | No | - | one of: set, clear; default: "set" |
| `occurredAt` | string | No | Required when action is set. Omit when action is clear. | format: date-time |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/stops/<stopId>/event' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "eventType": "arrival"
}'
```

#### Success response shape

Recorded load stop event

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.stop` | LoadStop | Yes | - | - |
| `data.stop.id` | string | Yes | - | format: uuid |
| `data.stop.loadId` | string \| null | Yes | - | format: uuid |
| `data.stop.locationId` | string \| null | Yes | - | format: uuid |
| `data.stop.index` | integer \| null | Yes | - | - |
| `data.stop.type` | string \| null | Yes | - | - |
| `data.stop.referenceNum` | string \| null | Yes | - | - |
| `data.stop.pieces` | integer \| null | Yes | - | - |
| `data.stop.weight` | number \| null | Yes | - | - |
| `data.stop.comment` | string \| null | Yes | - | - |
| `data.stop.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.stop.schedulingType` | string \| null | Yes | - | one of: fcfs, appointment, null |
| `data.stop.arrivalTime` | string \| null | Yes | - | format: date-time |
| `data.stop.arrivalTime2` | string \| null | Yes | - | format: date-time |
| `data.stop.inTime` | string \| null | Yes | - | format: date-time |
| `data.stop.outTime` | string \| null | Yes | - | format: date-time |
| `data.stop.inTimeSetByUserId` | string \| null | Yes | - | format: uuid |
| `data.stop.inTimeSetBySystem` | string \| null | Yes | - | - |
| `data.stop.inTimeSetAt` | string \| null | Yes | - | format: date-time |
| `data.stop.outTimeSetByUserId` | string \| null | Yes | - | format: uuid |
| `data.stop.outTimeSetBySystem` | string \| null | Yes | - | - |
| `data.stop.outTimeSetAt` | string \| null | Yes | - | format: date-time |
| `data.stop.onTimeCounted` | boolean | Yes | - | - |
| `data.stop.milesToNextStop` | number \| null | Yes | - | - |
| `data.stop.durationToNextStopSeconds` | integer \| null | Yes | - | - |
| `data.stop.createdAt` | string \| null | Yes | - | format: date-time |
| `data.stop.location` | LoadStopLocation | Yes | - | - |
| `data.stop.location.id` | string \| null | Yes | - | format: uuid |
| `data.stop.location.name` | string \| null | Yes | - | - |
| `data.stop.location.address` | LocationAddress | Yes | - | - |
| `data.stop.location.address.id` | string \| null | Yes | - | format: uuid |
| `data.stop.location.address.company` | string \| null | Yes | - | - |
| `data.stop.location.address.name` | string \| null | Yes | - | - |
| `data.stop.location.address.address` | string \| null | Yes | - | - |
| `data.stop.location.address.address2` | string \| null | Yes | - | - |
| `data.stop.location.address.city` | string \| null | Yes | - | - |
| `data.stop.location.address.state` | string \| null | Yes | - | - |
| `data.stop.location.address.zip` | string \| null | Yes | - | - |
| `data.stop.location.address.phone` | string \| null | Yes | - | - |
| `data.stop.location.address.email` | string \| null | Yes | - | - |
| `data.stop.location.address.latitude` | number \| null | Yes | - | - |
| `data.stop.location.address.longitude` | number \| null | Yes | - | - |
| `data.stop.location.address.timezoneId` | string \| null | Yes | - | - |
| `data.stop.location.address.country` | string \| null | Yes | - | one of: USA, CAN, MEX, null |
| `data.stop.location.customer` | LocationCustomerRef | Yes | - | - |
| `data.stop.location.customer.id` | string | Yes | - | format: uuid |
| `data.stop.location.customer.name` | string \| null | Yes | - | - |
| `data.stop.location.customer.code` | string \| null | Yes | - | - |
| `data.eventType` | string | Yes | - | one of: arrival, departure |
| `data.action` | string | Yes | - | one of: set, clear |
| `data.occurredAt` | string \| null | Yes | - | format: date-time |
| `data.stopIndex` | integer | Yes | - | - |
| `data.notificationResult` | object \| null | No | - | - |
| `data.ediResult` | object \| null | No | - | - |
| `data.project44Result` | object \| null | No | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/loads/{loadId}/tracking

`ark.get_tracking_status`

Returns active MacroPoint, TruckerTools, and internal ARK tracking sessions for a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/tracking' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Tracking status

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | TrackingStatusData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.sessions` | array<TrackingSessionSummary> | Yes | - | - |
| `data.sessions[]` | TrackingSessionSummary | Yes | - | - |
| `data.sessions[].provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.sessions[].trackingId` | string | Yes | - | - |
| `data.sessions[].loadId` | string | Yes | - | format: uuid |
| `data.sessions[].preferred` | boolean | Yes | - | - |
| `data.sessions[].status` | string | Yes | - | one of: active, pending_driver |
| `data.sessions[].startedAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].lastUpdatedAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].pendingExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].trackingMethod` | string \| null | Yes | - | - |
| `data.sessions[].driverActionRequired` | boolean | Yes | - | - |
| `data.sessions[].temperature` | object \| null | Yes | - | - |
| `data.preferredSession` | TrackingSessionSummary \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/loads/{loadId}/tracking

`ark.update_tracking`

Updates timing, notification, notes, driver, equipment, or reefer settings on an active load tracking session.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | TrackingProvider | No | - | one of: macropoint, truckertools, internal |
| `trackingId` | string | No | - | max length: 200 |
| `trackStartDateTime` | string | No | - | max length: 100 |
| `trackDurationHours` | number | No | - | min: 1; max: 720 |
| `trackIntervalMinutes` | integer | No | - | min: 5; max: 1440 |
| `emailCopiesTo` | string \| null | No | - | max length: 1000 |
| `notes` | string \| null | No | - | max length: 5000 |
| `minTemp` | number \| null | No | - | - |
| `maxTemp` | number \| null | No | - | - |
| `tempUoM` | string | No | - | one of: fahrenheit, celsius |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/loads/<loadId>/tracking' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated tracking

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.provider` | string \| null | Yes | - | one of: macropoint, truckertools, internal, null |
| `data.trackingId` | string \| null | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.result` | TrackingProviderResult | Yes | - | - |
| `data.result.success` | boolean | Yes | - | - |
| `data.result.message` | string | Yes | - | - |
| `data.result.trackingId` | string \| null | Yes | - | - |
| `data.result.errorCode` | string \| null | Yes | - | - |
| `data.status` | TrackingStatusData | Yes | - | - |
| `data.status.loadId` | string | Yes | - | format: uuid |
| `data.status.load` | Load | Yes | - | - |
| `data.status.load.id` | string | Yes | - | format: uuid |
| `data.status.load.loadNumber` | string | Yes | - | - |
| `data.status.load.status` | string \| null | Yes | - | - |
| `data.status.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.status.load.customer` | object \| null | Yes | - | - |
| `data.status.load.customer.id` | string | Yes | - | format: uuid |
| `data.status.load.customer.name` | string \| null | Yes | - | - |
| `data.status.load.activeDispatch` | object \| null | Yes | - | - |
| `data.status.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.status.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.status.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.status.load.pickupNumber` | string \| null | Yes | - | - |
| `data.status.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.status.load.billOfLading` | string \| null | Yes | - | - |
| `data.status.load.product` | string \| null | Yes | - | - |
| `data.status.load.description` | string \| null | Yes | - | - |
| `data.status.load.createdAt` | string | Yes | - | format: date-time |
| `data.status.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions` | array<TrackingSessionSummary> | Yes | - | - |
| `data.status.sessions[]` | TrackingSessionSummary | Yes | - | - |
| `data.status.sessions[].provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.status.sessions[].trackingId` | string | Yes | - | - |
| `data.status.sessions[].loadId` | string | Yes | - | format: uuid |
| `data.status.sessions[].preferred` | boolean | Yes | - | - |
| `data.status.sessions[].status` | string | Yes | - | one of: active, pending_driver |
| `data.status.sessions[].startedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].lastUpdatedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].pendingExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].trackingMethod` | string \| null | Yes | - | - |
| `data.status.sessions[].driverActionRequired` | boolean | Yes | - | - |
| `data.status.sessions[].temperature` | object \| null | Yes | - | - |
| `data.status.preferredSession` | TrackingSessionSummary \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/tracking/driver-conflict/resolve

`ark.resolve_tracking_driver_conflict`

Switches a visible active dispatch to the app-linked duplicate-phone driver and starts internal ARK Tracking in one workflow.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `dispatchId` | string | Yes | Visible active dispatch whose driver should be switched. | format: uuid |
| `targetDriverId` | string | Yes | App-linked driver ID suggested by the tracking conflict response. | format: uuid |
| `emailCopiesTo` | string \| null | No | - | max length: 1000 |
| `notes` | string \| null | No | - | max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/tracking/driver-conflict/resolve' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "dispatchId": "<dispatchId>",
  "targetDriverId": "<targetDriverId>"
}'
```

#### Success response shape

Resolved driver conflict and started tracking

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ResolveTrackingDriverConflictData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.driverSwitched` | boolean | Yes | - | - |
| `data.driver` | TrackingDriverConflictDriver | Yes | - | - |
| `data.driver.id` | string | Yes | - | format: uuid |
| `data.driver.name` | string \| null | Yes | - | - |
| `data.driver.phone` | string \| null | Yes | - | - |
| `data.driver.email` | string \| null | Yes | - | format: email |
| `data.driver.hasAppAccount` | boolean | Yes | - | - |
| `data.tracking` | InternalTrackingStartResult | Yes | - | - |
| `data.tracking.sessionId` | string | Yes | - | format: uuid |
| `data.tracking.statusCode` | string | Yes | - | one of: active, pending_driver |
| `data.tracking.driverActionRequired` | boolean | Yes | - | - |
| `data.tracking.requiresConsent` | boolean | Yes | - | - |
| `data.tracking.driverNotified` | boolean | Yes | - | - |
| `data.tracking.smsSent` | boolean | Yes | - | - |
| `data.tracking.pendingDriverInfo` | object \| null | Yes | - | - |
| `data.tracking.warning` | string \| null | Yes | - | - |
| `data.tracking.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/tracking/email

`ark.send_tracking_link_email`

Sends a customer-facing tracking link email for the active or selected tracking provider on a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `recipientEmail` | string | Yes | - | format: email; max length: 500 |
| `recipientName` | string | No | - | min length: 1; max length: 200 |
| `message` | string \| null | No | - | max length: 5000 |
| `senderName` | string | No | - | min length: 1; max length: 200 |
| `provider` | TrackingProvider | No | - | one of: macropoint, truckertools, internal |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/tracking/email' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "recipientEmail": "<recipientEmail>"
}'
```

#### Success response shape

Sent tracking link email

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SendTrackingLinkEmailData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.recipient` | object | Yes | - | - |
| `data.recipient.email` | string | Yes | - | format: email |
| `data.recipient.name` | string \| null | Yes | - | - |
| `data.provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.providerDisplayName` | string | Yes | - | - |
| `data.trackingUrl` | string | Yes | - | format: uri |
| `data.emailSent` | unknown | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/loads/{loadId}/tracking/internal

`ark.get_internal_tracking_session`

Returns the latest internal ARK Tracking session detail for a visible load, including pending driver invite, stops, latest internal location, driver, and dispatch state.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/tracking/internal' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Internal tracking session detail

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | InternalTrackingSessionData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.hasOpenSession` | boolean | Yes | - | - |
| `data.hasActiveSession` | boolean | Yes | - | - |
| `data.pendingDriverInfo` | InternalTrackingPendingDriverInfo \| null | Yes | - | - |
| `data.session` | InternalTrackingSessionDetail \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/loads/{loadId}/tracking/link

`ark.get_tracking_link`

Returns a customer-facing tracking link for the active or selected tracking provider on a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required because resolving provider links can call external providers or create internal tracking tokens. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | TrackingProvider | No | - | one of: macropoint, truckertools, internal |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/tracking/link' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Tracking link

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | TrackingLinkData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.providerDisplayName` | string | Yes | - | - |
| `data.trackingUrl` | string | Yes | - | format: uri |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### POST /api/v1/loads/{loadId}/tracking/notify

`ark.send_load_location_notification`

Sends a manual location-update notification for a visible load using configured tracking notification recipients and throttle rules.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `one of: canEditLoad`, `one of: canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `city` | string | Yes | - | min length: 1; max length: 200 |
| `state` | string | Yes | - | min length: 1; max length: 20 |
| `country` | string | No | - | one of: USA, CAN, MEX; default: "USA" |
| `latitude` | number \| null | No | - | min: -90; max: 90 |
| `longitude` | number \| null | No | - | min: -180; max: 180 |
| `timezoneId` | string \| null | No | - | max length: 100 |
| `locationDateTime` | string | No | - | format: date-time |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/tracking/notify' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "city": "<city>",
  "state": "<state>"
}'
```

#### Success response shape

Load location notification result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SendLoadLocationNotificationData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | object | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.location` | LoadLocationNotificationLocation | Yes | - | - |
| `data.location.city` | string | Yes | - | - |
| `data.location.state` | string | Yes | - | - |
| `data.location.country` | string | Yes | - | one of: USA, CAN, MEX |
| `data.location.latitude` | number \| null | Yes | - | - |
| `data.location.longitude` | number \| null | Yes | - | - |
| `data.location.timezoneId` | string \| null | Yes | - | - |
| `data.location.locationDateTime` | string | Yes | - | format: date-time |
| `data.notificationSent` | boolean | Yes | - | - |
| `data.notificationResult` | LoadNotificationSendResult | Yes | - | - |
| `data.notificationResult.status` | string | Yes | - | one of: sent, skipped, failed |
| `data.notificationResult.reason` | string | No | - | one of: no_active_settings, load_completed, arrival_disabled, departure_disabled, interval_throttled, settings_lookup_failed, load_lookup_failed, email_delivery_failed, unexpected_error |
| `data.notificationResult.message` | string | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### POST /api/v1/loads/{loadId}/tracking/start

`ark.start_tracking`

Starts MacroPoint, TruckerTools, or internal ARK tracking for a visible dispatched load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | TrackingProvider | No | - | one of: macropoint, truckertools, internal |
| `trackStartDateTime` | string | No | Required for MacroPoint tracking. | max length: 100 |
| `trackDurationHours` | number | No | Required for MacroPoint tracking. | min: 1; max: 720 |
| `trackIntervalMinutes` | integer | No | Required for MacroPoint tracking. | min: 5; max: 1440 |
| `emailCopiesTo` | string \| null | No | - | max length: 1000 |
| `notes` | string \| null | No | - | max length: 5000 |
| `minTemp` | number \| null | No | - | - |
| `maxTemp` | number \| null | No | - | - |
| `tempUoM` | string | No | - | one of: fahrenheit, celsius |
| `dispatchId` | string | No | Required when provider is internal. | format: uuid |
| `geofenceRadiusMiles` | number | No | - | min: 0.1; max: 50 |
| `consentConfirmed` | boolean | No | - | - |
| `consentMethod` | string | No | - | one of: verbal, written, electronic |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/tracking/start' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Started tracking

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.provider` | string \| null | Yes | - | one of: macropoint, truckertools, internal, null |
| `data.trackingId` | string \| null | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.result` | TrackingProviderResult | Yes | - | - |
| `data.result.success` | boolean | Yes | - | - |
| `data.result.message` | string | Yes | - | - |
| `data.result.trackingId` | string \| null | Yes | - | - |
| `data.result.errorCode` | string \| null | Yes | - | - |
| `data.status` | TrackingStatusData | Yes | - | - |
| `data.status.loadId` | string | Yes | - | format: uuid |
| `data.status.load` | Load | Yes | - | - |
| `data.status.load.id` | string | Yes | - | format: uuid |
| `data.status.load.loadNumber` | string | Yes | - | - |
| `data.status.load.status` | string \| null | Yes | - | - |
| `data.status.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.status.load.customer` | object \| null | Yes | - | - |
| `data.status.load.customer.id` | string | Yes | - | format: uuid |
| `data.status.load.customer.name` | string \| null | Yes | - | - |
| `data.status.load.activeDispatch` | object \| null | Yes | - | - |
| `data.status.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.status.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.status.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.status.load.pickupNumber` | string \| null | Yes | - | - |
| `data.status.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.status.load.billOfLading` | string \| null | Yes | - | - |
| `data.status.load.product` | string \| null | Yes | - | - |
| `data.status.load.description` | string \| null | Yes | - | - |
| `data.status.load.createdAt` | string | Yes | - | format: date-time |
| `data.status.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions` | array<TrackingSessionSummary> | Yes | - | - |
| `data.status.sessions[]` | TrackingSessionSummary | Yes | - | - |
| `data.status.sessions[].provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.status.sessions[].trackingId` | string | Yes | - | - |
| `data.status.sessions[].loadId` | string | Yes | - | format: uuid |
| `data.status.sessions[].preferred` | boolean | Yes | - | - |
| `data.status.sessions[].status` | string | Yes | - | one of: active, pending_driver |
| `data.status.sessions[].startedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].lastUpdatedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].pendingExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].trackingMethod` | string \| null | Yes | - | - |
| `data.status.sessions[].driverActionRequired` | boolean | Yes | - | - |
| `data.status.sessions[].temperature` | object \| null | Yes | - | - |
| `data.status.preferredSession` | TrackingSessionSummary \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/tracking/stop

`ark.stop_tracking`

Stops the active tracking session for a visible load or a specific provider tracking ID.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `provider` | TrackingProvider | No | - | one of: macropoint, truckertools, internal |
| `trackingId` | string | No | - | max length: 200 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/tracking/stop' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Stopped tracking

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.provider` | string \| null | Yes | - | one of: macropoint, truckertools, internal, null |
| `data.trackingId` | string \| null | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.result` | TrackingProviderResult | Yes | - | - |
| `data.result.success` | boolean | Yes | - | - |
| `data.result.message` | string | Yes | - | - |
| `data.result.trackingId` | string \| null | Yes | - | - |
| `data.result.errorCode` | string \| null | Yes | - | - |
| `data.status` | TrackingStatusData | Yes | - | - |
| `data.status.loadId` | string | Yes | - | format: uuid |
| `data.status.load` | Load | Yes | - | - |
| `data.status.load.id` | string | Yes | - | format: uuid |
| `data.status.load.loadNumber` | string | Yes | - | - |
| `data.status.load.status` | string \| null | Yes | - | - |
| `data.status.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.status.load.customer` | object \| null | Yes | - | - |
| `data.status.load.customer.id` | string | Yes | - | format: uuid |
| `data.status.load.customer.name` | string \| null | Yes | - | - |
| `data.status.load.activeDispatch` | object \| null | Yes | - | - |
| `data.status.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.status.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.status.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.status.load.pickupNumber` | string \| null | Yes | - | - |
| `data.status.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.status.load.billOfLading` | string \| null | Yes | - | - |
| `data.status.load.product` | string \| null | Yes | - | - |
| `data.status.load.description` | string \| null | Yes | - | - |
| `data.status.load.createdAt` | string | Yes | - | format: date-time |
| `data.status.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions` | array<TrackingSessionSummary> | Yes | - | - |
| `data.status.sessions[]` | TrackingSessionSummary | Yes | - | - |
| `data.status.sessions[].provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.status.sessions[].trackingId` | string | Yes | - | - |
| `data.status.sessions[].loadId` | string | Yes | - | format: uuid |
| `data.status.sessions[].preferred` | boolean | Yes | - | - |
| `data.status.sessions[].status` | string | Yes | - | one of: active, pending_driver |
| `data.status.sessions[].startedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].lastUpdatedAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].pendingExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.status.sessions[].trackingMethod` | string \| null | Yes | - | - |
| `data.status.sessions[].driverActionRequired` | boolean | Yes | - | - |
| `data.status.sessions[].temperature` | object \| null | Yes | - | - |
| `data.status.preferredSession` | TrackingSessionSummary \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/tracking/stop-inactive-dispatch

`ark.stop_tracking_for_inactive_dispatch`

Stops active tracking sessions after a visible dispatch or deleted load has already become inactive.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `dispatchId` | string \| null | No | Inactive dispatch ID. Required unless reason is load_delete. | format: uuid |
| `reason` | InactiveDispatchTrackingReason | No | - | one of: cancel_dispatch, tonu_recover, tonu_deliver, repower, load_delete, dispatch_inactive; default: "dispatch_inactive" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/tracking/stop-inactive-dispatch' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Stopped inactive dispatch tracking

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | StopTrackingForInactiveDispatchData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.dispatchId` | string \| null | Yes | - | format: uuid |
| `data.reason` | InactiveDispatchTrackingReason | Yes | - | one of: cancel_dispatch, tonu_recover, tonu_deliver, repower, load_delete, dispatch_inactive |
| `data.success` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.stopped` | array<StoppedTrackingSessionResult> | Yes | - | - |
| `data.stopped[]` | StoppedTrackingSessionResult | Yes | - | - |
| `data.stopped[].provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.stopped[].trackingId` | string | Yes | - | - |
| `data.stopped[].success` | boolean | Yes | - | - |
| `data.stopped[].message` | string | Yes | - | - |
| `data.stopped[].error` | object \| null | No | - | - |
| `data.skipped` | array<SkippedTrackingSessionResult> | Yes | - | - |
| `data.skipped[]` | SkippedTrackingSessionResult | Yes | - | - |
| `data.skipped[].provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.skipped[].trackingId` | string | Yes | - | - |
| `data.skipped[].reason` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/loads/{loadId}/tracking/update-params

`ark.get_tracking_update_params`

Returns the active tracking session ARK would update, its current provider settings, and which update fields the provider supports.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/tracking/update-params' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Tracking update params

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | TrackingUpdateParamsData | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.load` | Load | Yes | - | - |
| `data.load.id` | string | Yes | - | format: uuid |
| `data.load.loadNumber` | string | Yes | - | - |
| `data.load.status` | string \| null | Yes | - | - |
| `data.load.teamId` | string \| null | Yes | - | format: uuid |
| `data.load.customer` | object \| null | Yes | - | - |
| `data.load.customer.id` | string | Yes | - | format: uuid |
| `data.load.customer.name` | string \| null | Yes | - | - |
| `data.load.activeDispatch` | object \| null | Yes | - | - |
| `data.load.activeDispatch.id` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.carrierId` | string | Yes | - | format: uuid |
| `data.load.activeDispatch.status` | string \| null | Yes | - | - |
| `data.load.pickupNumber` | string \| null | Yes | - | - |
| `data.load.purchaseOrderNumber` | string \| null | Yes | - | - |
| `data.load.billOfLading` | string \| null | Yes | - | - |
| `data.load.product` | string \| null | Yes | - | - |
| `data.load.description` | string \| null | Yes | - | - |
| `data.load.createdAt` | string | Yes | - | format: date-time |
| `data.load.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.trackingId` | string | Yes | - | - |
| `data.sessions` | array<TrackingSessionSummary> | Yes | - | - |
| `data.sessions[]` | TrackingSessionSummary | Yes | - | - |
| `data.sessions[].provider` | TrackingProvider | Yes | - | one of: macropoint, truckertools, internal |
| `data.sessions[].trackingId` | string | Yes | - | - |
| `data.sessions[].loadId` | string | Yes | - | format: uuid |
| `data.sessions[].preferred` | boolean | Yes | - | - |
| `data.sessions[].status` | string | Yes | - | one of: active, pending_driver |
| `data.sessions[].startedAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].lastUpdatedAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].pendingExpiresAt` | string \| null | Yes | - | format: date-time |
| `data.sessions[].trackingMethod` | string \| null | Yes | - | - |
| `data.sessions[].driverActionRequired` | boolean | Yes | - | - |
| `data.sessions[].temperature` | object \| null | Yes | - | - |
| `data.currentParams` | object | Yes | - | - |
| `data.supportedUpdateFields` | array<string> | Yes | - | - |
| `data.supportedUpdateFields[]` | string | Yes | - | - |
| `data.providerNotes` | array<string> | Yes | - | - |
| `data.providerNotes[]` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/loads/{loadId}/unlock

`ark.unlock_load`

Releases the connected actor’s load lock, or manager-overrides another user lock when allowed.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `trigger` | string | No | - | one of: manual, form_close, dispatch_complete, manager_override; default: "manual" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/unlock' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Load unlock result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.message` | string \| null | Yes | - | - |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.lockedBy` | string \| null | Yes | - | format: uuid |
| `data.lockedByName` | string \| null | Yes | - | - |
| `data.lockedAt` | string \| null | Yes | - | format: date-time |
| `data.lockExpiresAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/loads/{loadId}/vendor-expenses

`ark.upsert_load_vendor_expense`

Creates or updates one Vendor Expense on a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `loads:write`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canEditLoad`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `id` | string \| null | No | Existing Vendor Expense ID when updating. | format: uuid |
| `dispatchId` | string \| null | No | - | format: uuid |
| `category` | string | Yes | - | one of: Lumper, Insurance, Customs / Duties, Customs Broker, Transload / Crossdock, Toll, Permit, Storage, Scale Ticket, Washout, Other |
| `amount` | number | Yes | - | - |
| `vendorName` | string | Yes | - | min length: 1; max length: 200 |
| `paymentMethod` | string | Yes | - | one of: Credit Card, Check, ACH, Cash, EFS / Comcheck, Wire, E-Transfer, Other |
| `paidAt` | string \| null | No | - | - |
| `referenceNumber` | string \| null | No | - | max length: 200 |
| `description` | string \| null | No | - | max length: 5000 |
| `notes` | string \| null | No | - | max length: 5000 |
| `billCustomer` | boolean | No | - | default: false |
| `customerChargeName` | string \| null | No | - | max length: 200 |
| `customerChargeAmount` | number \| null | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/vendor-expenses' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "Lumper",
  "amount": 1,
  "vendorName": "<vendorName>",
  "paymentMethod": "Credit Card"
}'
```

#### Success response shape

Saved Vendor Expense

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |

#### Errors

_No operation-specific error responses._

### DELETE /api/v1/loads/{loadId}/vendor-expenses/{vendorExpenseId}

`ark.delete_load_vendor_expense`

Deletes one Vendor Expense from a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `loads:write`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canEditLoad`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `path.vendorExpenseId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/loads/<loadId>/vendor-expenses/<vendorExpenseId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deleted Vendor Expense

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |

#### Errors

_No operation-specific error responses._

### POST /api/v1/loads/{loadId}/vendor-expenses/batch

`ark.upsert_load_vendor_expenses`

Creates or updates multiple Vendor Expenses for one visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `loads:write`, `billing:write` |
| ARK permissions | `canViewLoads`, `canViewBilling`, `canEditLoad`, `canMakeAdjustments` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `expenses` | array<LoadVendorExpenseWriteRequest> | Yes | - | min items: 1; max items: 100 |
| `expenses[]` | LoadVendorExpenseWriteRequest | Yes | - | - |
| `expenses[].id` | string \| null | No | Existing Vendor Expense ID when updating. | format: uuid |
| `expenses[].dispatchId` | string \| null | No | - | format: uuid |
| `expenses[].category` | string | Yes | - | one of: Lumper, Insurance, Customs / Duties, Customs Broker, Transload / Crossdock, Toll, Permit, Storage, Scale Ticket, Washout, Other |
| `expenses[].amount` | number | Yes | - | - |
| `expenses[].vendorName` | string | Yes | - | min length: 1; max length: 200 |
| `expenses[].paymentMethod` | string | Yes | - | one of: Credit Card, Check, ACH, Cash, EFS / Comcheck, Wire, E-Transfer, Other |
| `expenses[].paidAt` | string \| null | No | - | - |
| `expenses[].referenceNumber` | string \| null | No | - | max length: 200 |
| `expenses[].description` | string \| null | No | - | max length: 5000 |
| `expenses[].notes` | string \| null | No | - | max length: 5000 |
| `expenses[].billCustomer` | boolean | No | - | default: false |
| `expenses[].customerChargeName` | string \| null | No | - | max length: 200 |
| `expenses[].customerChargeAmount` | number \| null | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/<loadId>/vendor-expenses/batch' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "expenses": [
    {
      "category": "Lumper",
      "amount": 1,
      "vendorName": "<vendorName>",
      "paymentMethod": "Credit Card"
    }
  ]
}'
```

#### Success response shape

Saved Vendor Expenses

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |

#### Errors

_No operation-specific error responses._

### GET /api/v1/loads/{loadId}/vendor-expenses/rebill-state

`ark.get_vendor_expense_rebill_state`

Returns linked customer rebill and locked-billing state for Vendor Expenses on a visible load.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read`, `billing:read` |
| ARK permissions | `canViewLoads`, `canViewBilling` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.loadId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/loads/<loadId>/vendor-expenses/rebill-state' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Vendor Expense rebill state

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |

#### Errors

_No operation-specific error responses._

### POST /api/v1/loads/bulk

`ark.bulk_create_loads`

Creates 1-25 available loads from one load template plus row-level customer reference, BOL, PO, and stop appointment overrides.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canCreateLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `template` | LoadCreateRequest | Yes | - | - |
| `template.customerId` | string | Yes | - | format: uuid |
| `template.teamId` | string | Yes | - | format: uuid |
| `template.brokerId` | string \| null | No | - | format: uuid |
| `template.customerServiceRepId` | string \| null | No | - | format: uuid |
| `template.temperature` | number \| null | No | - | - |
| `template.internalComments` | string | No | - | default: ""; max length: 5000 |
| `template.externalComments` | string | No | - | default: ""; max length: 5000 |
| `template.hotComments` | string | No | - | default: ""; max length: 5000 |
| `template.product` | string | No | - | default: ""; max length: 200 |
| `template.value` | number \| null | No | - | - |
| `template.description` | string | No | - | default: ""; max length: 5000 |
| `template.size` | string | No | - | default: ""; max length: 100 |
| `template.trailer` | string | Yes | - | min length: 1; max length: 100 |
| `template.weight` | number \| null | No | - | - |
| `template.weightUnit` | string | No | - | one of: lbs, kg; default: "lbs" |
| `template.length` | number \| null | No | - | - |
| `template.width` | number \| null | No | - | - |
| `template.height` | number \| null | No | - | - |
| `template.billOfLading` | string | No | - | default: ""; max length: 100 |
| `template.numberOfPieces` | integer \| null | No | - | min: 0 |
| `template.pickupNumber` | string | No | - | default: ""; max length: 100 |
| `template.purchaseOrderNumber` | string | No | - | default: ""; max length: 100 |
| `template.hazmat` | boolean | No | - | default: false |
| `template.docHigh` | boolean | No | - | default: false |
| `template.stackable` | boolean | No | - | default: false |
| `template.tsa` | boolean | No | - | default: false |
| `template.teamDriverRequired` | boolean | No | - | default: false |
| `template.miles` | number \| null | No | - | min: 0 |
| `template.customerCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `template.carrierCurrency` | string | No | - | one of: USD, CAD, MXN; default: "USD" |
| `template.customerPay` | array<LoadCreateCustomerPayInput> | No | - | default: []; max items: 100 |
| `template.customerPay[]` | LoadCreateCustomerPayInput | No | - | - |
| `template.customerPay[].name` | string | No | - | min length: 1; max length: 200 |
| `template.customerPay[].price` | number \| null | No | - | - |
| `template.customerPay[].rateType` | string \| null | No | - | max length: 50 |
| `template.customerPay[].unitPrice` | number \| null | No | - | - |
| `template.customerPay[].quantity` | number \| null | No | - | - |
| `template.customerPay[].uom` | string \| null | No | - | max length: 50 |
| `template.stops` | array<LoadCreateStopInput> | Yes | - | min items: 2; max items: 50 |
| `template.stops[]` | LoadCreateStopInput | Yes | - | - |
| `template.stops[].locationId` | string | Yes | - | format: uuid |
| `template.stops[].index` | integer | Yes | - | min: 0 |
| `template.stops[].type` | string | Yes | - | min length: 1; max length: 50 |
| `template.stops[].referenceNumber` | string \| null | No | - | max length: 100 |
| `template.stops[].pieces` | integer \| null | No | - | min: 0 |
| `template.stops[].arrivalTime` | string \| null | No | - | format: date-time |
| `template.stops[].arrivalTime2` | string \| null | No | - | format: date-time |
| `template.stops[].weight` | number \| null | No | - | min: 0 |
| `template.stops[].comment` | string \| null | No | - | max length: 5000 |
| `template.stops[].schedulingType` | string \| null | No | - | one of: fcfs, appointment, null |
| `template.stops[].milesToNextStop` | number \| null | No | - | min: 0 |
| `template.stops[].durationToNextStopSeconds` | integer \| null | No | - | min: 0 |
| `rows` | array<BulkCreateLoadRow> | Yes | - | min items: 1; max items: 25 |
| `rows[]` | BulkCreateLoadRow | Yes | - | - |
| `rows[].rowIndex` | integer | No | - | min: 0 |
| `rows[].customerRef` | string | Yes | Row-specific pickup/customer reference. | min length: 1; max length: 100 |
| `rows[].billOfLading` | string \| null | No | - | max length: 100 |
| `rows[].purchaseOrderNumber` | string \| null | No | - | max length: 100 |
| `rows[].stopOverrides` | array<BulkCreateLoadStopOverride> | No | - | default: []; max items: 50 |
| `rows[].stopOverrides[]` | BulkCreateLoadStopOverride | No | - | - |
| `rows[].stopOverrides[].stopIndex` | integer | No | Template stop index to override. | min: 0 |
| `rows[].stopOverrides[].referenceNumber` | string \| null | No | - | max length: 100 |
| `rows[].stopOverrides[].arrivalTime` | string \| null | No | - | format: date-time |
| `rows[].stopOverrides[].arrivalTime2` | string \| null | No | - | format: date-time |
| `rows[].stopOverrides[].schedulingType` | string | No | - | one of: appointment |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/loads/bulk' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "template": {
    "customerId": "<customerId>",
    "teamId": "<teamId>",
    "trailer": "<trailer>",
    "stops": [
      {
        "locationId": "<locationId>",
        "index": 0,
        "type": "<type>"
      },
      {
        "locationId": "<locationId>",
        "index": 0,
        "type": "<type>"
      }
    ]
  },
  "rows": [
    {
      "customerRef": "<customerRef>"
    }
  ]
}'
```

#### Success response shape

Created loads

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.createdCount` | integer | Yes | - | min: 0 |
| `data.items` | array<BulkCreatedLoad> | Yes | - | - |
| `data.items[]` | BulkCreatedLoad | Yes | - | - |
| `data.items[].rowIndex` | integer | Yes | - | min: 0 |
| `data.items[].loadId` | string | Yes | - | format: uuid |
| `data.items[].loadNumber` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/locations

`ark.search_locations`

Searches visible shipper, consignee, and customer locations by name, address, customer, country, and team visibility.

| Requirement | Value |
| --- | --- |
| Scopes | `locations:read` |
| ARK permissions | `canViewLocations` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | No | - | min length: 1; max length: 100 |
| `query.team_ids` | string | No | Comma-separated visible team IDs. | - |
| `query.country_codes` | string | No | Comma-separated ISO 3166-1 alpha-3 country codes. | - |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/locations' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Location search results

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.items` | array<Location> | Yes | - | - |
| `data.items[]` | Location | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].teamId` | string \| null | Yes | - | format: uuid |
| `data.items[].name` | string \| null | Yes | - | - |
| `data.items[].notes` | string \| null | Yes | - | - |
| `data.items[].internalNotes` | string \| null | Yes | - | - |
| `data.items[].address` | LocationAddress | Yes | - | - |
| `data.items[].address.id` | string \| null | Yes | - | format: uuid |
| `data.items[].address.company` | string \| null | Yes | - | - |
| `data.items[].address.name` | string \| null | Yes | - | - |
| `data.items[].address.address` | string \| null | Yes | - | - |
| `data.items[].address.address2` | string \| null | Yes | - | - |
| `data.items[].address.city` | string \| null | Yes | - | - |
| `data.items[].address.state` | string \| null | Yes | - | - |
| `data.items[].address.zip` | string \| null | Yes | - | - |
| `data.items[].address.phone` | string \| null | Yes | - | - |
| `data.items[].address.email` | string \| null | Yes | - | - |
| `data.items[].address.latitude` | number \| null | Yes | - | - |
| `data.items[].address.longitude` | number \| null | Yes | - | - |
| `data.items[].address.timezoneId` | string \| null | Yes | - | - |
| `data.items[].address.country` | string \| null | Yes | - | one of: USA, CAN, MEX, null |
| `data.items[].customer` | LocationCustomerRef | Yes | - | - |
| `data.items[].customer.id` | string | Yes | - | format: uuid |
| `data.items[].customer.name` | string \| null | Yes | - | - |
| `data.items[].customer.code` | string \| null | Yes | - | - |
| `data.items[].createdAt` | string | Yes | - | format: date-time |
| `data.pagination` | CursorPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/locations

`ark.create_location`

Creates a visible team-owned location and address.

| Requirement | Value |
| --- | --- |
| Scopes | `locations:write` |
| ARK permissions | `canCreateLocation` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `teamId` | string | Yes | - | format: uuid |
| `customerId` | string \| null | No | - | format: uuid |
| `name` | string | Yes | - | min length: 1; max length: 200 |
| `company` | string \| null | No | - | max length: 200 |
| `address` | string \| null | No | - | max length: 500 |
| `address2` | string \| null | No | - | max length: 500 |
| `city` | string \| null | No | - | max length: 200 |
| `state` | string \| null | No | - | max length: 20 |
| `zip` | string \| null | No | - | max length: 30 |
| `phone` | string \| null | No | - | max length: 50 |
| `email` | string \| null | No | - | max length: 500 |
| `notes` | string \| null | No | - | max length: 5000 |
| `internalNotes` | string \| null | No | - | max length: 5000 |
| `latitude` | number \| null | No | - | - |
| `longitude` | number \| null | No | - | - |
| `timezoneId` | string | Yes | - | min length: 1; max length: 100 |
| `country` | string | No | - | one of: USA, CAN, MEX; default: "USA" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/locations' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "teamId": "<teamId>",
  "name": "<name>",
  "timezoneId": "<timezoneId>"
}'
```

#### Success response shape

Created location

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Location | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.teamId` | string \| null | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.internalNotes` | string \| null | Yes | - | - |
| `data.address` | LocationAddress | Yes | - | - |
| `data.address.id` | string \| null | Yes | - | format: uuid |
| `data.address.company` | string \| null | Yes | - | - |
| `data.address.name` | string \| null | Yes | - | - |
| `data.address.address` | string \| null | Yes | - | - |
| `data.address.address2` | string \| null | Yes | - | - |
| `data.address.city` | string \| null | Yes | - | - |
| `data.address.state` | string \| null | Yes | - | - |
| `data.address.zip` | string \| null | Yes | - | - |
| `data.address.phone` | string \| null | Yes | - | - |
| `data.address.email` | string \| null | Yes | - | - |
| `data.address.latitude` | number \| null | Yes | - | - |
| `data.address.longitude` | number \| null | Yes | - | - |
| `data.address.timezoneId` | string \| null | Yes | - | - |
| `data.address.country` | string \| null | Yes | - | one of: USA, CAN, MEX, null |
| `data.customer` | LocationCustomerRef | Yes | - | - |
| `data.customer.id` | string | Yes | - | format: uuid |
| `data.customer.name` | string \| null | Yes | - | - |
| `data.customer.code` | string \| null | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### DELETE /api/v1/locations/{locationId}

`ark.delete_location`

Archives a visible location using the same soft-delete behavior as the ARK UI.

| Requirement | Value |
| --- | --- |
| Scopes | `locations:write` |
| ARK permissions | `canDeleteLocation` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.locationId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/locations/<locationId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Archived location

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.deleted` | boolean | Yes | - | one of: true |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### GET /api/v1/locations/{locationId}

`ark.get_location`

Returns one visible location by ID.

| Requirement | Value |
| --- | --- |
| Scopes | `locations:read` |
| ARK permissions | `canViewLocations` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.locationId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/locations/<locationId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Get location

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Location | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.teamId` | string \| null | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.internalNotes` | string \| null | Yes | - | - |
| `data.address` | LocationAddress | Yes | - | - |
| `data.address.id` | string \| null | Yes | - | format: uuid |
| `data.address.company` | string \| null | Yes | - | - |
| `data.address.name` | string \| null | Yes | - | - |
| `data.address.address` | string \| null | Yes | - | - |
| `data.address.address2` | string \| null | Yes | - | - |
| `data.address.city` | string \| null | Yes | - | - |
| `data.address.state` | string \| null | Yes | - | - |
| `data.address.zip` | string \| null | Yes | - | - |
| `data.address.phone` | string \| null | Yes | - | - |
| `data.address.email` | string \| null | Yes | - | - |
| `data.address.latitude` | number \| null | Yes | - | - |
| `data.address.longitude` | number \| null | Yes | - | - |
| `data.address.timezoneId` | string \| null | Yes | - | - |
| `data.address.country` | string \| null | Yes | - | one of: USA, CAN, MEX, null |
| `data.customer` | LocationCustomerRef | Yes | - | - |
| `data.customer.id` | string | Yes | - | format: uuid |
| `data.customer.name` | string \| null | Yes | - | - |
| `data.customer.code` | string \| null | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/locations/{locationId}

`ark.update_location`

Updates a visible location profile and address fields.

| Requirement | Value |
| --- | --- |
| Scopes | `locations:write` |
| ARK permissions | `canEditLocation` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.locationId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerId` | string \| null | No | - | format: uuid |
| `name` | string | No | - | min length: 1; max length: 200 |
| `company` | string \| null | No | - | max length: 200 |
| `address` | string \| null | No | - | max length: 500 |
| `address2` | string \| null | No | - | max length: 500 |
| `city` | string \| null | No | - | max length: 200 |
| `state` | string \| null | No | - | max length: 20 |
| `zip` | string \| null | No | - | max length: 30 |
| `phone` | string \| null | No | - | max length: 50 |
| `email` | string \| null | No | - | max length: 500 |
| `notes` | string \| null | No | - | max length: 5000 |
| `internalNotes` | string \| null | No | - | max length: 5000 |
| `latitude` | number \| null | No | - | - |
| `longitude` | number \| null | No | - | - |
| `timezoneId` | string \| null | No | - | max length: 100 |
| `country` | string | No | - | one of: USA, CAN, MEX; default: "USA" |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/locations/<locationId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated location

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Location | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.teamId` | string \| null | Yes | - | format: uuid |
| `data.name` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.internalNotes` | string \| null | Yes | - | - |
| `data.address` | LocationAddress | Yes | - | - |
| `data.address.id` | string \| null | Yes | - | format: uuid |
| `data.address.company` | string \| null | Yes | - | - |
| `data.address.name` | string \| null | Yes | - | - |
| `data.address.address` | string \| null | Yes | - | - |
| `data.address.address2` | string \| null | Yes | - | - |
| `data.address.city` | string \| null | Yes | - | - |
| `data.address.state` | string \| null | Yes | - | - |
| `data.address.zip` | string \| null | Yes | - | - |
| `data.address.phone` | string \| null | Yes | - | - |
| `data.address.email` | string \| null | Yes | - | - |
| `data.address.latitude` | number \| null | Yes | - | - |
| `data.address.longitude` | number \| null | Yes | - | - |
| `data.address.timezoneId` | string \| null | Yes | - | - |
| `data.address.country` | string \| null | Yes | - | one of: USA, CAN, MEX, null |
| `data.customer` | LocationCustomerRef | Yes | - | - |
| `data.customer.id` | string | Yes | - | format: uuid |
| `data.customer.name` | string \| null | Yes | - | - |
| `data.customer.code` | string \| null | Yes | - | - |
| `data.createdAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/locations/import

`ark.import_locations`

Validates and imports shipper, consignee, and customer locations from parsed CSV rows with team visibility, customer matching, and duplicate skipping.

| Requirement | Value |
| --- | --- |
| Scopes | `locations:write` |
| ARK permissions | `canCreateLocation` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `rows` | array<ImportLocationRow> | Yes | - | min items: 1; max items: 1000 |
| `rows[]` | ImportLocationRow | Yes | Parsed CSV row for shipper, consignee, or customer location import. | - |
| `rows[].teamName` | string | No | Visible team name. Required when the actor can access multiple teams unless teamId is provided. | max length: 200 |
| `rows[].teamId` | string | No | Visible team ID. Takes precedence over teamName. | - |
| `rows[].name` | string | Yes | - | min length: 1; max length: 200 |
| `rows[].notes` | string \| null | No | - | max length: 5000 |
| `rows[].internalNotes` | string \| null | No | - | max length: 5000 |
| `rows[].customerName` | string | No | Exact customer name to link within the selected visible team. | max length: 200 |
| `rows[].company` | string \| null | No | - | max length: 200 |
| `rows[].address` | string \| null | No | - | max length: 500 |
| `rows[].address2` | string \| null | No | - | max length: 500 |
| `rows[].city` | string \| null | No | - | max length: 200 |
| `rows[].state` | string \| null | No | - | max length: 20 |
| `rows[].country` | string | No | USA, CAN, or MEX. Common aliases like US, Canada, and MX are accepted. | one of: USA, CAN, MEX; default: "USA" |
| `rows[].zip` | string \| null | No | - | max length: 30 |
| `rows[].phone` | string \| null | No | - | max length: 50 |
| `rows[].email` | string \| null | No | Email address or semicolon/comma-separated emails. | max length: 500 |
| `rows[].latitude` | number | No | - | min: -90; max: 90 |
| `rows[].longitude` | number | No | - | min: -180; max: 180 |
| `rows[].timezoneId` | string \| null | No | - | max length: 100 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/locations/import' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "name": "<name>"
    }
  ]
}'
```

#### Success response shape

Location import result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ImportLocationsResult | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.totalRows` | integer | Yes | - | min: 0 |
| `data.successCount` | integer | Yes | - | min: 0 |
| `data.errorCount` | integer | Yes | - | min: 0 |
| `data.skippedCount` | integer | Yes | - | min: 0 |
| `data.errors` | array<ImportLocationError> | Yes | - | - |
| `data.errors[]` | ImportLocationError | Yes | - | - |
| `data.errors[].row` | integer | Yes | - | min: 1 |
| `data.errors[].field` | string | Yes | - | - |
| `data.errors[].value` | string | Yes | - | - |
| `data.errors[].message` | string | Yes | - | - |
| `data.createdLocations` | array<ImportedLocationSummary> | Yes | - | - |
| `data.createdLocations[]` | ImportedLocationSummary | Yes | - | - |
| `data.createdLocations[].row` | integer | Yes | - | min: 1 |
| `data.createdLocations[].locationId` | string | Yes | - | format: uuid |
| `data.createdLocations[].name` | string | Yes | - | - |
| `data.createdLocations[].teamId` | string | Yes | - | format: uuid |
| `data.createdLocations[].customerId` | string \| null | Yes | - | format: uuid |
| `data.createdLocations[].addressId` | string | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/me

`ark.get_current_context`

Returns the connected actor identity, effective scopes, visible teams, permissions, and operation availability.

| Requirement | Value |
| --- | --- |
| Scopes | `context:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.include_unavailable_operations` | boolean | No | - | default: false |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/me' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Current API context

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | CurrentContext | Yes | - | - |
| `data.actor` | object | Yes | - | - |
| `data.actor.type` | string | Yes | - | one of: web_user, api_token, oauth_mcp, internal_agent |
| `data.actor.source` | string | Yes | - | one of: web, api, mcp, agent |
| `data.actor.userId` | string | Yes | - | - |
| `data.actor.organizationId` | string | Yes | - | - |
| `data.actor.credentialId` | string \| null | Yes | - | - |
| `data.access` | object | Yes | - | - |
| `data.access.scopes` | array<OperationScope> | Yes | - | - |
| `data.access.scopes[]` | OperationScope | Yes | - | one of: context:read, agents:read, agents:write, admin:write, people:read, people:write, api_tokens:read, api_tokens:write, customers:read, carriers:read, factoring:read, factoring:write, locations:read, locations:write, docs:read, operations:read, audit:read, audit:export, reports:read, billing:read, billing:write, loads:read, loads:write, loads:delete, loads:dispatch, edi:read, edi:write, customers:write, carriers:write |
| `data.access.permissions` | object | Yes | - | - |
| `data.access.enabledPermissions` | array<string> | Yes | - | - |
| `data.access.enabledPermissions[]` | string | Yes | - | - |
| `data.access.visibleTeamIds` | array<string> | Yes | - | - |
| `data.access.visibleTeamIds[]` | string | Yes | - | - |
| `data.access.canAccessLegacyUnscopedLoads` | boolean | Yes | - | - |
| `data.access.isTenantAdmin` | boolean | Yes | - | - |
| `data.access.isSuperUser` | boolean | Yes | - | - |
| `data.operations` | array<OperationAvailability> | Yes | - | - |
| `data.operations[]` | OperationAvailability | Yes | - | - |
| `data.operations[].id` | string | Yes | - | - |
| `data.operations[].title` | string | Yes | - | - |
| `data.operations[].domain` | string | Yes | - | - |
| `data.operations[].description` | string | Yes | - | - |
| `data.operations[].available` | boolean | Yes | - | - |
| `data.operations[].requiredScopes` | array<OperationScope> | Yes | - | - |
| `data.operations[].requiredScopes[]` | OperationScope | Yes | - | one of: context:read, agents:read, agents:write, admin:write, people:read, people:write, api_tokens:read, api_tokens:write, customers:read, carriers:read, factoring:read, factoring:write, locations:read, locations:write, docs:read, operations:read, audit:read, audit:export, reports:read, billing:read, billing:write, loads:read, loads:write, loads:delete, loads:dispatch, edi:read, edi:write, customers:write, carriers:write |
| `data.operations[].requiredPermissions` | array<string> | Yes | - | - |
| `data.operations[].requiredPermissions[]` | string | Yes | - | - |
| `data.operations[].requiresTeamAccess` | boolean | Yes | - | - |
| `data.operations[].approvalPolicy` | string | Yes | - | - |
| `data.operations[].sideEffects` | array<string> | Yes | - | - |
| `data.operations[].sideEffects[]` | string | Yes | - | - |
| `data.operations[].missingScopes` | array<OperationScope> | No | - | - |
| `data.operations[].missingScopes[]` | OperationScope | No | - | one of: context:read, agents:read, agents:write, admin:write, people:read, people:write, api_tokens:read, api_tokens:write, customers:read, carriers:read, factoring:read, factoring:write, locations:read, locations:write, docs:read, operations:read, audit:read, audit:export, reports:read, billing:read, billing:write, loads:read, loads:write, loads:delete, loads:dispatch, edi:read, edi:write, customers:write, carriers:write |
| `data.operations[].missingPermissions` | array<string> | No | - | - |
| `data.operations[].missingPermissions[]` | string | No | - | - |
| `data.operations[].missingTeamAccess` | boolean | No | - | - |
| `data.operations[].requiresTenantAdmin` | boolean | Yes | - | - |
| `data.requestId` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/me/preferences

`ark.get_user_preferences`

Returns notification and sound preferences for the connected user, falling back to ARK defaults when no preferences row exists.

| Requirement | Value |
| --- | --- |
| Scopes | `notifications:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/me/preferences' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Connected-user preferences

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UserPreferences | Yes | - | - |
| `data.userId` | string | Yes | - | format: uuid |
| `data.notificationsEnabled` | boolean | Yes | - | - |
| `data.soundNewBid` | boolean | Yes | - | - |
| `data.soundQuoteAccepted` | boolean | Yes | - | - |
| `data.soundAwardSuccess` | boolean | Yes | - | - |
| `data.volume` | number | Yes | - | min: 0; max: 1 |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedBy` | string \| null | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### PATCH /api/v1/me/preferences

`ark.update_user_preferences`

Updates notification and sound preferences for the connected user.

| Requirement | Value |
| --- | --- |
| Scopes | `notifications:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `notificationsEnabled` | boolean | No | - | - |
| `soundNewBid` | boolean | No | - | - |
| `soundQuoteAccepted` | boolean | No | - | - |
| `soundAwardSuccess` | boolean | No | - | - |
| `volume` | number | No | - | min: 0; max: 1 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/me/preferences' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated user preferences

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UserPreferences | Yes | - | - |
| `data.userId` | string | Yes | - | format: uuid |
| `data.notificationsEnabled` | boolean | Yes | - | - |
| `data.soundNewBid` | boolean | Yes | - | - |
| `data.soundQuoteAccepted` | boolean | Yes | - | - |
| `data.soundAwardSuccess` | boolean | Yes | - | - |
| `data.volume` | number | Yes | - | min: 0; max: 1 |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedBy` | string \| null | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/notifications

`ark.list_notifications`

Lists notifications for the connected user. Use group_by_load=true to include spot quote/load grouped notifications.

| Requirement | Value |
| --- | --- |
| Scopes | `notifications:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.include_read` | boolean | No | - | default: false |
| `query.group_by_load` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/notifications' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Connected-user notifications

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | ListNotificationsPayload | Yes | - | - |
| `data.items` | array<Notification> | Yes | - | - |
| `data.items[]` | Notification | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].organizationId` | string | Yes | - | format: uuid |
| `data.items[].userId` | string | Yes | - | format: uuid |
| `data.items[].actorUserId` | string \| null | Yes | - | format: uuid |
| `data.items[].type` | string | Yes | - | - |
| `data.items[].title` | string | Yes | - | - |
| `data.items[].body` | string \| null | Yes | - | - |
| `data.items[].spotLoadId` | string \| null | Yes | - | format: uuid |
| `data.items[].spotLoadBidId` | string \| null | Yes | - | format: uuid |
| `data.items[].loadNumber` | integer \| string \| null | Yes | - | - |
| `data.items[].actionRoute` | string \| null | Yes | - | - |
| `data.items[].actionParams` | object \| null | Yes | - | - |
| `data.items[].readAt` | string \| null | Yes | - | format: date-time |
| `data.items[].createdAt` | string | Yes | - | format: date-time |
| `data.unreadCount` | integer | Yes | - | min: 0 |
| `data.groups` | array<NotificationGroup> | No | - | - |
| `data.groups[]` | NotificationGroup | No | - | - |
| `data.groups[].spotLoadId` | string | No | - | format: uuid |
| `data.groups[].loadNumber` | integer \| string \| null | No | - | - |
| `data.groups[].notifications` | array<Notification> | No | - | - |
| `data.groups[].notifications[]` | Notification | No | - | - |
| `data.groups[].notifications[].id` | string | No | - | format: uuid |
| `data.groups[].notifications[].organizationId` | string | No | - | format: uuid |
| `data.groups[].notifications[].userId` | string | No | - | format: uuid |
| `data.groups[].notifications[].actorUserId` | string \| null | No | - | format: uuid |
| `data.groups[].notifications[].type` | string | No | - | - |
| `data.groups[].notifications[].title` | string | No | - | - |
| `data.groups[].notifications[].body` | string \| null | No | - | - |
| `data.groups[].notifications[].spotLoadId` | string \| null | No | - | format: uuid |
| `data.groups[].notifications[].spotLoadBidId` | string \| null | No | - | format: uuid |
| `data.groups[].notifications[].loadNumber` | integer \| string \| null | No | - | - |
| `data.groups[].notifications[].actionRoute` | string \| null | No | - | - |
| `data.groups[].notifications[].actionParams` | object \| null | No | - | - |
| `data.groups[].notifications[].readAt` | string \| null | No | - | format: date-time |
| `data.groups[].notifications[].createdAt` | string | No | - | format: date-time |
| `data.groups[].unreadCount` | integer | No | - | min: 0 |
| `data.groups[].latestCreatedAt` | string | No | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/notifications/{notificationId}/read

`ark.mark_notification_read`

Marks one notification for the connected user as read.

| Requirement | Value |
| --- | --- |
| Scopes | `notifications:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.notificationId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/notifications/<notificationId>/read' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Marked notification

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | MarkNotificationReadPayload | Yes | - | - |
| `data.notification` | Notification | Yes | - | - |
| `data.notification.id` | string | Yes | - | format: uuid |
| `data.notification.organizationId` | string | Yes | - | format: uuid |
| `data.notification.userId` | string | Yes | - | format: uuid |
| `data.notification.actorUserId` | string \| null | Yes | - | format: uuid |
| `data.notification.type` | string | Yes | - | - |
| `data.notification.title` | string | Yes | - | - |
| `data.notification.body` | string \| null | Yes | - | - |
| `data.notification.spotLoadId` | string \| null | Yes | - | format: uuid |
| `data.notification.spotLoadBidId` | string \| null | Yes | - | format: uuid |
| `data.notification.loadNumber` | integer \| string \| null | Yes | - | - |
| `data.notification.actionRoute` | string \| null | Yes | - | - |
| `data.notification.actionParams` | object \| null | Yes | - | - |
| `data.notification.readAt` | string \| null | Yes | - | format: date-time |
| `data.notification.createdAt` | string | Yes | - | format: date-time |
| `data.wasAlreadyRead` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/notifications/read-all

`ark.mark_all_notifications_read`

Marks all unread notifications for the connected user as read.

| Requirement | Value |
| --- | --- |
| Scopes | `notifications:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/notifications/read-all' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Marked notifications

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | MarkAllNotificationsReadPayload | Yes | - | - |
| `data.count` | integer | Yes | - | min: 0 |
| `data.readAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/openapi.json

**Public schema**

Returns the machine-readable OpenAPI 3.1 contract for ARK API v1.

| Requirement | Value |
| --- | --- |
| Scopes | None |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | Public cache policy |

#### Parameters

_None._

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/openapi.json' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

OpenAPI document

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `value` | object | Yes | - | - |

#### Errors

_No operation-specific error responses._

### POST /api/v1/organization/logos/finalize-upload

`ark.finalize_organization_logo_upload`

Finalizes a prepared organization logo upload after the PNG has been uploaded, validates the canonical path, and returns a short-lived signed preview URL.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `logoType` | OrganizationLogoType | Yes | standard is the online app logo. paper is the logo used for PDFs and documents. | one of: standard, paper |
| `filePath` | string | Yes | - | min length: 1; max length: 500 |
| `pendingUploadId` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/organization/logos/finalize-upload' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "logoType": "standard",
  "filePath": "<filePath>",
  "pendingUploadId": "<pendingUploadId>"
}'
```

#### Success response shape

Finalized organization logo upload

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | FinalizeOrganizationLogoUploadPayload | Yes | - | - |
| `data.logoType` | OrganizationLogoType | Yes | standard is the online app logo. paper is the logo used for PDFs and documents. | one of: standard, paper |
| `data.filePath` | string | Yes | - | - |
| `data.displayName` | string | Yes | - | - |
| `data.pendingUploadId` | string | Yes | - | format: uuid |
| `data.signedUrl` | string | Yes | - | format: uri |
| `data.expiresInSeconds` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### POST /api/v1/organization/logos/prepare-upload

`ark.prepare_organization_logo_upload`

Creates a signed PNG upload URL for replacing the organization online logo or paper/PDF logo at the canonical storage path.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `logoType` | OrganizationLogoType | Yes | standard is the online app logo. paper is the logo used for PDFs and documents. | one of: standard, paper |
| `fileName` | string | No | - | min length: 1; max length: 200 |
| `mimeType` | string | No | - | default: "image/png" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/organization/logos/prepare-upload' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "logoType": "standard"
}'
```

#### Success response shape

Prepared organization logo upload

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | PrepareOrganizationLogoUploadPayload | Yes | - | - |
| `data.logoType` | OrganizationLogoType | Yes | standard is the online app logo. paper is the logo used for PDFs and documents. | one of: standard, paper |
| `data.filePath` | string | Yes | - | - |
| `data.displayName` | string | Yes | - | - |
| `data.fileName` | string | Yes | - | - |
| `data.mimeType` | string | Yes | - | - |
| `data.pendingUploadId` | string | Yes | - | format: uuid |
| `data.signedUrl` | string | Yes | - | format: uri |
| `data.token` | string | Yes | - | - |
| `data.upsert` | boolean | Yes | - | one of: true |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### GET /api/v1/organization/settings

`ark.get_organization_settings`

Gets tenant-admin organization settings and operational toggles. Sensitive payment credentials are always masked on the external API.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

_None._

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/organization/settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Organization settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | OrganizationSettingsPayload | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.name` | string | Yes | - | - |
| `data.mcNumber` | string \| null | Yes | - | - |
| `data.dotNumber` | string \| null | Yes | - | - |
| `data.address` | OrganizationSettingsAddress \| null | Yes | - | - |
| `data.billingAddress` | OrganizationSettingsAddress \| null | Yes | - | - |
| `data.invoiceContact` | string \| null | Yes | - | - |
| `data.invoiceInstructions` | string \| null | Yes | - | - |
| `data.rateconTerms` | string \| null | Yes | - | - |
| `data.subscriptionStatus` | string \| null | Yes | - | - |
| `data.maxUsers` | integer \| null | Yes | - | - |
| `data.payment` | OrganizationPaymentSettings | Yes | - | - |
| `data.payment.bankName` | string \| null | Yes | - | - |
| `data.payment.bankAccountName` | string \| null | Yes | - | - |
| `data.payment.bankAccountType` | string \| null | Yes | - | - |
| `data.payment.sensitiveFieldsIncluded` | boolean | Yes | - | - |
| `data.payment.federalTaxId` | null | Yes | - | - |
| `data.payment.bankAccountNumber` | null | Yes | - | - |
| `data.payment.bankRoutingNumber` | null | Yes | - | - |
| `data.payment.nachaDiscretionaryData` | null | Yes | - | - |
| `data.payment.nachaCompanyId` | null | Yes | - | - |
| `data.payment.masked` | object | Yes | - | - |
| `data.payment.masked.federalTaxIdPresent` | boolean | Yes | - | - |
| `data.payment.masked.bankAccountNumberLast4` | string \| null | Yes | - | - |
| `data.payment.masked.bankRoutingNumberLast4` | string \| null | Yes | - | - |
| `data.payment.masked.nachaDiscretionaryDataPresent` | boolean | Yes | - | - |
| `data.payment.masked.nachaCompanyIdPresent` | boolean | Yes | - | - |
| `data.settings` | object | Yes | - | - |
| `data.settings.requireDriverOnEsign` | boolean | Yes | - | - |
| `data.settings.forceImportedCarriersInactive` | boolean | Yes | - | - |
| `data.settings.loadLocksEnabled` | boolean | Yes | - | - |
| `data.settings.loadLockDurationMinutes` | integer \| null | Yes | - | - |
| `data.settings.recalculateCarrierDueDateOnReady` | boolean | Yes | - | - |
| `data.settings.multiCurrencyEnabled` | boolean | Yes | - | - |
| `data.settings.showCarrierOnboardingPanel` | boolean | Yes | - | - |
| `data.settings.randomizedLoadNumbersEnabled` | boolean \| null | Yes | - | - |
| `data.settings.randomizedLoadNumbersEnabledAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/organization/settings

`ark.update_organization_settings`

Updates tenant-admin organization profile fields, billing profile fields, and operational toggles with a partial patch. Payment fields require billing:write in addition to admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `name` | string | No | - | min length: 1; max length: 200 |
| `mcNumber` | string \| null | No | - | max length: 50 |
| `dotNumber` | string \| null | No | - | max length: 50 |
| `address` | UpdateOrganizationSettingsAddressPatch \| null | No | - | - |
| `billingAddress` | UpdateOrganizationSettingsAddressPatch \| null | No | - | - |
| `invoiceContact` | string \| null | No | - | max length: 500 |
| `invoiceInstructions` | string \| null | No | - | max length: 5000 |
| `rateconTerms` | string \| null | No | - | max length: 5000 |
| `payment` | UpdateOrganizationSettingsPaymentPatch | No | - | - |
| `payment.federalTaxId` | string \| null | No | - | max length: 100 |
| `payment.bankName` | string \| null | No | - | max length: 100 |
| `payment.bankAccountName` | string \| null | No | - | max length: 100 |
| `payment.bankAccountType` | string \| null | No | - | max length: 50 |
| `payment.bankAccountNumber` | string \| null | No | - | max length: 100 |
| `payment.bankRoutingNumber` | string \| null | No | - | - |
| `payment.nachaDiscretionaryData` | string \| null | No | - | max length: 20 |
| `payment.nachaCompanyId` | string \| null | No | - | max length: 10 |
| `settings` | UpdateOrganizationSettingsOperationalPatch | No | - | - |
| `settings.requireDriverOnEsign` | boolean | No | - | - |
| `settings.forceImportedCarriersInactive` | boolean | No | - | - |
| `settings.loadLocksEnabled` | boolean | No | - | - |
| `settings.loadLockDurationMinutes` | integer | No | - | min: 1; max: 60 |
| `settings.recalculateCarrierDueDateOnReady` | boolean | No | - | - |
| `settings.multiCurrencyEnabled` | boolean | No | - | - |
| `settings.showCarrierOnboardingPanel` | boolean | No | - | - |
| `settings.randomizedLoadNumbersEnabled` | boolean | No | Internal-admin only. | - |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/organization/settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated organization settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UpdateOrganizationSettingsPayload | Yes | - | - |
| `data.message` | string | Yes | - | - |
| `data.changed` | array<string> | Yes | - | - |
| `data.changed[]` | string | Yes | - | - |
| `data.loadLocksCleared` | boolean | Yes | - | - |
| `data.organization` | OrganizationSettingsPayload | Yes | - | - |
| `data.organization.id` | string | Yes | - | format: uuid |
| `data.organization.name` | string | Yes | - | - |
| `data.organization.mcNumber` | string \| null | Yes | - | - |
| `data.organization.dotNumber` | string \| null | Yes | - | - |
| `data.organization.address` | OrganizationSettingsAddress \| null | Yes | - | - |
| `data.organization.billingAddress` | OrganizationSettingsAddress \| null | Yes | - | - |
| `data.organization.invoiceContact` | string \| null | Yes | - | - |
| `data.organization.invoiceInstructions` | string \| null | Yes | - | - |
| `data.organization.rateconTerms` | string \| null | Yes | - | - |
| `data.organization.subscriptionStatus` | string \| null | Yes | - | - |
| `data.organization.maxUsers` | integer \| null | Yes | - | - |
| `data.organization.payment` | OrganizationPaymentSettings | Yes | - | - |
| `data.organization.payment.bankName` | string \| null | Yes | - | - |
| `data.organization.payment.bankAccountName` | string \| null | Yes | - | - |
| `data.organization.payment.bankAccountType` | string \| null | Yes | - | - |
| `data.organization.payment.sensitiveFieldsIncluded` | boolean | Yes | - | - |
| `data.organization.payment.federalTaxId` | null | Yes | - | - |
| `data.organization.payment.bankAccountNumber` | null | Yes | - | - |
| `data.organization.payment.bankRoutingNumber` | null | Yes | - | - |
| `data.organization.payment.nachaDiscretionaryData` | null | Yes | - | - |
| `data.organization.payment.nachaCompanyId` | null | Yes | - | - |
| `data.organization.payment.masked` | object | Yes | - | - |
| `data.organization.payment.masked.federalTaxIdPresent` | boolean | Yes | - | - |
| `data.organization.payment.masked.bankAccountNumberLast4` | string \| null | Yes | - | - |
| `data.organization.payment.masked.bankRoutingNumberLast4` | string \| null | Yes | - | - |
| `data.organization.payment.masked.nachaDiscretionaryDataPresent` | boolean | Yes | - | - |
| `data.organization.payment.masked.nachaCompanyIdPresent` | boolean | Yes | - | - |
| `data.organization.settings` | object | Yes | - | - |
| `data.organization.settings.requireDriverOnEsign` | boolean | Yes | - | - |
| `data.organization.settings.forceImportedCarriersInactive` | boolean | Yes | - | - |
| `data.organization.settings.loadLocksEnabled` | boolean | Yes | - | - |
| `data.organization.settings.loadLockDurationMinutes` | integer \| null | Yes | - | - |
| `data.organization.settings.recalculateCarrierDueDateOnReady` | boolean | Yes | - | - |
| `data.organization.settings.multiCurrencyEnabled` | boolean | Yes | - | - |
| `data.organization.settings.showCarrierOnboardingPanel` | boolean | Yes | - | - |
| `data.organization.settings.randomizedLoadNumbersEnabled` | boolean \| null | Yes | - | - |
| `data.organization.settings.randomizedLoadNumbersEnabledAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/people

`ark.search_people`

Searches organization carrier people records, including drivers and dispatchers linked to carriers.

| Requirement | Value |
| --- | --- |
| Scopes | `people:read` |
| ARK permissions | `canViewPeople` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.type` | string | No | - | one of: all, driver, dispatcher; default: "all" |
| `query.q` | string | No | - | min length: 1; max length: 100 |
| `query.carrier_id` | string | No | - | format: uuid |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.offset` | integer | No | - | default: 0; min: 0 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/people' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

People search results

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.items` | array<Person> | Yes | - | - |
| `data.items[]` | Person | Yes | - | - |
| `data.items[].type` | PersonType | Yes | - | one of: driver, dispatcher |
| `data.items[].recordId` | string | Yes | Driver or dispatcher table record ID. | format: uuid |
| `data.items[].personId` | string | Yes | Underlying ARK person ID used for get/update/delete. | format: uuid |
| `data.items[].firstName` | string \| null | Yes | - | - |
| `data.items[].lastName` | string \| null | Yes | - | - |
| `data.items[].email` | string \| null | Yes | - | - |
| `data.items[].phone` | string \| null | Yes | - | - |
| `data.items[].notes` | string \| null | Yes | - | - |
| `data.items[].carrier` | PersonCarrierRef \| null | Yes | - | - |
| `data.items[].hasAppAccount` | boolean \| null | Yes | Driver mobile-app account flag. Null for dispatchers. | - |
| `data.items[].userId` | string \| null | Yes | - | format: uuid |
| `data.items[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.items[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.pagination` | PeopleOffsetPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | min: 1; max: 100 |
| `data.pagination.offset` | integer | Yes | - | min: 0 |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextOffset` | integer \| null | Yes | - | min: 0 |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/people

`ark.create_person`

Creates a carrier driver or dispatcher contact.

| Requirement | Value |
| --- | --- |
| Scopes | `people:write` |
| ARK permissions | `canCreatePerson` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `type` | PersonType | Yes | - | one of: driver, dispatcher |
| `carrierId` | string | Yes | Carrier ID this driver or dispatcher contact belongs to. | format: uuid |
| `firstName` | string \| null | No | - | max length: 100 |
| `lastName` | string \| null | No | - | max length: 100 |
| `email` | string \| null | No | - | max length: 500 |
| `phone` | string \| null | No | - | max length: 50 |
| `notes` | string \| null | No | - | max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/people' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "driver",
  "carrierId": "<carrierId>"
}'
```

#### Success response shape

Created person

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Person | Yes | - | - |
| `data.type` | PersonType | Yes | - | one of: driver, dispatcher |
| `data.recordId` | string | Yes | Driver or dispatcher table record ID. | format: uuid |
| `data.personId` | string | Yes | Underlying ARK person ID used for get/update/delete. | format: uuid |
| `data.firstName` | string \| null | Yes | - | - |
| `data.lastName` | string \| null | Yes | - | - |
| `data.email` | string \| null | Yes | - | - |
| `data.phone` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.carrier` | PersonCarrierRef \| null | Yes | - | - |
| `data.hasAppAccount` | boolean \| null | Yes | Driver mobile-app account flag. Null for dispatchers. | - |
| `data.userId` | string \| null | Yes | - | format: uuid |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### DELETE /api/v1/people/{personId}

`ark.delete_person`

Soft-deletes a carrier driver or dispatcher contact by marking the person deleted.

| Requirement | Value |
| --- | --- |
| Scopes | `people:write` |
| ARK permissions | `canDeletePerson` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.personId` | string | Yes | Underlying ARK person ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/people/<personId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deleted person

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.id` | string | Yes | - | format: uuid |
| `data.deleted` | boolean | Yes | - | one of: true |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### GET /api/v1/people/{personId}

`ark.get_person`

Returns one carrier driver or dispatcher contact by underlying ARK person ID.

| Requirement | Value |
| --- | --- |
| Scopes | `people:read` |
| ARK permissions | `canViewPeople` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.personId` | string | Yes | Underlying ARK person ID. | format: uuid |
| `query.type` | PersonType | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/people/<personId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Person detail

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Person | Yes | - | - |
| `data.type` | PersonType | Yes | - | one of: driver, dispatcher |
| `data.recordId` | string | Yes | Driver or dispatcher table record ID. | format: uuid |
| `data.personId` | string | Yes | Underlying ARK person ID used for get/update/delete. | format: uuid |
| `data.firstName` | string \| null | Yes | - | - |
| `data.lastName` | string \| null | Yes | - | - |
| `data.email` | string \| null | Yes | - | - |
| `data.phone` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.carrier` | PersonCarrierRef \| null | Yes | - | - |
| `data.hasAppAccount` | boolean \| null | Yes | Driver mobile-app account flag. Null for dispatchers. | - |
| `data.userId` | string \| null | Yes | - | format: uuid |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/people/{personId}

`ark.update_person`

Updates a carrier driver or dispatcher contact profile and optional carrier link.

| Requirement | Value |
| --- | --- |
| Scopes | `people:write` |
| ARK permissions | `canEditPerson` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.personId` | string | Yes | Underlying ARK person ID. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `type` | PersonType | Yes | - | one of: driver, dispatcher |
| `carrierId` | string | No | Carrier ID this driver or dispatcher contact belongs to. | format: uuid |
| `firstName` | string \| null | No | - | max length: 100 |
| `lastName` | string \| null | No | - | max length: 100 |
| `email` | string \| null | No | - | max length: 500 |
| `phone` | string \| null | No | - | max length: 50 |
| `notes` | string \| null | No | - | max length: 5000 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/people/<personId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "driver"
}'
```

#### Success response shape

Updated person

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | Person | Yes | - | - |
| `data.type` | PersonType | Yes | - | one of: driver, dispatcher |
| `data.recordId` | string | Yes | Driver or dispatcher table record ID. | format: uuid |
| `data.personId` | string | Yes | Underlying ARK person ID used for get/update/delete. | format: uuid |
| `data.firstName` | string \| null | Yes | - | - |
| `data.lastName` | string \| null | Yes | - | - |
| `data.email` | string \| null | Yes | - | - |
| `data.phone` | string \| null | Yes | - | - |
| `data.notes` | string \| null | Yes | - | - |
| `data.carrier` | PersonCarrierRef \| null | Yes | - | - |
| `data.hasAppAccount` | boolean \| null | Yes | Driver mobile-app account flag. Null for dispatchers. | - |
| `data.userId` | string \| null | Yes | - | format: uuid |
| `data.createdAt` | string \| null | Yes | - | format: date-time |
| `data.modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/people/drivers/{driverId}/invite-app

`ark.invite_driver_app`

Creates or links a driver mobile-app account and records broker-confirmed SMS consent for the invite workflow. If the driver is already linked, the response succeeds with status already_linked.

| Requirement | Value |
| --- | --- |
| Scopes | `people:write` |
| ARK permissions | `one of: canCreatePerson`, `one of: canEditPerson` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.driverId` | string | Yes | Driver table record ID returned as recordId by people search for type=driver. | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `consentConfirmed` | boolean | Yes | Must be true after the broker has confirmed driver SMS consent. | - |
| `consentMethod` | string | No | How the broker confirmed driver SMS consent. | one of: verbal, written, electronic; default: "verbal" |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/people/drivers/<driverId>/invite-app' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "consentConfirmed": true
}'
```

#### Success response shape

Driver app invite result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | InviteDriverAppResult | Yes | - | - |
| `data.driverId` | string | Yes | - | format: uuid |
| `data.personId` | string | Yes | - | format: uuid |
| `data.authUserId` | string | Yes | - | format: uuid |
| `data.status` | string | Yes | - | one of: linked, already_linked |
| `data.hasUserAccount` | boolean | Yes | - | - |
| `data.recordsCreated` | array<string> | Yes | - | - |
| `data.recordsCreated[]` | string | Yes | - | - |
| `data.recordsUpdated` | array<string> | Yes | - | - |
| `data.recordsUpdated[]` | string | Yes | - | - |
| `data.consentMethod` | string | Yes | - | one of: verbal, written, electronic |
| `data.phoneE164` | string | Yes | - | - |
| `data.consentRecordCreated` | boolean | Yes | - | - |
| `data.downloadUrl` | string | Yes | - | format: uri |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/people/import

`ark.import_people`

Validates and imports driver or dispatcher contacts from parsed CSV rows, linking each row to an exact carrier match.

| Requirement | Value |
| --- | --- |
| Scopes | `people:write`, `carriers:read` |
| ARK permissions | `canCreatePerson`, `canViewCarriers` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `rows` | array<ImportPeopleRow> | Yes | - | min items: 1; max items: 1000 |
| `rows[]` | ImportPeopleRow | Yes | Parsed CSV row for driver or dispatcher import. Dispatcher rows require firstName, lastName, and email. | - |
| `rows[].firstName` | string | No | - | - |
| `rows[].lastName` | string | No | - | - |
| `rows[].email` | string \| null | No | Email address or semicolon/comma-separated emails. | - |
| `rows[].phone` | string | No | - | - |
| `rows[].notes` | string | No | - | - |
| `rows[].carrierName` | string | Yes | Carrier name used for exact matching when carrierMC is absent. | min length: 1 |
| `rows[].carrierMC` | string | No | Carrier MC number used for exact matching first. | - |
| `rows[].carrierDOT` | string | No | Accepted for CSV compatibility; carrier matching uses MC then name. | - |
| `rows[].type` | string | Yes | - | one of: Driver, Dispatcher |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/people/import' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "carrierName": "<carrierName>",
      "type": "Driver"
    }
  ]
}'
```

#### Success response shape

People import result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | ImportPeopleResult | Yes | - | - |
| `data.success` | boolean | Yes | - | - |
| `data.totalRows` | integer | Yes | - | min: 0 |
| `data.successCount` | integer | Yes | - | min: 0 |
| `data.errorCount` | integer | Yes | - | min: 0 |
| `data.skippedCount` | integer | Yes | - | min: 0 |
| `data.errors` | array<ImportPeopleError> | Yes | - | - |
| `data.errors[]` | ImportPeopleError | Yes | - | - |
| `data.errors[].row` | integer | Yes | - | min: 1 |
| `data.errors[].field` | string | Yes | - | - |
| `data.errors[].value` | string | Yes | - | - |
| `data.errors[].message` | string | Yes | - | - |
| `data.createdPeople` | array<ImportedPersonSummary> | Yes | - | - |
| `data.createdPeople[]` | ImportedPersonSummary | Yes | - | - |
| `data.createdPeople[].row` | integer | Yes | - | min: 1 |
| `data.createdPeople[].personId` | string | Yes | - | format: uuid |
| `data.createdPeople[].type` | string | Yes | - | one of: Driver, Dispatcher |
| `data.createdPeople[].carrierId` | string | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |
| 422 | Invalid request |

### GET /api/v1/reports/aging

`ark.get_aging_report`

Returns permissioned AR/AP aging summaries with bounded outstanding invoice/payment details.

| Requirement | Value |
| --- | --- |
| Scopes | `reports:read` |
| ARK permissions | `canViewReports`, `canViewAgingReport` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.direction` | string | No | - | one of: receivables, payables, both; default: "both" |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use every team available to the credential. | - |
| `query.detail_limit` | integer | No | - | min: 0; max: 1000 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/reports/aging' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Report result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.filters` | object | Yes | - | - |
| `data.receivables` | object \| null | Yes | - | - |
| `data.payables` | object \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/reports/aging/details

`ark.list_aging_details`

Lists unpaid invoice or settlement detail rows for one customer or carrier aging summary row with search, currency, pagination, and sort controls.

| Requirement | Value |
| --- | --- |
| Scopes | `reports:read` |
| ARK permissions | `canViewReports`, `canViewAgingReport` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.direction` | string | Yes | - | one of: receivables, payables |
| `query.entity_id` | string | Yes | Customer ID for receivables or carrier ID for payables. | format: uuid |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use every team available to the credential. | - |
| `query.search` | string | No | - | max length: 200 |
| `query.currency_code` | string | No | - | one of: USD, CAD, MXN |
| `query.page` | integer | No | - | default: 1; min: 1 |
| `query.page_size` | integer | No | - | default: 25; min: 1; max: 500 |
| `query.sort_column` | string | No | - | one of: docNumber, amountDue, ageDays, bucket, status, pickupNumber, loadNumber, settlementNumber; default: "ageDays" |
| `query.sort_direction` | string | No | - | one of: asc, desc; default: "desc" |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/reports/aging/details?direction=<direction>&entity_id=<entity_id>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Aging detail rows

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.filters` | object | Yes | - | - |
| `data.rows` | array<object> | Yes | - | - |
| `data.rows[]` | object | Yes | - | - |
| `data.rows[].id` | string | Yes | - | format: uuid |
| `data.rows[].entityId` | string | Yes | - | format: uuid |
| `data.rows[].entityName` | string | Yes | - | - |
| `data.rows[].currencyCode` | string | No | - | one of: USD, CAD, MXN |
| `data.rows[].docNumber` | string \| null | No | - | - |
| `data.rows[].amountDue` | number | Yes | - | - |
| `data.rows[].status` | string \| null | No | - | - |
| `data.rows[].onHold` | boolean | No | - | - |
| `data.rows[].dueDate` | string \| null | No | - | format: date-time |
| `data.rows[].invoicedDate` | string \| null | No | - | format: date-time |
| `data.rows[].ageDays` | integer | Yes | - | - |
| `data.rows[].bucket` | string | Yes | - | one of: 0-30, 31-60, 61-90, 90+ |
| `data.rows[].loadNumber` | string \| number \| null | No | - | - |
| `data.rows[].pickupNumber` | string \| null | No | - | - |
| `data.rows[].settlementNumber` | string \| number \| null | No | - | - |
| `data.pagination` | ReportPagination | Yes | - | - |
| `data.pagination.page` | integer | Yes | - | - |
| `data.pagination.pageSize` | integer | Yes | - | - |
| `data.pagination.total` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextPage` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/reports/aging/summary

`ark.list_aging_summary`

Lists AR customer or AP carrier aging summary rows with search, bucket, hold, currency, team, pagination, and sort controls.

| Requirement | Value |
| --- | --- |
| Scopes | `reports:read` |
| ARK permissions | `canViewReports`, `canViewAgingReport` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.direction` | string | Yes | - | one of: receivables, payables |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use every team available to the credential. | - |
| `query.search` | string | No | - | max length: 200 |
| `query.bucket` | string | No | - | one of: 0-30, 31-60, 61-90, 90+ |
| `query.on_hold_only` | boolean | No | - | - |
| `query.currency_code` | string | No | - | one of: USD, CAD, MXN |
| `query.page` | integer | No | - | default: 1; min: 1 |
| `query.page_size` | integer | No | - | default: 25; min: 1; max: 500 |
| `query.sort_column` | string | No | - | one of: entityName, currencyCode, totalOutstanding, oldestAgeDays, oldestBucket, itemCount, onHoldCount; default: "totalOutstanding" |
| `query.sort_direction` | string | No | - | one of: asc, desc; default: "desc" |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/reports/aging/summary?direction=<direction>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Aging summary rows

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.filters` | object | Yes | - | - |
| `data.rows` | array<object> | Yes | - | - |
| `data.rows[]` | object | Yes | - | - |
| `data.rows[].entityId` | string | Yes | - | format: uuid |
| `data.rows[].entityName` | string | Yes | - | - |
| `data.rows[].currencyCode` | string | No | - | one of: USD, CAD, MXN |
| `data.rows[].totalOutstanding` | number | Yes | - | - |
| `data.rows[].oldestAgeDays` | integer | Yes | - | - |
| `data.rows[].oldestBucket` | string | Yes | - | one of: 0-30, 31-60, 61-90, 90+ |
| `data.rows[].itemCount` | integer | Yes | - | - |
| `data.rows[].onHoldCount` | integer | Yes | - | - |
| `data.pagination` | ReportPagination | Yes | - | - |
| `data.pagination.page` | integer | Yes | - | - |
| `data.pagination.pageSize` | integer | Yes | - | - |
| `data.pagination.total` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextPage` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/reports/cash-flow

`ark.get_cash_flow_forecast`

Returns permissioned cash-flow forecast data with AR/AP aging buckets, daily inflow/outflow projection, and customer/carrier concentration analysis.

| Requirement | Value |
| --- | --- |
| Scopes | `reports:read` |
| ARK permissions | `canViewReports`, `canViewCashFlowForecast` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.scenario` | string | No | - | one of: P25, P50, P75; default: "P50" |
| `query.mode` | string | No | - | one of: historical, terms; default: "historical" |
| `query.horizon_days` | integer | No | - | one of: 30, 60, 90; default: 60 |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use every team available to the credential. | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/reports/cash-flow' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Cash flow forecast

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.filters` | object | Yes | - | - |
| `data.filters.scenario` | string | Yes | - | one of: P25, P50, P75 |
| `data.filters.mode` | string | Yes | - | one of: historical, terms |
| `data.filters.horizonDays` | integer | Yes | - | one of: 30, 60, 90 |
| `data.filters.teamIds` | array<string> | Yes | - | - |
| `data.filters.teamIds[]` | string | Yes | - | format: uuid |
| `data.forecast` | object | Yes | - | - |
| `data.forecast.scenario` | string | Yes | - | one of: P25, P50, P75 |
| `data.forecast.mode` | string | Yes | - | one of: historical, terms |
| `data.forecast.horizonDays` | integer | Yes | - | one of: 30, 60, 90 |
| `data.forecast.summary` | object | Yes | - | - |
| `data.forecast.agingBuckets` | object | Yes | - | - |
| `data.forecast.dailyForecast` | array<object> | Yes | - | - |
| `data.forecast.dailyForecast[]` | object | Yes | - | - |
| `data.forecast.customerAnalysis` | array<object> | Yes | - | - |
| `data.forecast.customerAnalysis[]` | object | Yes | - | - |
| `data.forecast.carrierAnalysis` | array<object> | Yes | - | - |
| `data.forecast.carrierAnalysis[]` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 502 | External provider or worker queue could not be reached |

### GET /api/v1/reports/commissions

`ark.get_commission_report`

Returns permissioned commission detail rows, user summaries, or both.

| Requirement | Value |
| --- | --- |
| Scopes | `reports:read` |
| ARK permissions | `canViewReports`, `canViewCommissionReport` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.from` | string | Yes | - | - |
| `query.to` | string | Yes | - | - |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use every team available to the credential. | - |
| `query.view` | string | No | - | one of: detail, summary, both; default: "both" |
| `query.page` | integer | No | - | min: 1 |
| `query.page_size` | integer | No | - | min: 1; max: 500 |
| `query.user_id` | string | No | - | - |
| `query.customer_id` | string | No | - | - |
| `query.is_paid` | boolean | No | - | - |
| `query.date_filter_type` | string | No | - | one of: delivery_date, created_date, booking_date, pickup_date; default: "delivery_date" |
| `query.paid_date_filter_type` | string | No | - | one of: delivery_date, paid_date; default: "delivery_date" |
| `query.customer_currency` | string | No | - | one of: USD, CAD, MXN |
| `query.detail_sort_column` | string | No | - | - |
| `query.summary_sort_column` | string | No | - | - |
| `query.sort_direction` | string | No | - | one of: asc, desc; default: "desc" |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/reports/commissions?from=<from>&to=<to>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Report result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.filters` | object | Yes | - | - |
| `data.detail` | object \| null | Yes | - | - |
| `data.summary` | object \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/reports/loads

`ark.get_load_report`

Returns permissioned paginated load report rows with lane, status, equipment, customer, carrier, revenue, expense, and margin fields.

| Requirement | Value |
| --- | --- |
| Scopes | `reports:read` |
| ARK permissions | `canViewReports`, `canViewLoadReport` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.from` | string | Yes | - | - |
| `query.to` | string | Yes | - | - |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use every team available to the credential. | - |
| `query.load_status` | string | No | Comma-separated load statuses. Defaults to Pending, Dispatched, and Delivered. | - |
| `query.customer_id` | string | No | - | - |
| `query.sales_rep_id` | string | No | - | - |
| `query.broker_id` | string | No | - | - |
| `query.carrier_id` | string | No | - | - |
| `query.origin_city` | string | No | - | - |
| `query.origin_state` | string | No | - | - |
| `query.destination_city` | string | No | - | - |
| `query.destination_state` | string | No | - | - |
| `query.load_size` | string | No | - | - |
| `query.trailer` | string | No | - | - |
| `query.date_filter_type` | string | No | - | one of: delivery_date, created_date, booking_date, pickup_date; default: "delivery_date" |
| `query.customer_currency` | string | No | - | one of: USD, CAD, MXN |
| `query.carrier_currency` | string | No | - | one of: USD, CAD, MXN |
| `query.page` | integer | No | - | min: 1 |
| `query.page_size` | integer | No | - | min: 1; max: 500 |
| `query.sort_column` | string | No | - | one of: loadNumber, status, customerCurrency, carrierCurrency, revenue, expenses, margin, customer, carrier, origin, destination; default: "loadNumber" |
| `query.sort_direction` | string | No | - | one of: asc, desc; default: "desc" |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/reports/loads?from=<from>&to=<to>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Report result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.filters` | ReportFilterSummary | Yes | - | - |
| `data.filters.from` | string | Yes | - | - |
| `data.filters.to` | string | Yes | - | - |
| `data.filters.teamIds` | array<string> | Yes | - | - |
| `data.filters.teamIds[]` | string | Yes | - | format: uuid |
| `data.filters.loadStatus` | array<string> | Yes | - | - |
| `data.filters.loadStatus[]` | string | Yes | - | - |
| `data.filters.dateFilterType` | string | Yes | - | one of: delivery_date, created_date, booking_date, pickup_date |
| `data.loads` | array<object> | Yes | - | - |
| `data.loads[]` | object | Yes | - | - |
| `data.pagination` | ReportPagination | Yes | - | - |
| `data.pagination.page` | integer | Yes | - | - |
| `data.pagination.pageSize` | integer | Yes | - | - |
| `data.pagination.total` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextPage` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/reports/revenue

`ark.get_revenue_report`

Returns permissioned revenue, expense, margin, load-count, trend, category, and entity report data.

| Requirement | Value |
| --- | --- |
| Scopes | `reports:read` |
| ARK permissions | `canViewReports`, `canViewRevenueReport` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.from` | string | Yes | - | - |
| `query.to` | string | Yes | - | - |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use every team available to the credential. | - |
| `query.load_status` | string | No | Comma-separated load statuses. Defaults to Pending, Dispatched, and Delivered. | - |
| `query.customer_id` | string | No | - | - |
| `query.sales_rep_id` | string | No | - | - |
| `query.broker_id` | string | No | - | - |
| `query.carrier_id` | string | No | - | - |
| `query.origin_city` | string | No | - | - |
| `query.origin_state` | string | No | - | - |
| `query.destination_city` | string | No | - | - |
| `query.destination_state` | string | No | - | - |
| `query.load_size` | string | No | - | - |
| `query.trailer` | string | No | - | - |
| `query.date_filter_type` | string | No | - | one of: delivery_date, created_date, booking_date, pickup_date; default: "delivery_date" |
| `query.customer_currency` | string | No | - | one of: USD, CAD, MXN |
| `query.carrier_currency` | string | No | - | one of: USD, CAD, MXN |
| `query.interval` | string | No | - | one of: hour, day, week, month; default: "day" |
| `query.timezone` | string | No | IANA timezone used for trend buckets. | - |
| `query.include_details` | boolean | No | - | - |
| `query.include_trends` | boolean | No | - | - |
| `query.include_entities` | boolean | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/reports/revenue?from=<from>&to=<to>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Report result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.filters` | ReportFilterSummary | Yes | - | - |
| `data.filters.from` | string | Yes | - | - |
| `data.filters.to` | string | Yes | - | - |
| `data.filters.teamIds` | array<string> | Yes | - | - |
| `data.filters.teamIds[]` | string | Yes | - | format: uuid |
| `data.filters.loadStatus` | array<string> | Yes | - | - |
| `data.filters.loadStatus[]` | string | Yes | - | - |
| `data.filters.dateFilterType` | string | Yes | - | one of: delivery_date, created_date, booking_date, pickup_date |
| `data.totals` | array<object> | Yes | - | - |
| `data.totals[]` | object | Yes | - | - |
| `data.revenueMarginTrend` | array<object> | Yes | - | - |
| `data.revenueMarginTrend[]` | object | Yes | - | - |
| `data.loadCountTrend` | array<object> | Yes | - | - |
| `data.loadCountTrend[]` | object | Yes | - | - |
| `data.revenueDetails` | array<object> | Yes | - | - |
| `data.revenueDetails[]` | object | Yes | - | - |
| `data.expenseDetails` | array<object> | Yes | - | - |
| `data.expenseDetails[]` | object | Yes | - | - |
| `data.entities` | array<object> | Yes | - | - |
| `data.entities[]` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/search

`ark.search`

Searches across available loads, customers, carriers, locations, users, and docs with one query. Each domain is filtered by the connected actor’s scopes, permissions, and team visibility.

| Requirement | Value |
| --- | --- |
| Scopes | `context:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | Yes | - | min length: 2; max length: 100 |
| `query.domains` | string | No | Comma-separated domain filters: loads, customers, carriers, locations, users, docs. | - |
| `query.limit_per_domain` | integer | No | - | default: 5; min: 1; max: 10 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/search?q=<q>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Cross-entity search results

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.query` | string | Yes | - | - |
| `data.results` | array<SearchDomainResult> | Yes | - | - |
| `data.results[]` | SearchDomainResult | Yes | - | - |
| `data.results[].domain` | string | Yes | - | one of: loads, customers, carriers, locations, users, docs |
| `data.results[].operationId` | string | Yes | - | - |
| `data.results[].available` | boolean | Yes | - | - |
| `data.results[].items` | array<unknown> | Yes | - | - |
| `data.results[].items[]` | unknown | Yes | - | - |
| `data.results[].error` | object \| null | Yes | - | - |
| `data.results[].error.code` | string | Yes | - | - |
| `data.results[].error.message` | string | Yes | - | - |
| `data.results[].error.details` | unknown | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/spot-quotes

`ark.list_spot_quotes`

Lists visible spot quotes with bid summaries, stops, customer context, and watcher state for the connected actor.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use all teams visible to the connected actor. | - |
| `query.statuses` | string | No | Comma-separated spot quote statuses. | - |
| `query.include_retained` | boolean | No | - | default: false |
| `query.retained_only` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 200 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/spot-quotes' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Spot quotes

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuotes` | array<SpotQuote> | Yes | - | - |
| `data.spotQuotes[]` | SpotQuote | Yes | - | - |
| `data.spotQuotes[].id` | string | Yes | - | format: uuid |
| `data.spotQuotes[].org_id` | string | Yes | - | format: uuid |
| `data.spotQuotes[].team_id` | string \| null | No | - | format: uuid |
| `data.spotQuotes[].customer_id` | string | Yes | - | format: uuid |
| `data.spotQuotes[].customer_name` | string \| null | No | - | - |
| `data.spotQuotes[].load_number` | string \| integer | Yes | - | - |
| `data.spotQuotes[].reference_number` | string \| null | No | - | - |
| `data.spotQuotes[].status` | string | Yes | - | one of: new, quoting, quoted_pending, won, lost, cancelled, expired |
| `data.spotQuotes[].origin_city` | string \| null | No | - | - |
| `data.spotQuotes[].origin_state` | string \| null | No | - | - |
| `data.spotQuotes[].destination_city` | string \| null | No | - | - |
| `data.spotQuotes[].destination_state` | string \| null | No | - | - |
| `data.spotQuotes[].vehicle_type` | string \| null | No | - | - |
| `data.spotQuotes[].bid_count` | integer | No | - | - |
| `data.spotQuotes[].linked_load_id` | string \| null | No | - | format: uuid |
| `data.spotQuotes[].stops` | array<object> | Yes | - | - |
| `data.spotQuotes[].stops[]` | object | Yes | - | - |
| `data.bids` | array<SpotQuoteBid> | Yes | - | - |
| `data.bids[]` | SpotQuoteBid | Yes | - | - |
| `data.bids[].id` | string | Yes | - | format: uuid |
| `data.bids[].spot_load_id` | string | Yes | - | format: uuid |
| `data.bids[].carrier_id` | string \| null | No | - | format: uuid |
| `data.bids[].carrier_name` | string \| null | No | - | - |
| `data.bids[].price` | number \| null | No | - | - |
| `data.bids[].currency` | string \| null | No | - | - |
| `data.bids[].status` | string | Yes | - | - |
| `data.watchedSpotQuoteIds` | array<string> | Yes | - | - |
| `data.watchedSpotQuoteIds[]` | string | Yes | - | format: uuid |
| `data.count` | integer | Yes | - | - |
| `data.truncated` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/spot-quotes

`ark.create_spot_quote`

Creates a spot quote with pickup, delivery, freight, customer, and team context using the same transactional workflow as the website.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canCreateLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerId` | string | Yes | - | format: uuid |
| `teamId` | string | No | Visible team ID. Omit only when the connection has one visible team. | format: uuid |
| `customerEmail` | string \| null | No | - | format: email; max length: 254 |
| `currency` | string | No | - | one of: USD, CAD, MXN |
| `referenceNumber` | string \| null | No | - | max length: 100 |
| `loadClassification` | string \| null | No | - | max length: 100 |
| `sylectusLoadType` | integer \| null | No | - | - |
| `vehicleType` | string \| null | No | - | max length: 100 |
| `pieces` | integer \| null | No | - | min: 1 |
| `dimensionsLength` | number \| null | No | - | - |
| `dimensionsWidth` | number \| null | No | - | - |
| `dimensionsHeight` | number \| null | No | - | - |
| `dimensionsUnit` | string | No | - | one of: inches, feet |
| `weight` | number \| null | No | - | - |
| `weightUnit` | string | No | - | one of: lbs, kg |
| `stackable` | boolean | No | - | - |
| `hazmat` | boolean | No | - | - |
| `dockHigh` | boolean | No | - | - |
| `teamDriverRequired` | boolean | No | - | - |
| `tsa` | boolean | No | - | - |
| `notesInternal` | string \| null | No | - | max length: 5000 |
| `notesExternal` | string \| null | No | - | max length: 5000 |
| `distanceMiles` | number \| null | No | - | - |
| `stops` | array<SpotQuoteStopInput> | Yes | - | min items: 2; max items: 50 |
| `stops[]` | SpotQuoteStopInput | Yes | - | - |
| `stops[].id` | string | No | Existing stop ID when updating an existing stop. | format: uuid |
| `stops[].sequenceIndex` | integer | Yes | - | min: 0 |
| `stops[].type` | string | Yes | - | one of: pickup, drop_off |
| `stops[].city` | string | Yes | - | min length: 1; max length: 200 |
| `stops[].state` | string | Yes | - | min length: 1; max length: 50 |
| `stops[].zip` | string \| null | No | - | max length: 30 |
| `stops[].arrivalTime` | string \| null | No | Optional scheduled arrival timestamp. | - |
| `stops[].arrivalTime2` | string \| null | No | Optional scheduled arrival window end timestamp. | - |
| `stops[].timezone` | string \| null | No | - | max length: 100 |
| `stops[].deliveryType` | string \| null | No | - | one of: asap, direct, null |
| `stops[].milesToNextStop` | number \| null | No | - | min: 0 |
| `stops[].durationToNextStopSeconds` | integer \| null | No | - | min: 0 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "<customerId>",
  "stops": [
    {
      "sequenceIndex": 0,
      "type": "pickup",
      "city": "<city>",
      "state": "<state>"
    },
    {
      "sequenceIndex": 0,
      "type": "pickup",
      "city": "<city>",
      "state": "<state>"
    }
  ]
}'
```

#### Success response shape

Created spot quote

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.spotQuote` | object | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/spot-quotes/{spotQuoteId}

`ark.get_spot_quote`

Returns a visible spot quote with stops, bids, customer quotes, invitations, recent events, and watcher state.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Spot quote detail

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuote` | SpotQuote | Yes | - | - |
| `data.spotQuote.id` | string | Yes | - | format: uuid |
| `data.spotQuote.org_id` | string | Yes | - | format: uuid |
| `data.spotQuote.team_id` | string \| null | No | - | format: uuid |
| `data.spotQuote.customer_id` | string | Yes | - | format: uuid |
| `data.spotQuote.customer_name` | string \| null | No | - | - |
| `data.spotQuote.load_number` | string \| integer | Yes | - | - |
| `data.spotQuote.reference_number` | string \| null | No | - | - |
| `data.spotQuote.status` | string | Yes | - | one of: new, quoting, quoted_pending, won, lost, cancelled, expired |
| `data.spotQuote.origin_city` | string \| null | No | - | - |
| `data.spotQuote.origin_state` | string \| null | No | - | - |
| `data.spotQuote.destination_city` | string \| null | No | - | - |
| `data.spotQuote.destination_state` | string \| null | No | - | - |
| `data.spotQuote.vehicle_type` | string \| null | No | - | - |
| `data.spotQuote.bid_count` | integer | No | - | - |
| `data.spotQuote.linked_load_id` | string \| null | No | - | format: uuid |
| `data.spotQuote.stops` | array<object> | Yes | - | - |
| `data.spotQuote.stops[]` | object | Yes | - | - |
| `data.stops` | array<object> | Yes | - | - |
| `data.stops[]` | object | Yes | - | - |
| `data.bids` | array<SpotQuoteBid> | Yes | - | - |
| `data.bids[]` | SpotQuoteBid | Yes | - | - |
| `data.bids[].id` | string | Yes | - | format: uuid |
| `data.bids[].spot_load_id` | string | Yes | - | format: uuid |
| `data.bids[].carrier_id` | string \| null | No | - | format: uuid |
| `data.bids[].carrier_name` | string \| null | No | - | - |
| `data.bids[].price` | number \| null | No | - | - |
| `data.bids[].currency` | string \| null | No | - | - |
| `data.bids[].status` | string | Yes | - | - |
| `data.customerQuotes` | array<SpotQuoteCustomerQuote> | Yes | - | - |
| `data.customerQuotes[]` | SpotQuoteCustomerQuote | Yes | - | - |
| `data.customerQuotes[].id` | string | Yes | - | format: uuid |
| `data.customerQuotes[].spot_load_id` | string | Yes | - | format: uuid |
| `data.customerQuotes[].customer_id` | string | Yes | - | format: uuid |
| `data.customerQuotes[].price` | number | Yes | - | - |
| `data.customerQuotes[].currency` | string \| null | No | - | - |
| `data.customerQuotes[].status` | string | Yes | - | - |
| `data.customerQuotes[].from_bid_id` | string \| null | No | - | format: uuid |
| `data.customerQuotes[].email_sent_at` | string \| null | No | - | format: date-time |
| `data.invitations` | array<SpotQuoteInvitation> | Yes | - | - |
| `data.invitations[]` | SpotQuoteInvitation | Yes | - | - |
| `data.invitations[].id` | string | Yes | - | format: uuid |
| `data.invitations[].spot_load_id` | string | Yes | - | format: uuid |
| `data.invitations[].carrier_id` | string \| null | No | - | format: uuid |
| `data.invitations[].carrier_name` | string \| null | No | - | - |
| `data.invitations[].channel` | string \| null | No | - | - |
| `data.invitations[].status` | string \| null | No | - | - |
| `data.invitations[].created_at` | string \| null | No | - | format: date-time |
| `data.events` | array<SpotQuoteEvent> | Yes | - | - |
| `data.events[]` | SpotQuoteEvent | Yes | - | - |
| `data.events[].id` | string | Yes | - | format: uuid |
| `data.events[].spot_load_id` | string | Yes | - | format: uuid |
| `data.events[].actor_user_id` | string \| null | No | - | format: uuid |
| `data.events[].type` | string | Yes | - | - |
| `data.events[].payload` | object \| null | No | - | - |
| `data.events[].created_at` | string \| null | No | - | format: date-time |
| `data.isWatched` | boolean | Yes | - | - |
| `data.pendingCustomerQuote` | SpotQuoteCustomerQuote \| null | Yes | - | - |
| `data.heldBid` | SpotQuoteBid \| null | Yes | - | - |
| `data.awardedBid` | SpotQuoteBid \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/spot-quotes/{spotQuoteId}

`ark.update_spot_quote`

Updates customer, freight, reference, schedule, and stop details on a visible active spot quote.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerId` | string | No | - | format: uuid |
| `customerEmail` | string \| null | No | - | format: email; max length: 254 |
| `currency` | string | No | - | one of: USD, CAD, MXN |
| `referenceNumber` | string \| null | No | - | max length: 100 |
| `loadClassification` | string \| null | No | - | max length: 100 |
| `sylectusLoadType` | integer \| null | No | - | - |
| `vehicleType` | string \| null | No | - | max length: 100 |
| `pieces` | integer \| null | No | - | min: 1 |
| `dimensionsLength` | number \| null | No | - | - |
| `dimensionsWidth` | number \| null | No | - | - |
| `dimensionsHeight` | number \| null | No | - | - |
| `dimensionsUnit` | string | No | - | one of: inches, feet |
| `weight` | number \| null | No | - | - |
| `weightUnit` | string | No | - | one of: lbs, kg |
| `stackable` | boolean | No | - | - |
| `hazmat` | boolean | No | - | - |
| `dockHigh` | boolean | No | - | - |
| `teamDriverRequired` | boolean | No | - | - |
| `tsa` | boolean | No | - | - |
| `notesInternal` | string \| null | No | - | max length: 5000 |
| `notesExternal` | string \| null | No | - | max length: 5000 |
| `distanceMiles` | number \| null | No | - | - |
| `stops` | array<SpotQuoteStopInput> | No | - | min items: 2; max items: 50 |
| `stops[]` | SpotQuoteStopInput | No | - | - |
| `stops[].id` | string | No | Existing stop ID when updating an existing stop. | format: uuid |
| `stops[].sequenceIndex` | integer | No | - | min: 0 |
| `stops[].type` | string | No | - | one of: pickup, drop_off |
| `stops[].city` | string | No | - | min length: 1; max length: 200 |
| `stops[].state` | string | No | - | min length: 1; max length: 50 |
| `stops[].zip` | string \| null | No | - | max length: 30 |
| `stops[].arrivalTime` | string \| null | No | Optional scheduled arrival timestamp. | - |
| `stops[].arrivalTime2` | string \| null | No | Optional scheduled arrival window end timestamp. | - |
| `stops[].timezone` | string \| null | No | - | max length: 100 |
| `stops[].deliveryType` | string \| null | No | - | one of: asap, direct, null |
| `stops[].milesToNextStop` | number \| null | No | - | min: 0 |
| `stops[].durationToNextStopSeconds` | integer \| null | No | - | min: 0 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated spot quote

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.spotQuote` | object | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/bids

`ark.create_spot_quote_bid`

Creates a carrier bid for a visible active spot quote, records bid history, and notifies quote watchers.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierId` | string \| null | No | Carrier ID when the carrier already exists in ARK. | format: uuid |
| `carrierName` | string | No | - | min length: 1; max length: 200 |
| `dotNumber` | string | Yes | - | min length: 1; max length: 30 |
| `mcNumber` | string \| null | No | - | max length: 30 |
| `price` | number | Yes | - | - |
| `pricePerMile` | number \| null | No | - | - |
| `distanceDeadheadMiles` | number \| null | No | - | min: 0 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/bids' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "dotNumber": "<dotNumber>",
  "price": 1
}'
```

#### Success response shape

Spot quote bid action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.bidId` | string | Yes | - | format: uuid |
| `data.bid` | SpotQuoteBid | Yes | - | - |
| `data.bid.id` | string | Yes | - | format: uuid |
| `data.bid.spot_load_id` | string | Yes | - | format: uuid |
| `data.bid.carrier_id` | string \| null | No | - | format: uuid |
| `data.bid.carrier_name` | string \| null | No | - | - |
| `data.bid.price` | number \| null | No | - | - |
| `data.bid.currency` | string \| null | No | - | - |
| `data.bid.status` | string | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/build-load

`ark.build_load_from_spot_quote`

Creates a broker load from a visible won spot quote, links the quote to the created load, records the conversion event, and processes queued load-board removals.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canCreateLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/build-load' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Created load link result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.loadNumber` | integer \| null | Yes | - | - |
| `data.loadBoardRemovalProcessed` | boolean | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/cancel

`ark.cancel_spot_quote`

Cancels a visible spot quote using the same status and history updates as the website.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/cancel' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Cancelled spot quote

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.spotQuote` | object | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/hold

`ark.hold_spot_quote`

Places a visible active spot quote on hold and notifies watchers.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `reason` | string | Yes | - | min length: 1; max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/hold' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "<reason>"
}'
```

#### Success response shape

Spot quote hold action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.spotQuote` | object | Yes | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/invitations/send

`ark.send_spot_quote_invitations`

Creates carrier invitation records for a visible spot quote and sends the requested email or in-app notifications.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `invitations` | array<object> | Yes | - | min items: 1; max items: 100 |
| `invitations[]` | object | Yes | - | - |
| `invitations[].driverUserId` | string | No | Required when channel is in_app. | format: uuid |
| `invitations[].carrierId` | string | Yes | - | format: uuid |
| `invitations[].channel` | string | Yes | - | one of: in_app, email |
| `invitations[].message` | string | Yes | - | min length: 1; max length: 5000 |
| `invitations[].email` | string | No | Required when channel is email. | format: email |
| `invitations[].pushNotification` | object | No | Required when channel is in_app. | - |
| `invitations[].pushNotification.title` | string | No | - | min length: 1; max length: 120 |
| `invitations[].pushNotification.body` | string | No | - | min length: 1; max length: 500 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/invitations/send' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "invitations": [
    {
      "carrierId": "<carrierId>",
      "channel": "in_app",
      "message": "<message>"
    }
  ]
}'
```

#### Success response shape

Invitation send result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.totalInvitations` | integer | Yes | - | - |
| `data.notificationsSent` | integer | Yes | - | - |
| `data.invitations` | array<object> | Yes | - | - |
| `data.invitations[]` | object | Yes | - | - |
| `data.invitations[].id` | string | Yes | - | format: uuid |
| `data.invitations[].carrierId` | string | Yes | - | format: uuid |
| `data.invitations[].driverUserId` | string \| null | Yes | - | format: uuid |
| `data.invitations[].channel` | string | Yes | - | one of: in_app, email |
| `data.invitations[].invitedAt` | string \| null | Yes | - | format: date-time |
| `data.notificationResults` | array<object> | Yes | - | - |
| `data.notificationResults[]` | object | Yes | - | - |
| `data.notificationResults[].index` | integer | Yes | - | - |
| `data.notificationResults[].invitationId` | string \| null | Yes | - | format: uuid |
| `data.notificationResults[].carrierId` | string | Yes | - | format: uuid |
| `data.notificationResults[].channel` | string | Yes | - | one of: push, email |
| `data.notificationResults[].success` | boolean | Yes | - | - |
| `data.notificationResults[].reason` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/mark-lost

`ark.mark_spot_quote_lost`

Marks a visible open spot quote lost and rejects the pending customer quote through the same transactional workflow as the website.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `reason` | string | No | - | max length: 500 |
| `lostToCompetitor` | boolean | No | - | default: false |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/mark-lost' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Spot quote action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.result` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/miles/calculate

`ark.calculate_spot_quote_miles`

Calculates truck route miles for a visible spot quote using stop coordinates and stores total/per-stop mileage.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `stops` | array<RouteCoordinateStopInput> | Yes | Stop coordinates ordered by stopIndex. Count must match the persisted stops. | min items: 2; max items: 25 |
| `stops[]` | RouteCoordinateStopInput | Yes | - | - |
| `stops[].lat` | number | Yes | - | min: -90; max: 90 |
| `stops[].lng` | number | Yes | - | min: -180; max: 180 |
| `stops[].stopIndex` | integer | Yes | - | min: 0 |
| `trailer` | string | No | - | min length: 1; max length: 100 |
| `size` | string | No | - | min length: 1; max length: 50 |
| `dimensions` | RouteDimensionsInput | No | - | - |
| `dimensions.length` | number | No | - | - |
| `dimensions.width` | number | No | - | - |
| `dimensions.height` | number | No | - | - |
| `dimensions.weight` | number | No | - | - |
| `hazmat` | boolean | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/miles/calculate' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "stops": [
    {
      "lat": -90,
      "lng": -180,
      "stopIndex": 0
    },
    {
      "lat": -90,
      "lng": -180,
      "stopIndex": 0
    }
  ]
}'
```

#### Success response shape

Calculated spot quote miles

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | RouteMilesResult | Yes | - | - |
| `data.loadId` | string | No | - | format: uuid |
| `data.spotQuoteId` | string | No | - | format: uuid |
| `data.totalMiles` | number | Yes | - | - |
| `data.perStopMiles` | array<number> | Yes | - | - |
| `data.perStopMiles[]` | number | Yes | - | - |
| `data.durationSeconds` | integer | Yes | - | - |
| `data.typicalDurationSeconds` | integer \| null | Yes | - | - |
| `data.routeParamsHash` | string | Yes | - | - |
| `data.segmentCount` | integer | Yes | - | min: 0 |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/quotes

`ark.create_spot_quote_customer_quote`

Creates and sends a customer quote for a visible spot quote, records the quote event, updates the quote workflow status, and notifies watchers.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerId` | string | Yes | Customer ID. Must match the visible spot quote customer. | format: uuid |
| `price` | number | Yes | Customer quote price. | - |
| `markupPercent` | number | No | - | min: 0; max: 100 |
| `fromBidId` | string \| null | No | Carrier bid used to generate the customer quote. In the hold-bid workflow, bidId is used as the quote source. | format: uuid |
| `etaMode` | string \| null | No | - | one of: time_away, exact_time, null |
| `etaHours` | integer \| null | No | - | min: 0; max: 999 |
| `etaMinutes` | integer \| null | No | - | min: 0; max: 59 |
| `etaDatetime` | string \| null | No | - | format: date-time |
| `etaTimezone` | string \| null | No | - | max length: 100 |
| `quoteVehicleType` | string \| null | No | - | max length: 100 |
| `trailerLength` | number \| null | No | - | - |
| `trailerWidth` | number \| null | No | - | - |
| `trailerHeight` | number \| null | No | - | - |
| `trailerDimensionsUnit` | string \| null | No | - | one of: feet, inches, null |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/quotes' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "<customerId>",
  "price": 1
}'
```

#### Success response shape

Spot quote customer quote create result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SpotQuoteCustomerQuoteCreateResult | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.quoteId` | string | Yes | - | format: uuid |
| `data.quote` | SpotQuoteCustomerQuote | Yes | - | - |
| `data.quote.id` | string | Yes | - | format: uuid |
| `data.quote.spot_load_id` | string | Yes | - | format: uuid |
| `data.quote.customer_id` | string | Yes | - | format: uuid |
| `data.quote.price` | number | Yes | - | - |
| `data.quote.currency` | string \| null | No | - | - |
| `data.quote.status` | string | Yes | - | - |
| `data.quote.from_bid_id` | string \| null | No | - | format: uuid |
| `data.quote.email_sent_at` | string \| null | No | - | format: date-time |
| `data.heldBid` | SpotQuoteBid \| null | Yes | - | - |
| `data.notificationCount` | integer | Yes | - | min: 0 |
| `data.emailSent` | boolean | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/quotes/hold-bid

`ark.create_spot_quote_customer_quote_and_hold_bid`

Creates and sends a customer quote from a visible pending carrier bid, then holds that bid pending the customer response.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `bidId` | string | Yes | Visible pending carrier bid to hold after creating the customer quote. | format: uuid |
| `holdReason` | string | No | - | max length: 5000 |
| `customerId` | string | Yes | Customer ID. Must match the visible spot quote customer. | format: uuid |
| `price` | number | Yes | Customer quote price. | - |
| `markupPercent` | number | No | - | min: 0; max: 100 |
| `fromBidId` | string \| null | No | Carrier bid used to generate the customer quote. In the hold-bid workflow, bidId is used as the quote source. | format: uuid |
| `etaMode` | string \| null | No | - | one of: time_away, exact_time, null |
| `etaHours` | integer \| null | No | - | min: 0; max: 999 |
| `etaMinutes` | integer \| null | No | - | min: 0; max: 59 |
| `etaDatetime` | string \| null | No | - | format: date-time |
| `etaTimezone` | string \| null | No | - | max length: 100 |
| `quoteVehicleType` | string \| null | No | - | max length: 100 |
| `trailerLength` | number \| null | No | - | - |
| `trailerWidth` | number \| null | No | - | - |
| `trailerHeight` | number \| null | No | - | - |
| `trailerDimensionsUnit` | string \| null | No | - | one of: feet, inches, null |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/quotes/hold-bid' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "bidId": "<bidId>",
  "customerId": "<customerId>",
  "price": 1
}'
```

#### Success response shape

Spot quote customer quote create result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | SpotQuoteCustomerQuoteCreateResult | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.quoteId` | string | Yes | - | format: uuid |
| `data.quote` | SpotQuoteCustomerQuote | Yes | - | - |
| `data.quote.id` | string | Yes | - | format: uuid |
| `data.quote.spot_load_id` | string | Yes | - | format: uuid |
| `data.quote.customer_id` | string | Yes | - | format: uuid |
| `data.quote.price` | number | Yes | - | - |
| `data.quote.currency` | string \| null | No | - | - |
| `data.quote.status` | string | Yes | - | - |
| `data.quote.from_bid_id` | string \| null | No | - | format: uuid |
| `data.quote.email_sent_at` | string \| null | No | - | format: date-time |
| `data.heldBid` | SpotQuoteBid \| null | Yes | - | - |
| `data.notificationCount` | integer | Yes | - | min: 0 |
| `data.emailSent` | boolean | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/reopen

`ark.reopen_spot_quote`

Moves a visible lost spot quote back to the active workflow using the same transactional workflow as the website.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/reopen' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Spot quote action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.result` | object | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/unhold

`ark.unhold_spot_quote`

Releases a hold from a visible held spot quote and notifies watchers.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/unhold' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Spot quote hold action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.spotQuote` | object | Yes | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/unwatch

`ark.unwatch_spot_quote`

Removes the connected actor as a watcher for a visible spot quote.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/unwatch' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Spot quote watch action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.watchId` | string \| null | Yes | - | format: uuid |
| `data.watched` | boolean | Yes | - | - |
| `data.alreadyWatched` | boolean | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/{spotQuoteId}/watch

`ark.watch_spot_quote`

Adds the connected actor as a watcher for a visible spot quote.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.spotQuoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/<spotQuoteId>/watch' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Spot quote watch action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.watchId` | string \| null | Yes | - | format: uuid |
| `data.watched` | boolean | Yes | - | - |
| `data.alreadyWatched` | boolean | No | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### PATCH /api/v1/spot-quotes/bids/{bidId}

`ark.update_spot_quote_bid`

Updates carrier, DOT, MC, price, price-per-mile, or deadhead details on a visible pending spot quote bid.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.bidId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `carrierId` | string \| null | No | Carrier ID when the carrier already exists in ARK. | format: uuid |
| `carrierName` | string | No | - | min length: 1; max length: 200 |
| `dotNumber` | string | No | - | min length: 1; max length: 30 |
| `mcNumber` | string \| null | No | - | max length: 30 |
| `price` | number | No | - | - |
| `pricePerMile` | number \| null | No | - | - |
| `distanceDeadheadMiles` | number \| null | No | - | min: 0 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/spot-quotes/bids/<bidId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Spot quote bid action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.bidId` | string | Yes | - | format: uuid |
| `data.bid` | SpotQuoteBid | Yes | - | - |
| `data.bid.id` | string | Yes | - | format: uuid |
| `data.bid.spot_load_id` | string | Yes | - | format: uuid |
| `data.bid.carrier_id` | string \| null | No | - | format: uuid |
| `data.bid.carrier_name` | string \| null | No | - | - |
| `data.bid.price` | number \| null | No | - | - |
| `data.bid.currency` | string \| null | No | - | - |
| `data.bid.status` | string | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/bids/{bidId}/award

`ark.award_spot_quote_bid`

Awards a visible pending spot quote bid through the transactional award workflow and notifies the relevant users.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.bidId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `customerQuotePrice` | number | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/bids/<bidId>/award' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Spot quote bid action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.bidId` | string | Yes | - | format: uuid |
| `data.bid` | SpotQuoteBid | Yes | - | - |
| `data.bid.id` | string | Yes | - | format: uuid |
| `data.bid.spot_load_id` | string | Yes | - | format: uuid |
| `data.bid.carrier_id` | string \| null | No | - | format: uuid |
| `data.bid.carrier_name` | string \| null | No | - | - |
| `data.bid.price` | number \| null | No | - | - |
| `data.bid.currency` | string \| null | No | - | - |
| `data.bid.status` | string | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/bids/{bidId}/hold

`ark.hold_spot_quote_bid`

Places a visible pending spot quote bid on hold when no other bid is held for the same spot quote.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.bidId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `reason` | string | Yes | - | min length: 1; max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/bids/<bidId>/hold' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "<reason>"
}'
```

#### Success response shape

Spot quote bid action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.bidId` | string | Yes | - | format: uuid |
| `data.bid` | SpotQuoteBid | Yes | - | - |
| `data.bid.id` | string | Yes | - | format: uuid |
| `data.bid.spot_load_id` | string | Yes | - | format: uuid |
| `data.bid.carrier_id` | string \| null | No | - | format: uuid |
| `data.bid.carrier_name` | string \| null | No | - | - |
| `data.bid.price` | number \| null | No | - | - |
| `data.bid.currency` | string \| null | No | - | - |
| `data.bid.status` | string | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/bids/{bidId}/reject

`ark.reject_spot_quote_bid`

Rejects a visible pending spot quote bid and optionally stores the rejection message.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.bidId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `message` | string | No | - | max length: 5000 |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/bids/<bidId>/reject' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Spot quote bid action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.bidId` | string | Yes | - | format: uuid |
| `data.bid` | SpotQuoteBid | Yes | - | - |
| `data.bid.id` | string | Yes | - | format: uuid |
| `data.bid.spot_load_id` | string | Yes | - | format: uuid |
| `data.bid.carrier_id` | string \| null | No | - | format: uuid |
| `data.bid.carrier_name` | string \| null | No | - | - |
| `data.bid.price` | number \| null | No | - | - |
| `data.bid.currency` | string \| null | No | - | - |
| `data.bid.status` | string | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/bids/{bidId}/unhold

`ark.unhold_spot_quote_bid`

Releases the hold on a visible held spot quote bid.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.bidId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/bids/<bidId>/unhold' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Spot quote bid action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.bidId` | string | Yes | - | format: uuid |
| `data.bid` | SpotQuoteBid | Yes | - | - |
| `data.bid.id` | string | Yes | - | format: uuid |
| `data.bid.spot_load_id` | string | Yes | - | format: uuid |
| `data.bid.carrier_id` | string \| null | No | - | format: uuid |
| `data.bid.carrier_name` | string \| null | No | - | - |
| `data.bid.price` | number \| null | No | - | - |
| `data.bid.currency` | string \| null | No | - | - |
| `data.bid.status` | string | Yes | - | - |
| `data.result` | object | No | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/spot-quotes/intelligence

`ark.get_spot_quote_intelligence`

Returns lane history, pricing statistics, nearby carrier context, and quote recommendations for a pickup and delivery ZIP pair.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.pickup_zip` | string | Yes | - | - |
| `query.delivery_zip` | string | Yes | - | - |
| `query.days_back` | integer | No | - | default: 90; min: 1; max: 365 |
| `query.carrier_radius` | integer | No | - | default: 150; min: 1; max: 500 |
| `query.max_carriers` | integer | No | - | default: 20; min: 1; max: 100 |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use all teams visible to the connected actor. | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/spot-quotes/intelligence?pickup_zip=<pickup_zip>&delivery_zip=<delivery_zip>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Spot quote intelligence

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.lane` | object | Yes | - | - |
| `data.lane.statistics` | object \| null | Yes | - | - |
| `data.lane.recentHistory` | array<object> | Yes | - | - |
| `data.lane.recentHistory[]` | object | Yes | - | - |
| `data.lane.distance` | number \| null | Yes | - | - |
| `data.carriers` | array<object> | Yes | - | - |
| `data.carriers[]` | object | Yes | - | - |
| `data.recommendations` | array<SpotQuoteIntelligenceRecommendation> | Yes | - | - |
| `data.recommendations[]` | SpotQuoteIntelligenceRecommendation | Yes | - | - |
| `data.recommendations[].type` | string | Yes | - | one of: success, info, caution, warning |
| `data.recommendations[].category` | string | Yes | - | one of: lane_history, pricing, carrier_availability, distance |
| `data.recommendations[].message` | string | Yes | - | - |
| `data.recommendations[].action` | string | Yes | - | - |
| `data.metadata` | object | Yes | - | - |
| `data.metadata.pickupZip` | string | Yes | - | - |
| `data.metadata.deliveryZip` | string | Yes | - | - |
| `data.metadata.generatedAt` | string | Yes | - | format: date-time |
| `data.metadata.searchRadiusMiles` | integer | Yes | - | - |
| `data.metadata.daysAnalyzed` | integer | Yes | - | - |
| `data.metadata.teamIds` | array<string> | Yes | - | - |
| `data.metadata.teamIds[]` | string | Yes | - | format: uuid |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/spot-quotes/lane-history

`ark.get_spot_quote_lane_history`

Returns historical spot quote awards, pricing statistics, pricing trend, and market activity for a pickup and delivery ZIP pair.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.pickup_zip` | string | Yes | - | - |
| `query.delivery_zip` | string | Yes | - | - |
| `query.days_back` | integer | No | - | default: 90; min: 1; max: 365 |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |
| `query.team_ids` | string | No | Comma-separated visible team IDs. Omit to use all teams visible to the connected actor. | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/spot-quotes/lane-history?pickup_zip=<pickup_zip>&delivery_zip=<delivery_zip>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Spot quote lane history

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.lane` | object | Yes | - | - |
| `data.lane.pickupZip` | string | Yes | - | - |
| `data.lane.deliveryZip` | string | Yes | - | - |
| `data.statistics` | object \| null | Yes | - | - |
| `data.recentHistory` | array<object> | Yes | - | - |
| `data.recentHistory[]` | object | Yes | - | - |
| `data.pricingTrend` | string | Yes | - | one of: up, down, stable, unknown |
| `data.marketActivity` | string | Yes | - | one of: high, medium, low |
| `data.metadata` | object | Yes | - | - |
| `data.metadata.daysBack` | integer | Yes | - | - |
| `data.metadata.limit` | integer | Yes | - | - |
| `data.metadata.teamIds` | array<string> | Yes | - | - |
| `data.metadata.teamIds[]` | string | Yes | - | format: uuid |
| `data.metadata.generatedAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/spot-quotes/nearby-carriers

`ark.search_spot_quote_nearby_carriers`

Finds carriers near a ZIP code using ARK carrier location history for spot quote bid targeting.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.zip` | string | Yes | - | - |
| `query.radius_miles` | integer | No | - | default: 150; min: 1; max: 500 |
| `query.limit` | integer | No | - | default: 50; min: 1; max: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/spot-quotes/nearby-carriers?zip=<zip>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Nearby spot quote carriers

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.search` | object | Yes | - | - |
| `data.search.zipCode` | string | Yes | - | - |
| `data.search.radiusMiles` | integer | Yes | - | - |
| `data.search.limit` | integer | Yes | - | - |
| `data.carriers` | array<object> | Yes | - | - |
| `data.carriers[]` | object | Yes | - | - |
| `data.count` | integer | Yes | - | - |
| `data.message` | string \| null | Yes | - | - |
| `data.generatedAt` | string | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/spot-quotes/quotes/{quoteId}/accept

`ark.accept_spot_quote_customer_quote`

Accepts a visible pending customer quote through the transactional quote acceptance workflow.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.quoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

_None._

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/quotes/<quoteId>/accept' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Spot quote customer quote action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.quoteId` | string | Yes | - | format: uuid |
| `data.quote` | object | Yes | - | - |
| `data.result` | object | Yes | - | - |
| `data.load` | object \| null | Yes | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### POST /api/v1/spot-quotes/quotes/{quoteId}/reject

`ark.reject_spot_quote_customer_quote`

Rejects a visible pending customer quote through the transactional quote rejection workflow.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:write` |
| ARK permissions | `canEditLoad` |
| Team visibility | Required and enforced |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.quoteId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. | min length: 1; max length: 255 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `reason` | string | No | - | max length: 5000 |
| `lostToCompetitor` | boolean \| null | No | - | - |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/spot-quotes/quotes/<quoteId>/reject' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Spot quote customer quote action result

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.spotQuoteId` | string | Yes | - | format: uuid |
| `data.quoteId` | string | Yes | - | format: uuid |
| `data.quote` | object | Yes | - | - |
| `data.result` | object | Yes | - | - |
| `data.load` | object \| null | Yes | - | - |
| `data.notificationCount` | integer | Yes | - | - |
| `data.sideEffectError` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/spot-quotes/zip-coordinates

`ark.lookup_spot_quote_zip_coordinates`

Looks up ZIP centroid coordinates used by spot quote lane, distance, and carrier-search workflows.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.zip_codes` | string | No | Comma-separated ZIP codes to resolve. | - |
| `query.zip` | array<string> | No | Repeatable ZIP code parameter alternative. | min items: 1; max items: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/spot-quotes/zip-coordinates' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Spot quote ZIP coordinates

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.coordinates` | array<object> | Yes | - | - |
| `data.coordinates[]` | object | Yes | - | - |
| `data.coordinates[].zip_code` | string | Yes | - | - |
| `data.coordinates[].place_name` | string \| null | No | - | - |
| `data.coordinates[].state_name` | string \| null | No | - | - |
| `data.coordinates[].state_code` | string \| null | No | - | - |
| `data.coordinates[].latitude` | number \| null | Yes | - | - |
| `data.coordinates[].longitude` | number \| null | Yes | - | - |
| `data.coordinates[].accuracy_score` | number \| null | No | - | - |
| `data.missingZipCodes` | array<string> | Yes | - | - |
| `data.missingZipCodes[]` | string | Yes | - | - |
| `data.count` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/teams

`ark.list_visible_teams`

Lists team IDs and names visible to the connected actor.

| Requirement | Value |
| --- | --- |
| Scopes | `context:read` |
| ARK permissions | None |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | No | - | min length: 1; max length: 100 |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/teams' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Visible teams

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | VisibleTeamsPayload | Yes | - | - |
| `data.items` | array<Team> | Yes | - | - |
| `data.items[]` | Team | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].name` | string | Yes | - | - |
| `data.items[].notes` | string \| null | Yes | - | - |
| `data.items[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.items[].modifiedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### POST /api/v1/teams

`ark.create_team`

Creates an organization team and optional team address. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `name` | string | Yes | - | min length: 1; max length: 200 |
| `notes` | string \| null | No | - | max length: 5000 |
| `address` | TeamWriteAddressRequest | No | - | - |
| `address.address` | string \| null | No | - | max length: 500 |
| `address.address2` | string \| null | No | - | max length: 500 |
| `address.city` | string \| null | No | - | max length: 200 |
| `address.state` | string \| null | No | - | max length: 50 |
| `address.zip` | string \| null | No | - | max length: 30 |
| `address.phone` | string \| null | No | - | max length: 50 |
| `address.email` | string \| null | No | - | max length: 500 |
| `address.country` | string | No | - | one of: USA, CAN, MEX |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/teams' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "<name>"
}'
```

#### Success response shape

Created team

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | TeamMutationPayload | Yes | - | - |
| `data.team` | ManagedTeam | Yes | - | - |
| `data.team.id` | string | Yes | - | format: uuid |
| `data.team.name` | string | Yes | - | - |
| `data.team.notes` | string \| null | Yes | - | - |
| `data.team.address` | TeamAddress \| null | Yes | - | - |
| `data.team.createdAt` | string \| null | Yes | - | format: date-time |
| `data.team.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### PATCH /api/v1/teams/{teamId}

`ark.update_team`

Updates an organization team profile and optional team address. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.teamId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `name` | string | No | - | min length: 1; max length: 200 |
| `notes` | string \| null | No | - | max length: 5000 |
| `address` | TeamWriteAddressRequest | No | - | - |
| `address.address` | string \| null | No | - | max length: 500 |
| `address.address2` | string \| null | No | - | max length: 500 |
| `address.city` | string \| null | No | - | max length: 200 |
| `address.state` | string \| null | No | - | max length: 50 |
| `address.zip` | string \| null | No | - | max length: 30 |
| `address.phone` | string \| null | No | - | max length: 50 |
| `address.email` | string \| null | No | - | max length: 500 |
| `address.country` | string | No | - | one of: USA, CAN, MEX |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/teams/<teamId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Success response shape

Updated team

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | TeamMutationPayload | Yes | - | - |
| `data.team` | ManagedTeam | Yes | - | - |
| `data.team.id` | string | Yes | - | format: uuid |
| `data.team.name` | string | Yes | - | - |
| `data.team.notes` | string \| null | Yes | - | - |
| `data.team.address` | TeamAddress \| null | Yes | - | - |
| `data.team.createdAt` | string \| null | Yes | - | format: date-time |
| `data.team.modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/tracking/internal/availability

`ark.check_tracking_availability`

Checks whether internal ARK Tracking can start for a visible dispatch and explains consent, app-account, phone, active-dispatch, or org-setting blockers.

| Requirement | Value |
| --- | --- |
| Scopes | `loads:dispatch` |
| ARK permissions | `canAssignLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.dispatch_id` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/tracking/internal/availability?dispatch_id=<dispatch_id>' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Tracking availability

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | TrackingAvailabilityData | Yes | - | - |
| `data.provider` | string | Yes | - | one of: internal |
| `data.dispatchId` | string | Yes | - | format: uuid |
| `data.loadId` | string | Yes | - | format: uuid |
| `data.available` | boolean | Yes | - | - |
| `data.reason` | string \| null | Yes | - | - |
| `data.driverName` | string \| null | Yes | - | - |
| `data.requiresConsent` | boolean | Yes | - | - |
| `data.driverHasAppAccount` | boolean | Yes | - | - |
| `data.missingPhone` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### GET /api/v1/tracking/internal/session-metrics

`ark.get_tracking_session_metrics`

Returns internal ARK Tracking session-level duration, location update, ETA, reverse-geocode, and estimated cost counters.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.billing_period` | string | No | - | - |
| `query.load_id` | string | No | - | format: uuid |
| `query.session_id` | string | No | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/tracking/internal/session-metrics' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Tracking session metrics

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | TrackingSessionMetricsData | Yes | - | - |
| `data.organizationId` | string | Yes | - | format: uuid |
| `data.filters` | TrackingSessionMetricsFilters | Yes | - | - |
| `data.filters.billingPeriod` | string | No | - | - |
| `data.filters.loadId` | string | No | - | format: uuid |
| `data.filters.sessionId` | string | No | - | format: uuid |
| `data.rows` | array<TrackingSessionMetricsRow> | Yes | - | - |
| `data.rows[]` | TrackingSessionMetricsRow | Yes | - | - |
| `data.rows[].organization_id` | string | Yes | - | format: uuid |
| `data.rows[].billing_period` | string \| null | Yes | - | - |
| `data.rows[].load_id` | string | Yes | - | format: uuid |
| `data.rows[].dispatch_id` | string | Yes | - | format: uuid |
| `data.rows[].session_id` | string | Yes | - | - |
| `data.rows[].driver_active_started_at` | string \| null | Yes | - | format: date-time |
| `data.rows[].ended_at` | string \| null | Yes | - | format: date-time |
| `data.rows[].driver_active_minutes` | integer | Yes | - | - |
| `data.rows[].location_update_count` | integer | Yes | - | - |
| `data.rows[].eta_call_count` | integer | Yes | - | - |
| `data.rows[].eta_success_count` | integer | Yes | - | - |
| `data.rows[].eta_estimated_cost_micros` | integer | Yes | - | - |
| `data.rows[].reverse_geocode_call_count` | integer | Yes | - | - |
| `data.rows[].reverse_geocode_success_count` | integer | Yes | - | - |
| `data.rows[].reverse_geocode_estimated_cost_micros` | integer | Yes | - | - |
| `data.rows[].total_estimated_cost_micros` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/tracking/internal/usage-summary

`ark.get_tracking_usage_summary`

Returns internal ARK Tracking usage summary rows for the connected organization, optionally filtered to one billing period.

| Requirement | Value |
| --- | --- |
| Scopes | `billing:read` |
| ARK permissions | `canViewBilling` |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.billing_period` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/tracking/internal/usage-summary' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Tracking usage summary

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | TrackingUsageSummaryData | Yes | - | - |
| `data.organizationId` | string | Yes | - | format: uuid |
| `data.billingPeriod` | string \| null | Yes | - | - |
| `data.rows` | array<TrackingUsageSummaryRow> | Yes | - | - |
| `data.rows[]` | TrackingUsageSummaryRow | Yes | - | - |
| `data.rows[].organization_id` | string | Yes | - | format: uuid |
| `data.rows[].billing_period` | string \| null | Yes | - | - |
| `data.rows[].tracking_provider` | string | Yes | - | - |
| `data.rows[].completed_sessions` | integer \| null | Yes | - | - |
| `data.rows[].total_sessions` | integer \| null | Yes | - | - |
| `data.rows[].total_tracking_minutes` | integer \| null | Yes | - | - |
| `data.rows[].total_location_updates` | integer \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### GET /api/v1/users

`ark.search_users`

Searches active organization users visible through the connected actor team scope.

| Requirement | Value |
| --- | --- |
| Scopes | `people:read` |
| ARK permissions | `canViewPeople` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.q` | string | No | - | min length: 1; max length: 100 |
| `query.team_ids` | string | No | Comma-separated visible team IDs. | - |
| `query.roles` | string | No | Comma-separated user roles. | - |
| `query.include_inactive` | boolean | No | - | default: false |
| `query.limit` | integer | No | - | default: 25; min: 1; max: 100 |
| `query.cursor` | string | No | - | - |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/users' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Visible users

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UserSearchPayload | Yes | - | - |
| `data.items` | array<User> | Yes | - | - |
| `data.items[]` | User | Yes | - | - |
| `data.items[].id` | string | Yes | - | format: uuid |
| `data.items[].firstName` | string \| null | Yes | - | - |
| `data.items[].lastName` | string \| null | Yes | - | - |
| `data.items[].email` | string \| null | Yes | - | - |
| `data.items[].phone` | string \| null | Yes | - | - |
| `data.items[].role` | string \| null | Yes | - | - |
| `data.items[].active` | boolean | Yes | - | - |
| `data.items[].teamIds` | array<string> | Yes | - | - |
| `data.items[].teamIds[]` | string | Yes | - | format: uuid |
| `data.items[].defaultTeamId` | string \| null | Yes | - | format: uuid |
| `data.items[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.items[].modifiedAt` | string \| null | Yes | - | format: date-time |
| `data.pagination` | CursorPagination | Yes | - | - |
| `data.pagination.limit` | integer | Yes | - | - |
| `data.pagination.hasMore` | boolean | Yes | - | - |
| `data.pagination.nextCursor` | string \| null | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |

### DELETE /api/v1/users/{userId}

`ark.deactivate_user`

Deactivates an organization user account and prevents login. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

_None._

#### Example request

```bash
curl -X DELETE 'https://arktms.com/api/v1/users/<userId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>"
```

#### Success response shape

Deactivated user

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | DeactivateUserPayload | Yes | - | - |
| `data.userId` | string | Yes | - | format: uuid |
| `data.active` | boolean | Yes | - | one of: false |
| `data.wasAlreadyInactive` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PATCH /api/v1/users/{userId}

`ark.update_user`

Updates an organization user name and email. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `email` | string | No | - | format: email; max length: 320 |
| `firstName` | string | No | - | min length: 2; max length: 100 |
| `lastName` | string | No | - | min length: 2; max length: 100 |

#### Example request

```bash
curl -X PATCH 'https://arktms.com/api/v1/users/<userId>' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '"<body>"'
```

#### Success response shape

Updated user

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UpdateUserPayload | Yes | - | - |
| `data.userId` | string | Yes | - | format: uuid |
| `data.email` | string \| null | Yes | - | format: email |
| `data.firstName` | string \| null | Yes | - | - |
| `data.lastName` | string \| null | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/users/{userId}/backup-users

`ark.list_user_backup_users`

Lists backup users copied on outgoing emails where the selected organization broker is the broker of record. Requires tenant-admin access and admin:read.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/users/<userId>/backup-users' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

User backup users

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | ListUserBackupUsersPayload | Yes | - | - |
| `data.userId` | string | Yes | - | format: uuid |
| `data.backupUsers` | array<UserBackupUser> | Yes | - | - |
| `data.backupUsers[]` | UserBackupUser | Yes | - | - |
| `data.backupUsers[].assignmentId` | string | Yes | - | - |
| `data.backupUsers[].userId` | string | Yes | - | format: uuid |
| `data.backupUsers[].firstName` | string \| null | Yes | - | - |
| `data.backupUsers[].lastName` | string \| null | Yes | - | - |
| `data.backupUsers[].email` | string \| null | Yes | - | format: email |
| `data.backupUsers[].role` | string \| null | Yes | - | - |
| `data.backupUsers[].active` | boolean | Yes | - | - |
| `data.backupUsers[].createdAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PUT /api/v1/users/{userId}/backup-users

`ark.set_user_backup_users`

Replaces a broker user's backup-user assignments for absence coverage and outgoing email CC workflows. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `backupUserIds` | array<string> | Yes | Replacement backup user IDs. Use an empty array to clear all backup users. | max items: 50 |
| `backupUserIds[]` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/users/<userId>/backup-users' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "backupUserIds": [
    "<backupUserIds>"
  ]
}'
```

#### Success response shape

Updated user backup users

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | SetUserBackupUsersPayload | Yes | - | - |
| `data.userId` | string | Yes | - | format: uuid |
| `data.backupUsers` | array<UserBackupUser> | Yes | - | - |
| `data.backupUsers[]` | UserBackupUser | Yes | - | - |
| `data.backupUsers[].assignmentId` | string | Yes | - | - |
| `data.backupUsers[].userId` | string | Yes | - | format: uuid |
| `data.backupUsers[].firstName` | string \| null | Yes | - | - |
| `data.backupUsers[].lastName` | string \| null | Yes | - | - |
| `data.backupUsers[].email` | string \| null | Yes | - | format: email |
| `data.backupUsers[].role` | string \| null | Yes | - | - |
| `data.backupUsers[].active` | boolean | Yes | - | - |
| `data.backupUsers[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.addedBackupUserIds` | array<string> | Yes | - | - |
| `data.addedBackupUserIds[]` | string | Yes | - | format: uuid |
| `data.removedBackupUserIds` | array<string> | Yes | - | - |
| `data.removedBackupUserIds[]` | string | Yes | - | format: uuid |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/users/{userId}/commission-settings

`ark.get_user_commission_settings`

Returns default role commission settings and customer-specific commission overrides for an organization user. Requires tenant-admin access and admin:read.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/users/<userId>/commission-settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

User commission settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UserCommissionSettingsPayload | Yes | - | - |
| `data.user` | UserCommissionSettingsUser | Yes | - | - |
| `data.user.id` | string | Yes | - | format: uuid |
| `data.user.email` | string \| null | Yes | - | format: email |
| `data.user.firstName` | string \| null | Yes | - | - |
| `data.user.lastName` | string \| null | Yes | - | - |
| `data.user.role` | string \| null | Yes | - | - |
| `data.user.active` | boolean | Yes | - | - |
| `data.roleCommissions` | array<UserCommissionDefault> | Yes | - | - |
| `data.roleCommissions[]` | UserCommissionDefault | Yes | - | - |
| `data.roleCommissions[].id` | string | Yes | - | - |
| `data.roleCommissions[].role` | CommissionRole | Yes | - | one of: Broker, Sales Rep, Customer Service Rep, Manager |
| `data.roleCommissions[].marginPercentage` | number | Yes | - | - |
| `data.roleCommissions[].revenuePercentage` | number | Yes | - | - |
| `data.roleCommissions[].flatRate` | number | Yes | - | - |
| `data.roleCommissions[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.overrides` | array<UserCommissionOverride> | Yes | - | - |
| `data.overrides[]` | UserCommissionOverride | Yes | - | - |
| `data.overrides[].id` | string | Yes | - | - |
| `data.overrides[].customerId` | string | Yes | - | format: uuid |
| `data.overrides[].customerName` | string \| null | Yes | - | - |
| `data.overrides[].role` | CommissionRole | Yes | - | one of: Broker, Sales Rep, Customer Service Rep, Manager |
| `data.overrides[].marginPercentage` | number \| null | Yes | - | - |
| `data.overrides[].revenuePercentage` | number \| null | Yes | - | - |
| `data.overrides[].flatRate` | number \| null | Yes | - | - |
| `data.overrides[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.overrides[].updatedAt` | string \| null | Yes | - | format: date-time |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PUT /api/v1/users/{userId}/commission-settings

`ark.update_user_commission_settings`

Updates default role commissions and optionally replaces customer-specific commission overrides for an organization user. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `roleCommissions` | array<CommissionDefaultInput> | No | Default role commission updates. Omitted roles are left unchanged. | max items: 4 |
| `roleCommissions[]` | CommissionDefaultInput | No | - | - |
| `roleCommissions[].role` | CommissionRole | No | - | one of: Broker, Sales Rep, Customer Service Rep, Manager |
| `roleCommissions[].marginPercentage` | number | No | - | default: 0; min: 0; max: 100 |
| `roleCommissions[].revenuePercentage` | number | No | - | default: 0; min: 0; max: 100 |
| `roleCommissions[].flatRate` | number | No | - | default: 0; min: 0 |
| `overrides` | array<CommissionOverrideInput> | No | Full replacement customer-specific override set. Use an empty array to clear overrides. | max items: 500 |
| `overrides[]` | CommissionOverrideInput | No | - | - |
| `overrides[].customerId` | string | No | - | format: uuid |
| `overrides[].role` | CommissionRole | No | - | one of: Broker, Sales Rep, Customer Service Rep, Manager |
| `overrides[].marginPercentage` | number \| null | No | - | default: null; min: 0; max: 100 |
| `overrides[].revenuePercentage` | number \| null | No | - | default: null; min: 0; max: 100 |
| `overrides[].flatRate` | number \| null | No | - | default: null; min: 0 |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/users/<userId>/commission-settings' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '"<body>"'
```

#### Success response shape

Updated user commission settings

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UpdateUserCommissionSettingsPayload | Yes | - | - |
| `data.user` | UserCommissionSettingsUser | Yes | - | - |
| `data.user.id` | string | Yes | - | format: uuid |
| `data.user.email` | string \| null | Yes | - | format: email |
| `data.user.firstName` | string \| null | Yes | - | - |
| `data.user.lastName` | string \| null | Yes | - | - |
| `data.user.role` | string \| null | Yes | - | - |
| `data.user.active` | boolean | Yes | - | - |
| `data.roleCommissions` | array<UserCommissionDefault> | Yes | - | - |
| `data.roleCommissions[]` | UserCommissionDefault | Yes | - | - |
| `data.roleCommissions[].id` | string | Yes | - | - |
| `data.roleCommissions[].role` | CommissionRole | Yes | - | one of: Broker, Sales Rep, Customer Service Rep, Manager |
| `data.roleCommissions[].marginPercentage` | number | Yes | - | - |
| `data.roleCommissions[].revenuePercentage` | number | Yes | - | - |
| `data.roleCommissions[].flatRate` | number | Yes | - | - |
| `data.roleCommissions[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.overrides` | array<UserCommissionOverride> | Yes | - | - |
| `data.overrides[]` | UserCommissionOverride | Yes | - | - |
| `data.overrides[].id` | string | Yes | - | - |
| `data.overrides[].customerId` | string | Yes | - | format: uuid |
| `data.overrides[].customerName` | string \| null | Yes | - | - |
| `data.overrides[].role` | CommissionRole | Yes | - | one of: Broker, Sales Rep, Customer Service Rep, Manager |
| `data.overrides[].marginPercentage` | number \| null | Yes | - | - |
| `data.overrides[].revenuePercentage` | number \| null | Yes | - | - |
| `data.overrides[].flatRate` | number \| null | Yes | - | - |
| `data.overrides[].createdAt` | string \| null | Yes | - | format: date-time |
| `data.overrides[].updatedAt` | string \| null | Yes | - | format: date-time |
| `data.updatedRoleCommissionRoles` | array<CommissionRole> | Yes | - | - |
| `data.updatedRoleCommissionRoles[]` | CommissionRole | Yes | - | one of: Broker, Sales Rep, Customer Service Rep, Manager |
| `data.replacedOverrides` | boolean | Yes | - | - |
| `data.overrideCount` | integer | Yes | - | min: 0 |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/users/{userId}/permissions

`ark.get_user_permissions`

Lists public ARK permissions with enabled state for an organization user. Requires tenant-admin access and admin:read.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:read` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/users/<userId>/permissions' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

User permissions

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | GetUserPermissionsPayload | Yes | - | - |
| `data.user` | UserPermissionsUser | Yes | - | - |
| `data.user.id` | string | Yes | - | format: uuid |
| `data.user.email` | string \| null | Yes | - | format: email |
| `data.user.firstName` | string \| null | Yes | - | - |
| `data.user.lastName` | string \| null | Yes | - | - |
| `data.user.role` | string \| null | Yes | - | - |
| `data.user.active` | boolean | Yes | - | - |
| `data.enabledPermissionIds` | array<string> | Yes | - | - |
| `data.enabledPermissionIds[]` | string | Yes | - | format: uuid |
| `data.permissions` | array<UserPermissionItem> | Yes | - | - |
| `data.permissions[]` | UserPermissionItem | Yes | - | - |
| `data.permissions[].id` | string | Yes | - | format: uuid |
| `data.permissions[].description` | string | Yes | - | - |
| `data.permissions[].category` | string | Yes | - | - |
| `data.permissions[].enabled` | boolean | Yes | - | - |
| `data.categories` | array<UserPermissionCategory> | Yes | - | - |
| `data.categories[]` | UserPermissionCategory | Yes | - | - |
| `data.categories[].name` | string | Yes | - | - |
| `data.categories[].viewPermissionId` | string \| null | Yes | - | format: uuid |
| `data.categories[].permissions` | array<UserPermissionItem> | Yes | - | - |
| `data.categories[].permissions[]` | UserPermissionItem | Yes | - | - |
| `data.categories[].permissions[].id` | string | Yes | - | format: uuid |
| `data.categories[].permissions[].description` | string | Yes | - | - |
| `data.categories[].permissions[].category` | string | Yes | - | - |
| `data.categories[].permissions[].enabled` | boolean | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### PUT /api/v1/users/{userId}/permissions

`ark.update_user_permissions`

Replaces enabled public ARK permissions for an organization user. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `enabledPermissionIds` | array<string> | Yes | Full replacement list of enabled public ARK permission IDs. Category view permissions are added automatically when required. | max items: 500 |
| `enabledPermissionIds[]` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/users/<userId>/permissions' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "enabledPermissionIds": [
    "<enabledPermissionIds>"
  ]
}'
```

#### Success response shape

Updated user permissions

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | UpdateUserPermissionsPayload | Yes | - | - |
| `data.user` | UserPermissionsUser | Yes | - | - |
| `data.user.id` | string | Yes | - | format: uuid |
| `data.user.email` | string \| null | Yes | - | format: email |
| `data.user.firstName` | string \| null | Yes | - | - |
| `data.user.lastName` | string \| null | Yes | - | - |
| `data.user.role` | string \| null | Yes | - | - |
| `data.user.active` | boolean | Yes | - | - |
| `data.enabledPermissionIds` | array<string> | Yes | - | - |
| `data.enabledPermissionIds[]` | string | Yes | - | format: uuid |
| `data.permissions` | array<UserPermissionItem> | Yes | - | - |
| `data.permissions[]` | UserPermissionItem | Yes | - | - |
| `data.permissions[].id` | string | Yes | - | format: uuid |
| `data.permissions[].description` | string | Yes | - | - |
| `data.permissions[].category` | string | Yes | - | - |
| `data.permissions[].enabled` | boolean | Yes | - | - |
| `data.categories` | array<UserPermissionCategory> | Yes | - | - |
| `data.categories[]` | UserPermissionCategory | Yes | - | - |
| `data.categories[].name` | string | Yes | - | - |
| `data.categories[].viewPermissionId` | string \| null | Yes | - | format: uuid |
| `data.categories[].permissions` | array<UserPermissionItem> | Yes | - | - |
| `data.categories[].permissions[]` | UserPermissionItem | Yes | - | - |
| `data.categories[].permissions[].id` | string | Yes | - | format: uuid |
| `data.categories[].permissions[].description` | string | Yes | - | - |
| `data.categories[].permissions[].category` | string | Yes | - | - |
| `data.categories[].permissions[].enabled` | boolean | Yes | - | - |
| `data.grantedPermissionIds` | array<string> | Yes | - | - |
| `data.grantedPermissionIds[]` | string | Yes | - | format: uuid |
| `data.revokedPermissionIds` | array<string> | Yes | - | - |
| `data.revokedPermissionIds[]` | string | Yes | - | format: uuid |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |
| 409 | Idempotency conflict or in-progress retry |

### PUT /api/v1/users/{userId}/teams

`ark.assign_user_to_teams`

Replaces a non-driver organization user team assignment set and default team. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `path.userId` | string | Yes | - | format: uuid |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `teamIds` | array<string> | Yes | - | min items: 1; max items: 100 |
| `teamIds[]` | string | Yes | - | format: uuid |
| `defaultTeamId` | string | Yes | - | format: uuid |

#### Example request

```bash
curl -X PUT 'https://arktms.com/api/v1/users/<userId>/teams' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "teamIds": [
    "<teamIds>"
  ],
  "defaultTeamId": "<defaultTeamId>"
}'
```

#### Success response shape

Updated user team assignments

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | AssignUserTeamsPayload | Yes | - | - |
| `data.userId` | string | Yes | - | format: uuid |
| `data.teamIds` | array<string> | Yes | - | - |
| `data.teamIds[]` | string | Yes | - | format: uuid |
| `data.defaultTeamId` | string | Yes | - | format: uuid |
| `data.teams` | array<AssignedUserTeam> | Yes | - | - |
| `data.teams[]` | AssignedUserTeam | Yes | - | - |
| `data.teams[].id` | string | Yes | - | format: uuid |
| `data.teams[].name` | string \| null | Yes | - | - |
| `data.teams[].isDefault` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 404 | Resource not found |

### POST /api/v1/users/invite

`ark.invite_user`

Invites a broker user or reactivates an inactive organization user, assigning teams in the same admin action. Requires tenant-admin access and admin:write.

| Requirement | Value |
| --- | --- |
| Scopes | `admin:write` |
| ARK permissions | None |
| Team visibility | Not entity-scoped |
| Idempotency-Key | Required for this write |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Expanded preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `header.Idempotency-Key` | string | Yes | Required for external write operations. Reuse the same key only for exact retries of the same request body. | min length: 1; max length: 200 |

#### Request body

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `email` | string | Yes | - | format: email; max length: 320 |
| `firstName` | string | Yes | - | min length: 2; max length: 100 |
| `lastName` | string | Yes | - | min length: 2; max length: 100 |
| `teamIds` | array<string> | No | - | min items: 1; max items: 100 |
| `teamIds[]` | string | No | - | format: uuid |
| `defaultTeamId` | string | No | - | format: uuid |

#### Example request

```bash
curl -X POST 'https://arktms.com/api/v1/users/invite' \
  -H "Authorization: Bearer $ARK_API_TOKEN" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "<email>",
  "firstName": "<firstName>",
  "lastName": "<lastName>"
}'
```

#### Success response shape

Invited or reactivated user

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | one of: api_response |
| `ok` | boolean | Yes | - | one of: true |
| `api_version` | string | Yes | - | one of: 2026-05-31 |
| `request_id` | string | Yes | - | - |
| `data` | InviteUserPayload | Yes | - | - |
| `data.userId` | string | Yes | - | format: uuid |
| `data.email` | string | Yes | - | format: email |
| `data.firstName` | string | Yes | - | - |
| `data.lastName` | string | Yes | - | - |
| `data.active` | boolean | Yes | - | one of: true |
| `data.reactivated` | boolean | Yes | - | - |
| `data.teamIds` | array<string> | Yes | - | - |
| `data.teamIds[]` | string | Yes | - | format: uuid |
| `data.defaultTeamId` | string | Yes | - | format: uuid |
| `data.teams` | array<AssignedUserTeam> | Yes | - | - |
| `data.teams[]` | AssignedUserTeam | Yes | - | - |
| `data.teams[].id` | string | Yes | - | format: uuid |
| `data.teams[].name` | string \| null | Yes | - | - |
| `data.teams[].isDefault` | boolean | Yes | - | - |
| `data.message` | string | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid request |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |

### GET /api/v1/work-queue

`ark.get_work_queue`

Returns a compact operational work queue for the connected user, organization, and visible teams.

| Requirement | Value |
| --- | --- |
| Scopes | `operations:read`, `loads:read` |
| ARK permissions | `canViewLoads` |
| Team visibility | Required and enforced |
| Idempotency-Key | Not required |
| Approval | No MCP approval on REST API-token calls |
| Rate limit | API credential and organization budgets |
| Preview access | Core preview |

#### Parameters

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `query.team_ids` | string | No | Comma-separated team IDs. Omit to use all teams visible to the connected user. | - |
| `query.include_edi` | boolean | No | - | default: true |
| `query.include_loads` | boolean | No | - | default: true |

#### Request body

_None._

#### Example request

```bash
curl 'https://arktms.com/api/v1/work-queue' \
  -H "Authorization: Bearer $ARK_API_TOKEN"
```

#### Success response shape

Work queue summary

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `object` | string | Yes | - | - |
| `ok` | boolean | Yes | - | - |
| `api_version` | string | Yes | - | - |
| `request_id` | string | Yes | - | - |
| `data` | object | Yes | - | - |
| `data.organizationId` | string | Yes | - | - |
| `data.teamIds` | array<string> | Yes | - | - |
| `data.teamIds[]` | string | Yes | - | - |
| `data.loads` | object | Yes | - | - |
| `data.loads.visibleOpenCount` | integer | Yes | - | - |
| `data.edi` | object | Yes | - | - |
| `data.edi.visible` | boolean | Yes | - | - |
| `data.edi.receivedTenderCount` | integer | Yes | - | - |

#### Errors

| Status | Meaning |
| --- | --- |
| 401 | Authentication required |
| 403 | Permission, scope, team, or entitlement denied |
| 409 | Idempotency conflict or in-progress retry |