Transfers

Creates a standalone transfer of stock from one location to another (Transfers → Create).

Requires ManageTransfers and an Idempotency-Key header. Body: { "sourceLocationId": 1, "destinationLocationId": 4, "notes": "Restock van 2", "lines": [ { "itemId": 12, "quantity": 3 } ] }. For each line the server picks the concrete units the way stock moves do: units of that item at exactly sourceLocationId (not its child locations) that are not in transit, not in a bundle and not already on an open transfer — fewest units consumed, then oldest first. The units are grouped into transfer lines and the transfer is created Pending. When its value reaches the organization's approval threshold it also gets an approval request (approvalStatus``Pending, managers are emailed) and must be approved (POST /api/v1/transfers/{id}/approve, which moves it straight to InTransit) or rejected before anything else can happen. Otherwise the lifecycle is POST …/pick → POST …/start → POST …/complete (or POST …/cancel while Pending). Nothing is written unless every line can be filled. Returns the new transfer; its Location header is /api/v1/transfers/{id}.

post/api/v1/transfers

Request

  • Base URL: https://app.flexonthejob.com
  • URL: https://app.flexonthejob.com/api/v1/transfers
  • Auth: HTTP bearer

Request body

sourceLocationIdinteger

Location the stock leaves (see GET /api/v1/locations). Must be active and must hold enough available units of every line's item. Example: 1.

destinationLocationIdinteger

Location the stock arrives at; must be active and different from sourceLocationId. Example: 4.

notesstring nullable

Optional free-text note shown on the transfer, up to 2000 characters. Example: Restock van 2.

Response

The created transfer with its lines.

idinteger

Numeric id used in /api/v1/transfers/{id}. Unique within this organization. Example: 318.

syncIdstring uuid

Stable cross-device identifier (GUID) — also the pagination cursor value. Example: 0b8f4c1e-6f1a-4a5e-9d7c-2f3e4a5b6c7d.

statusstring

Transfer status name. One of Draft, Pending (created, stock reserved, not yet picked up), InTransit, AtWaypoint, InTransitToWaypoint, InTransitToDestination, Completed (delivered), Cancelled, Failed.

notesstring nullable

Free-text notes recorded on the transfer. Example: Transfer for Job J-2026-0042. Null when none.

jobIdinteger nullable

Id of the job this transfer supplies (see /api/v1/jobs/{id}); null for a standalone or sales-order transfer.

jobNumberstring nullable

Job number of jobId at read time. Example: J-2026-0042. Null when there is no job.

salesOrderIdinteger nullable

Id of the sales order this transfer fulfils; null otherwise.

isJobTransferboolean

True for a transfer created for a job (materials to its job site, or a direct / counter sale). Standalone transfers (both flags false) are the ones pick / start / complete / fail accept; job-site and standalone transfers can be cancelled with POST /api/v1/transfers/{id}/cancel.

isSalesOrderTransferboolean

True for a transfer that fulfils a sales order.

sourceLocationIdinteger nullable

Id of the location the stock leaves (see /api/v1/locations/{id}); null when the lines come from several locations or from no location.

sourceLocationNamestring nullable

Name of sourceLocationId. Example: Main Warehouse. Null when there is none.

destinationLocationIdinteger nullable

Id of the location the stock goes to — for a job-site transfer, the job's site location; null for a de-listing.

destinationLocationNamestring nullable

Name of destinationLocationId. Example: Job Site - J-2026-0042. Null when there is none.

requiresApprovalboolean

True when the transfer's value exceeded the organization's approval threshold when it was created. Job-site transfers never require approval.

approvalStatusstring nullable

State of the transfer's approval: Pending (awaiting POST /api/v1/transfers/{id}/approve or /reject), Approved or Rejected; null when the transfer never needed approval.

lineCountinteger

Number of item lines on the transfer. Example: 4.

transferDatestring date-time

When the transfer was initiated, ISO-8601 UTC. Example: 2026-09-23T14:05:00Z.

initiatedByIdstring nullable

Identity user id of the person who created the transfer (for an API/MCP-created transfer, the key's creator); null when unknown on this server.

completedByIdstring nullable

Identity user id of the person who completed (received) the transfer; null until it is completed.

createdAtstring date-time

Creation time, ISO-8601 UTC. Example: 2026-09-23T14:05:00Z.

updatedAtstring date-time nullable

Last modification time, ISO-8601 UTC; null when never modified since creation.

rejectionReasonstring nullable

Why the transfer's approval was rejected (from POST /api/v1/transfers/{id}/reject or the app); null otherwise.

currentWaypointIdinteger nullable

Id of the waypoint the transfer is heading to or stopped at (waypoints[].id); null when it has no waypoints or is heading to its final destination.

Changes

No recorded changes to this operation across all 1 revision of this API.