quipteams API
POST/equip-by-role
scopeequip:writereturns202rate limit20 / min

Equip an employee by role

Equips an employee with one of a role's kits. Nothing is assigned or quoted at call time: the employee receives a scheduling link where they confirm their details and, when the role has more than one kit, pick the kit they want. The stock check runs when they submit the form. Devices in stock are assigned; otherwise the whole kit is quoted. A role with no kits answers 400 and creates nothing.

Body

role_idrequired
stringRole to equip from. Must belong to your company and have at least one kit.
recipient.office_id
stringNot supported here — this endpoint emails a person a scheduling form. Use POST /equip with recipient.office_id to send a kit to an office.
recipient.namerequired
stringEmployee full name.
recipient.emailrequired
stringEmployee email — receives the scheduling link.
recipient.countryrequired
stringISO-3166 alpha-2 code or country name. Sets the stock region for the equip decision, so the employee sees it prefilled and read-only on the scheduling form.
recipient.address
stringDelivery address, if known.
recipient.phone
stringContact phone number.
recipient.phone_country_code
stringDial code for the phone number.
recipient.national_id
stringGovernment ID (CPF / DNI / SSN) where customs requires it.
recipient.when_to_contact
stringYYYY-MM-DD — holds the scheduling link email until this date.
recipient.hire_date
stringYYYY-MM-DD start date.
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.

Example request

json
{
  "role_id": "3c4d5e6f-7a8b-4910-a1b2-c3d4e5f60718",
  "recipient": {
    "name": "Ana Silva",
    "email": "ana.silva@acme.com",
    "country": "ES"
  },
  "requester_email": "it@acme.com"
}

Example response

json
{
  "data": {
    "mode": "scheduling_requested",
    "role": { "id": "3c4d5e6f-7a8b-4910-a1b2-c3d4e5f60718", "name": "Engineer" },
    "kit_count": 2,
    "kit_choice_required": true,
    "scheduling_request": {
      "id": "9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4",
      "status": "pending_notification",
      "scheduling_url": "https://app.quipteams.com/scheduling/xK3...",
      "schedule_link": "https://app.quipteams.com/scheduling/xK3...?code=A7K2MP",
      "access_code": "A7K2MP",
      "email_dispatched": true,
      "notification_scheduled_for": null,
      "expires_at": null
    }
  }
}