quipteams

POST/equip

scopeequip:writereturns202rate limit20 / min

Equip an employee with a kit

Equips an employee with a saved kit. If a new stored device is available for every item in their region, the devices are assigned; otherwise, a quote is created for the full kit. Used or returned units are never assigned. Use `dry_run: true` to check availability without creating anything.

Body

kit_idrequired

stringKit to equip. Must belong to your company.

recipient.namerequired

stringEmployee full name. Optional when office_id is set.

recipient.emailrequired

stringEmployee email — receives the scheduling link. Optional when office_id is set and the office has a contact email on file.

recipient.countryrequired

stringISO-3166 alpha-2 code or country name. Drives stock availability; regional aliases like "EU" are rejected. Rejected alongside office_id — the office supplies it.

recipient.office_id

stringShip the kit to a saved office (id from GET /api/v1/offices) instead of a person. The office supplies country + address (rejected alongside them, and alongside national_id). Stock is drawn only from the office's own country — no EU-wide pooling — and no scheduling form is sent: the address is already on file.

recipient.address

stringDelivery address, if known.

recipient.phone

stringContact phone number.

recipient.phone_country_code

stringDial code, combined with `phone` when both are present.

recipient.national_id

stringGovernment ID (CPF / DNI / SSN) where customs requires it. Persisted on the operation; on the quote branch it is passed to ops as a note.

recipient.when_to_contact

stringYYYY-MM-DD — holds the scheduling link until this date.

recipient.hire_date

stringYYYY-MM-DD start date. Persisted on the quote branch.

recipient.comments

stringNotes for the logistics team.

requester_email

stringWho to attribute the request to. Defaults to the API key creator.

requester_name

stringDisplay name on the quote, when one is created.

notification_emails

string[]Extra addresses copied on the resulting operation or quote.

dry_run

booleanPreview availability only. Nothing is created; responds 200.

Example request

json

{
  "kit_id": "8c1f2d3e-4a5b-4c6d-9e70-1f2a3b4c5d6e",
  "recipient": {
    "name": "Ana Silva",
    "email": "ana.silva@acme.com",
    "country": "ES",
    "address": "Calle Gran Via 1, Madrid",
    "phone": "600123456",
    "phone_country_code": "+34",
    "when_to_contact": "2026-08-03"
  },
  "requester_email": "it@acme.com"
}

Example response

json

{
  "data": {
    "mode": "assigned",
    "kit": { "id": "8c1f2d3e-4a5b-4c6d-9e70-1f2a3b4c5d6e", "name": "Engineering Standard" },
    "device_action": {
      "id": "3d4e5f60-7a8b-4c9d-8e1f-2a3b4c5d6e7f",
      "action_id": "AST12345678",
      "action_type": "Assign",
      "status": "in_progress",
      "device": { "serial_number": "C02XY1234ABC", "model": "Apple MacBook Pro 14" },
      "new_recipient": { "name": "Ana Silva", "email": "ana.silva@acme.com", "country": "ES" }
    },
    "lines": [
      {
        "kit_device_id": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
        "item": "Apple MacBook Pro 14",
        "needed": 1,
        "available": 3,
        "reason": null
      }
    ]
  }
}