April 2026 - InstaView API

April 2, 2026

Job-Optional GENERIC Interviews: Interviews with a GENERIC agent focus can now be created without providing a jobId.
- POST /interviews — When the resolved agent has a GENERIC focus, the jobId field is no longer required. This allows flexible use cases such as general candidate conversations that are not tied to a specific position.
- For non-GENERIC focus types (SCREENING, OUTREACH, LANGUAGE_TEST, etc.), a jobId is still required. If the candidate has exactly one active job assignment and no jobId is specified, the system now auto-resolves it automatically.
- When a candidate has multiple job assignments and no jobId is provided, the request returns a clear error message guiding the caller to specify one.

Timezone-Aware Interview Scheduling: Interview scheduling and rescheduling now correctly respect ISO 8601 timezone offsets.
- When scheduledAt (on POST /interviews) or the reschedule timestamp includes an explicit UTC offset (e.g. 2026-04-02T07:00:00+10:30), that offset is now used directly for call time interval validation. Previously, the offset was silently discarded and the system fell back to phone-number-based timezone detection or the company default, which could place calls outside the intended local time window.
- Invalid date formats now return a descriptive 400 Bad Request error including the specific parsing failure reason.

Owner Onboarding via Email: ATS partners can now specify a customer owner email when creating or updating companies via the API.
- ownerEmail Support: Added an optional ownerEmail field to POST /v1/company and PATCH /v1/company/:id.
- Automated Invitations: If the provided email corresponds to an existing InstaView user, they are automatically assigned as the OWNER of the company. If the user does not exist, the system automatically triggers a Company Invitation email to that address.
- Visibility: The ownerEmail is now returned in company responses in GET and LIST requests, allowing partners to verify which user is linked to each company.

Public Call Attempt Management: Added support for managing individual call attempts for phone interviews via the Public API.
- POST /interviews/{id}/call-attempts — Manually invoke a new call attempt or schedule a retry for an existing interview.
- PATCH /interviews/{id}/call-attempts/{attemptId} — Reschedule a pending call attempt to a different time.
- DELETE /interviews/{id}/call-attempts/{attemptId} — Cancel and delete a scheduled call attempt.
- Constraints: These operations are available only for phone-based interviews. Individual call attempt management is blocked for ONLINE interviews to maintain consistency.
- Active Call Protection: To prevent race conditions, call attempts cannot be rescheduled or deleted once they have moved to the IN_PROGRESS state.

Credits Billing System Support in Public API: The Public Billing API now reports usage for both legacy minutes-based companies and new credits-based companies.
- GET /billing/usage response additions:
  - billingSystem (per company): Either "minutes" or "credits" — indicates which unit the company is billed in.
  - totalCreditsUsed (per company and aggregate): Total credits consumed in the selected period. Present for credits-based companies; omitted otherwise.
  - breakdownByCostKey[].creditsUsed: Per-cost-key credits total. Present only for credits-based companies.
- For minutes-based companies the response shape is unchanged — totalMinutesUsed and breakdownByCostKey[].minutesUsed continue to be the source of truth.

Delete Company Endpoint: Added support for deleting companies via the Public API.
- DELETE /company/{id} — Permanently deletes a specific company by ID.
- Access Rules: Regular API keys can only delete their associated company. ATS integration keys can delete any child company they’ve created.
- Cascade Deletion: This is a destructive operation that will delete all related entities (jobs, candidates, interviews) for the specified company.