Initiate Recovery
Add a new employee to an existing recovery campaign.
POST
/api/v1/recover/campaign/employee/addDescription
This API is used to add a new employee to an existing Recover Campaign, along with return address and assigned item details.
Request
Headers
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer <token> | Yes |
| Content-Type | application/json | Yes |
Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| campaign_number | number | Yes | Unique identifier of the recover campaign |
| work_email | string | Conditional | Employee work email address. Required unless recovery_reason is 3 (Offboarding) |
| personal_email | string | Conditional | Employee personal email address. Required when recovery_reason is 3 (Offboarding); optional otherwise |
| notification_email_preference | string | No | Where recovery email and SMS updates are sent: work or personal. Defaults to work. Falls back to the other contact when the preferred field is empty. |
| firstname | string | Yes | Employee first name |
| lastname | string | Yes | Employee last name |
| work_phone | string | Conditional | Employee work phone number. Required unless recovery_reason is 3 (Offboarding) |
| personal_phone | string | Conditional | Employee personal phone number (digits; without country code). Required when recovery_reason is 3 (Offboarding); optional otherwise. Dial country is taken from address country |
| address_line_1 | string | Yes | Employee address line 1 |
| address_line_2 | string | No | Secondary address line |
| city | string | Yes | Employee city |
| state | string | Conditional | Employee state or region. Required when is_state_required is true for the selected country. See GET /api/v1/countries. |
| zip | string | Yes | Employee ZIP/postal code |
| country | string | Yes | Employee country code |
| recovery_reason | number | No | Recovery Reason for the user. 1 = Refresh, 2 = Break-Fix, 3 = Offboarding, 4 = Other |
| recovery_reason_note | string | No | Recovery reason note is required only if recovery_reason is 4 (Other) |
| 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 |
| items | array | Yes | 1 to 5 item objects assigned to employee |
| items[].item | string | Yes | Name/label of the asset |
| items[].item_serial_no | string | No | Serial number of the asset |
| items[].item_asset_id | string | No | Internal asset ID |
| items[].item_imei | string | No | IMEI number for mobile devices |
| items[].custom_field_1 | string | No | Custom metadata field 1 |
| items[].custom_field_2 | string | No | Custom metadata field 2 |
| items[].is_legal_hold | number | No | Send 1 to mark device for legal hold |
Response
Response Fields
| Field | Type | Description |
|---|---|---|
| success | boolean | Indicates if the request was successful |
| recovery_code | string | Generated recovery code |
| message | string | Success message |
Notes
- Use work_email for the employee work email. Legacy email is still accepted for backward compatibility with existing integrations. Required unless recovery_reason is 3 (Offboarding).
- Use work_phone for the employee work phone. Legacy phone is still accepted for backward compatibility with existing integrations. Required unless Offboarding.
- When recovery_reason is 3 (Offboarding), personal_email and personal_phone are required and work email/phone are optional. For all other reasons, work contacts are required and personal contacts are optional.
- notification_email_preference controls both email and SMS destinations. Personal phone country is stored from address country (same as work phone country).
- Optional department 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.
- The state field is required only for countries where GET /api/v1/countries returns is_state_required: true. When required, the value must match a valid state or region for that country.
- zip is required for all countries, including GB.
- Campaign names must be unique within your organization. Attempting to create a campaign with a duplicate name will result in a 409 Conflict error.
- The campaign_number is automatically generated and serves as the primary identifier for all subsequent operations.
- New campaigns are created with an active status by default. You can track their progress through the Campaign List and Campaign Details endpoints.
- Use descriptive campaign names and descriptions to help organize and identify recovery efforts across different time periods or departments.
Related Endpoints
Did this page help you?
Request
curl -X POST https://uat.unduit.com/api-exposed/api/v1/recover/campaign/employee/add \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"campaign_number": 17449821332893,
"work_email": "john.doe@company.com",
"personal_email": "john.doe@gmail.com",
"personal_phone": "5559876543",
"notification_email_preference": "work",
"firstname": "John",
"lastname": "Doe",
"work_phone": "1632960123",
"address_line_1": "123 Business Park",
"address_line_2": "Suite 200",
"city": "New York",
"state": "NY",
"zip": "10001",
"country": "US",
"recovery_reason": 4,
"recovery_reason_note": "Employee is leaving the company",
"department": "Finance",
"items": [
{
"item": "MacBook Pro 16",
"item_serial_no": "C02XL0XXXXX1",
"item_asset_id": "IT-APPLE-001",
"item_imei": "",
"custom_field_1": "2023-issue",
"custom_field_2": "Finance Dept",
"is_legal_hold": 1
},
{
"item": "iPhone 15 Pro",
"item_serial_no": "DNXXXXXX1JKL",
"item_asset_id": "IT-APPLE-002",
"item_imei": "35693803564XXXX",
"custom_field_1": "Mobile Plan: Corp",
"custom_field_2": "Manager Approval"
}
]
}'Success Response (200)
{
"success": true,
"recovery_code": "175153062352257",
"message": "Employee added successfully"
}