Remote Asset Recovery - Bulk Upload

Add multiple employees to a recovery campaign in one request.

POST

/api/v1/recover/campaign/employee/bulk-add

Description

The Bulk Upload API enables customers to add multiple employees (up to 100) to a recovery campaign in one request. This simplifies large-scale data entry by accepting employee objects under a single campaign. A successful upload returns unique recovery codes for each entry.

Request

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes
Content-Type	application/json	Yes

Request Body

Parameter	Type	Required	Description
campaign_number	number	Yes	Unique identifier of the recovery campaign
users	array	Yes	Array of employee objects (1-100 employees recommended)

Employee Object Fields

Parameter	Type	Required	Description
users[].campaign_number	number	Yes	Unique identifier of the recovery campaign
users[].firstname	string	Yes	First name of the employee
users[].lastname	string	Yes	Last name of the employee
users[].send_notifications_to	string	No	Where recovery email and SMS updates are sent: work or personal. Defaults to work
users[].work_email	string	Conditional	Employee work email address. Required when send_notifications_to is work; optional when personal
users[].personal_email	string	Conditional	Employee personal email address. Required when send_notifications_to is personal; optional when work
users[].work_phone	string	Conditional	Work phone number. Required when send_notifications_to is work; optional when personal
users[].personal_phone	string	Conditional	Personal phone number (digits; without country code). Required when send_notifications_to is personal; optional when work. Dial country is taken from address country
users[].address_line_1	string	Yes	Primary address line
users[].address_line_2	string	No	Secondary address line
users[].city	string	Yes	City of the employee address
users[].state	string	Conditional	State name. Required when is_state_required is true for country. See GET /api/v1/countries.
users[].zip	string	Yes	ZIP or postal code
users[].country	string	Yes	ISO 2-letter country code
users[].recovery_reason	number	No	Recovery Reason for the user. 1 = Refresh, 2 = Break-Fix, 3 = Offboarding, 4 = Other
users[].recovery_reason_note	string	No	Recovery reason note is required only if recovery_reason is 4 (Other)
users[].department	string	No	Department name (not ID). Matched case-insensitively for the company; created if missing (minimum 2 characters when creating). Stored as department_id on the recovery employee

Item Object Fields

Parameter	Type	Required	Description
users[].items[].item	string	Yes	Device/item name
users[].items[].item_serial_no	string	No	Serial number
users[].items[].item_asset_id	string	No	Asset ID
users[].items[].item_imei	string	No	IMEI number
users[].items[].custom_field_1	string	No	Custom field 1
users[].items[].custom_field_2	string	No	Custom field 2
users[].items[].is_legal_hold	number	No	Send 1 to mark device for legal hold

Response

Response Fields

Field	Type	Description
recovery_codes	array	Generated recovery codes for each uploaded user

Notes

The maximum recommended batch size is 100 employees per request to ensure optimal performance and reliability.
Each employee receives a unique recovery code that can be used to track their individual recovery status.
Required employee fields include firstname, lastname, city, zip, and country. work_email and work_phone are required when send_notifications_to is work (or omitted); optional when personal. state is required only when GET /api/v1/countries marks the selected country with is_state_required: true. zip is required for all countries.
personal_email and personal_phone are required when send_notifications_to is personal; optional when preference is work. Personal phone country is stored from address country. send_notifications_to is optional (defaults to work) and accepts work or personal, and applies to both email and SMS.
Optional department on each user is a department name (not ID). The API finds an active department for the company by case-insensitive name, or creates one (name must be at least 2 characters), then stores department_id on the recovery employee.
If any employee in the batch has validation errors, the entire request may fail. Ensure all data is properly formatted before submission.
Recovery codes are generated automatically and returned in the response for record-keeping and tracking purposes.

Related Endpoints

Initiate Recovery

Create a new recovery campaign

Campaign List

Get all recovery campaigns

Did this page help you?

Request

curl -X POST https://dev-api.unduit.com/api/v1/recover/campaign/employee/bulk-add \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_number": 6720250912001,
    "users": [
      {
        "firstname": "Jane",
        "lastname": "Doe",
        "send_notifications_to": "personal",
        "work_email": "[email protected]",
        "personal_email": "[email protected]",
        "work_phone": "4155550123",
        "personal_phone": "4155550199",
        "address_line_1": "123 Market Street",
        "address_line_2": "Apt 4B",
        "city": "San Francisco",
        "state": "California",
        "zip": "94103",
        "country": "US",
        "recovery_reason": 4,
        "recovery_reason_note": "Employee is leaving the company",
        "department": "Finance",
        "items": [
          {
            "item": "iPhone 14 Pro",
            "item_serial_no": "SN12345XYZ",
            "item_asset_id": "AST-00981",
            "item_imei": "356789123456789",
            "custom_field_1": "AppleCare+ Active",
            "custom_field_2": "Delivered on 2025-09-01",
            "is_legal_hold": 1
          },
          {
            "item": "MacBook Pro 16-inch",
            "item_serial_no": "SN98765ABC",
            "item_asset_id": "AST-00982",
            "item_imei": "",
            "custom_field_1": "3-Year Warranty",
            "custom_field_2": "Configured with M3 Max"
          }
        ]
      },
      {
        "firstname": "John",
        "lastname": "Smith",
        "send_notifications_to": "work",
        "work_email": "[email protected]",
        "personal_email": "",
        "work_phone": "442079460958",
        "address_line_1": "221B Baker Street",
        "address_line_2": "",
        "city": "San Francisco",
        "state": "California",
        "zip": "94103",
        "country": "US",
        "recovery_reason": 3,
        "recovery_reason_note": "",
        "department": "Engineering",
        "items": [
          {
            "item": "Samsung Galaxy S23 Ultra",
            "item_serial_no": "SN54321LMN",
            "item_asset_id": "AST-01011",
            "item_imei": "359876543210123",
            "custom_field_1": "Enterprise Account",
            "custom_field_2": "5G Enabled"
          }
        ]
      }
    ]
  }'

Success Response (200)

{
  "recovery_codes": [
    "175731749252477",
    "175731749252478"
  ]
}