Add a technician
createTechnicianCreates a technician membership for your business, linking an existing user or establishing a new identity. Assigns roles, buddies, leads, and service areas while sending notifications.
Instructions
Add a technician
Creates a technician membership under the current business. If the phone/email matches an existing user, their account is linked. Otherwise a new user identity is created. Either way the membership starts active. The new member is notified (live mode only, best-effort): an email when email is supplied, an SMS when phone is supplied, both when both — informational only, no activation step (login stays passwordless: magic link / OTP). If the technician was previously removed (deactive) they are reactivated instead (also notified). Owner/Administrator groups cannot be assigned via API key, and not at all in sandbox mode.
Optional relations (all validated; any missing id → 404 TECHNICIAN_NOT_FOUND with missing_ids): buddy_ids sets this technician's buddy list (use when creating a lead); lead_ids adds this technician as a buddy of each named lead (use when creating a buddy — the buddy-side way to attach the same lead↔buddy relation); service_area_ids assigns the technician to those service areas.
start_location_type=office snapshots the business address + coordinates into the technician at create time; address, start_location_lat, start_location_long in the body are ignored. Requires the business to have coordinates set (else 400 BUSINESS_LOCATION_MISSING). start_location_type=home (or empty) uses the address + coordinates from the body.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email address. At least one of phone/email is required (identity resolution key). | ||
| phone | No | At least one of phone/email is required (identity resolution key). | |
| address | No | Home address (the day-start point when start_location_type=home). | |
| lead_ids | No | Leads this technician is a buddy of (set when creating a buddy; the technician is appended to each lead's buddy list). Optional; max 50 technician ids. | |
| buddy_ids | No | Buddies of this technician (set when creating a lead). Optional; max 50 technician ids. | |
| full_name | Yes | The person's full display name. Required; max 255 chars. | |
| job_title | No | Display title (e.g. "Senior HVAC Technician"). | |
| join_date | No | First working day (YYYY-MM-DD). | |
| assignment_tier | No | Crew tier the matching engine assigns by: lead (can head a job), buddy (crew helper), float (excluded from auto crew-assign). | |
| idempotency_key | No | Unique key making retries safe: a repeat send with the same key replays the original response (header Idempotent-Replayed: true) instead of re-running the operation. Reusing a key with a different body returns 422 IDEMPOTENCY_KEY_REUSE. (sent as the Idempotency-Key header) | |
| service_area_ids | No | Service areas to assign the technician to. Optional; max 50. Discover via GET /service-areas. | |
| business_group_id | Yes | Role group for the new member. Discover IDs via GET /permission/groups (Owner/Administrator groups are rejected in sandbox mode). | |
| start_location_lat | No | Explicit day-start latitude in decimal degrees (-90..90); when set it wins over the address geocode. | |
| start_location_long | No | Explicit day-start longitude in decimal degrees (-180..180); when set it wins over the address geocode. | |
| start_location_type | No | Where the technician starts their day: home (their address) or office (the business location). Drives the engine's travel estimates. |