Record a transfer

Records a transfer — a subculture onto fresh media — for one plant or explant. Send exactly one of plant_id or explant_id. Everything else is optional: the date defaults to today and the cycle to the next one in the record's history.

Fill in the fields your lab has added to transfers with custom_fields. They are checked against your lab's field list exactly as the transfer form in xPlant checks them, so a key the lab has not defined, or a value of the wrong kind, is refused before anything is saved.

Send an Idempotency-Key when you might retry: a repeated transfer would also advance the cycle twice.

Send an Idempotency-Key header to make retries safe: a repeat with the same key within 24 hours returns the first response instead of writing twice. See Idempotency.

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	No	Any unique string you choose per logical write. A retry carrying the same key within 24 hours returns the first result instead of writing again. Scoped to your API key and this operation. 8–255 characters. Must match `^[A-Za-z0-9._:~-]+$`.

Request body

Field	Type	Required	Description
`plant_id`	string (uuid)	No	The plant this is for. Send exactly one of `plant_id` or `explant_id`.
`explant_id`	string (uuid)	No	The explant this is for. Send exactly one of `plant_id` or `explant_id`.
`transfer_date`	string	No	When the transfer was done: a date such as `2026-09-24`, or a full ISO 8601 timestamp. Defaults to today (UTC).
`from_location`	string	No	Where the culture was before the transfer, in your lab's own words — a room, shelf or hood. Up to 200 characters.
`to_location`	string	No	Where the culture went. Up to 200 characters.
`transfer_cycle`	integer	No	Which subculture this is for the plant or explant — 1 for the first. Defaults to one more than the highest cycle already recorded for it. At least 1.
`notes`	string	No	Up to 5000 characters.
`custom_fields`	object \| null	No	Values for the fields your lab has added to transfers, keyed by field key — for example `{ "vessel_lot": "LOT-2291" }`. Each value must suit its field: text, a number, `true` or `false`, a date (stored as `YYYY-MM-DD`), or one of a list field's options. `null` leaves a field empty. A key your lab has not defined is refused, and the values may total at most 10,000 bytes. Explant transfers only: a plant transfer takes no custom fields.

Example

curl -X POST https://app.xplantpro.com/api/v1/transfers \
  -H "Authorization: Bearer $XPLANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "explant_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "transfer_date": "2026-09-24",
    "from_location": "Growth room 1, shelf B2",
    "to_location": "Growth room 1, shelf C1",
    "notes": "LINE-0412 onto fresh multiplication medium. Two jars browning at the base, set aside.",
    "custom_fields": {
      "vessel_lot": "LOT-2291",
      "hood": "Hood 2"
    }
  }'

Response

201 with { "ok": true, "data": … }. data holds the result.

Field	Type	Required	Description
`id`	string (uuid)	Yes	—
`entity_type`	`"plant"` \| `"explant"`	Yes	Whether the transfer was of a plant or an explant.
`entity_id`	string (uuid)	Yes	The plant's or explant's id.
`transfer_date`	string \| null	Yes	When the transfer was done, as an ISO 8601 timestamp.
`transfer_cycle`	integer \| null	Yes	Which subculture this was for the plant or explant — 1 for the first.
`from_location`	string \| null	Yes	Where the culture was before the transfer.
`to_location`	string \| null	Yes	Where the culture went.
`status`	string	Yes	`active` for a transfer recorded through the API. Transfers scheduled in xPlant read `pending` until someone marks them `completed` or `cancelled`.
`notes`	string \| null	Yes	—
`created_at`	string \| null	Yes	—
`custom_fields`	object	Yes	Your lab's own fields on this transfer, keyed by field key. Always an object: `{}` when none were filled in, and always `{}` on a plant transfer.

Response

{
  "ok": true,
  "data": {
    "id": "c7d8e9f0-a1b2-4c3d-8e4f-5a6b7c8d9e0f",
    "entity_type": "explant",
    "entity_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "transfer_date": "2026-09-24T00:00:00+00:00",
    "transfer_cycle": 5,
    "from_location": "Growth room 1, shelf B2",
    "to_location": "Growth room 1, shelf C1",
    "status": "active",
    "notes": "LINE-0412 onto fresh multiplication medium. Two jars browning at the base, set aside.",
    "created_at": "2026-09-24T09:12:44.000Z",
    "custom_fields": {
      "vessel_lot": "LOT-2291",
      "hood": "Hood 2"
    }
  }
}

Response header	Meaning
`Idempotent-Replay`	`true` when this response is a replay of an earlier request with the same `Idempotency-Key`.
`X-Request-Id`	Identifies this request. Include it when you contact support.

Errors

Status	Code	When
`400`	`VALIDATION_ERROR`	The request body is not valid JSON.
`401`	`UNAUTHORIZED`	The key is missing, malformed or revoked, or its owner is no longer a member of the workspace.
`402`	`PAID_PLAN_REQUIRED`	The workspace's plan does not include the API. The full API is included with xPlant+ Teams and Enterprise; on Hobby and Pro Lab, keys can connect devices only.
`403`	`FORBIDDEN`	The key lacks a scope this operation requires, or its owner's current role in the workspace cannot use it — a key never does more than its owner can in xPlant. `error` names the scope, and for a role, the role it needs.
`403`	`DEVICE_TOKEN_NOT_ACCEPTED`	A device token was sent; this operation needs a workspace API key.
`404`	`NOT_FOUND`	The plant or explant is not in this workspace.
`409`	`IDEMPOTENCY_IN_FLIGHT`	A request with this `Idempotency-Key` is still being processed; retry after `Retry-After` seconds.
`422`	`VALIDATION_ERROR`	The `Idempotency-Key` header is malformed.
`422`	`VALIDATION_ERROR`	A field failed validation, or neither or both of `plant_id` and `explant_id` were sent. `error` names the first problem, for example `transfer_cycle: Number must be greater than or equal to 1`.
`422`	`VALIDATION_ERROR`	`custom_fields` names a field your lab has not defined, gives a field a value of the wrong kind, or was sent for a plant transfer. `error` names the field.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests for this key, device token or workspace. Wait `Retry-After` seconds.
`500`	`TRANSFER_CREATE_FAILED`	The transfer could not be saved. Retry with the same `Idempotency-Key`.

Branch on code, never on the error text. See Errors.

HeadersCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

ErrorsCopy Anchor Link

On this page

Headers

Request body

Example

Response

Errors