> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.

# Export Contact Data

> Returns everything held about one contact in the API key's company, as one JSON document: the contact's core and custom fields, its documents with download links, the text of its processed CVs, and every conversation with its call attempts, transcripts, recording links, analysis, analytics, question-level analyses and post-call checks.

Meant for answering a data subject access request. Needs both `read:contacts` and `read:conversations`. The download and recording links in the export are signed and valid until one hour after `exportedAt`.

Returns the personal data we hold about one contact as a single JSON document. Use it to answer
a data subject access request: the person asked what you know about them, and this is the
machine-readable answer. A few kinds of record are deliberately left out, such as deleted records
and internal archives; see [What is not in the export](#what-is-not-in-the-export).

The API key needs both `read:contacts` and `read:conversations`: the export hands over every
conversation's transcripts, recordings and analyses, which the conversation routes keep behind
`read:conversations`. The same export is available in the app: open the
contact and choose **Export data**.

## What the export contains

| Field | What it holds |
| - | - |
| `formatVersion` | Version of this format, currently `"1"` |
| `exportedAt` | When the export was made (UTC). The links in the export are valid until one hour after it |
| `contact` | The contact as [Get Contact](https://docs.instaview.sk/api-reference/contacts/get-contact.md) returns it: core fields, `metadata` and custom `fields` |
| `retiredFields` | Values of custom fields that have since been deleted from your catalog. `contact.fields` hides them; they are still stored |
| `documents` | The contact's documents as [List Documents](https://docs.instaview.sk/api-reference/contacts/documents/list-documents.md) returns them, each with a `downloadUrl` |
| `cvs` | Every CV processed for the contact: the text read from it, its anonymized version, and the contact details found in it |
| `conversations` | Every conversation, oldest first, as [Get Conversation](https://docs.instaview.sk/api-reference/conversations/get-conversation.md) returns it |
| `conversationTranscripts` | Transcript segments of an online conversation, which belong to no call attempt |
| `questionAnalyses` | Each question the analysis found in the contact's calls, with a summary of the answer |
| `callChecks` | What the post-call check concluded about each call: interest, a callback request or an agreed `scheduledCallback`, whether the call was completed |

Each conversation carries its call attempts, and each call attempt its transcript and a
`recordingUrl`. The conversation's `analysis` holds the AI evaluation (strengths, weaknesses,
overall evaluation) and, for a custom agent, `analytics` holds its summary, extractions and
scoring.

### Links

`recordingUrl`, `videoRecordingUrl` and `downloadUrl` are signed links, valid until **one hour
after `exportedAt`**. Download the files you need to hand over within that hour, or request a new
export. A `downloadUrl` is `null` for a document whose file was never uploaded, and for the
processed CV: its file is not kept after processing, and its text is in `cvs`.

### Format version

`formatVersion` changes when a field is removed or changes meaning. Adding a field does not
change it, so read the fields you know and ignore the rest.

## Example

```json theme={null}
{
  "formatVersion": "1",
  "exportedAt": "2026-11-17T10:30:00.000Z",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "Jana",
    "lastName": "Nováková",
    "email": "jana.novakova@example.com",
    "phoneNumber": "+421915123456",
    "status": "APPLIED",
    "metadata": { "externalId": "CAND-12345" },
    "fields": { "shoe_size": "38" }
  },
  "retiredFields": {},
  "documents": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "CV",
      "source": "CV",
      "status": "READY",
      "downloadUrl": "https://storage.example.com/...&X-Amz-Signature=..."
    }
  ],
  "conversations": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "COMPLETED",
      "callAttempts": [
        {
          "id": "c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a",
          "status": "COMPLETED",
          "recordingUrl": "https://storage.example.com/...&X-Amz-Signature=...",
          "transcript": [{ "speaker": "AI", "text": "Dobrý deň, volám z ...", "startTime": 0, "endTime": 2.4 }]
        }
      ],
      "analysis": { "general": { "strongPoints": ["Five years of warehouse experience"] } }
    }
  ],
  "questionAnalyses": [
    {
      "conversationId": "123e4567-e89b-12d3-a456-426614174000",
      "callAttemptId": "c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a",
      "question": "How many years have you worked in a warehouse?",
      "summary": "Five years, the last two as shift lead.",
      "wasAnswered": true
    }
  ],
  "callChecks": [
    {
      "conversationId": "123e4567-e89b-12d3-a456-426614174000",
      "callAttemptId": "c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a",
      "contactInterested": true,
      "reschedulingRequested": false,
      "conversationCompleted": true
    }
  ]
}
```

The example is shortened. The full shape of each section is in the response schema below.

## What is not in the export

* **Deleted records.** A conversation or contact you deleted is not exported. It is removed for
  good when its retention period ends.
* **Deletion archives.** When a contact or a conversation is deleted, a snapshot of the record
  (name, e-mail, phone number) is kept in an internal archive for the configured retention period
  (30 days by default) and then removed. The archive is not reachable through the API, so it is
  not in the export. A contact that is still live has nothing in it.
* **Internal operational data.** Billing reservations, call costs, provider call ids and
  similar records are about the call, not the person, and are left out.

## Error Scenarios

* **403 Forbidden**: the API key lacks `read:contacts` or `read:conversations`.
* **404 Not Found**: no contact with that id belongs to your API key's company. An id that
  exists nowhere and an id that belongs to another company answer identically, on purpose.

## Related Resources

> [card] [Erase Contacts by Identifier](https://docs.instaview.sk/api-reference/contacts/erase-contacts.md)
>
> Act on an erasure request

> [card] [Contacts Resource Guide](https://docs.instaview.sk/guides/resources/contacts.md)
>
> Learn about managing contacts


## OpenAPI

````yaml GET /contacts/{id}/data-export
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /contacts/{id}/data-export:
    get:
      tags:
        - Contacts
      summary: Export all data about a contact
      description: >-
        Returns everything held about one contact in the API key's company, as
        one JSON document: the contact's core and custom fields, its documents
        with download links, the text of its processed CVs, and every
        conversation with its call attempts, transcripts, recording links,
        analysis, analytics, question-level analyses and post-call checks.


        Meant for answering a data subject access request. Needs both
        `read:contacts` and `read:conversations`. The download and recording
        links in the export are signed and valid until one hour after
        `exportedAt`.
      operationId: PublicContactDataExportController_exportContactData_v1
      parameters:
        - name: id
          required: true
          in: path
          description: Contact to export.
          schema:
            type: string
            format: uuid
        - name: companyId
          required: false
          in: query
          description: >-
            Required for ATS API keys to specify which company to access.
            Ignored for standard company API keys.
          schema:
            type: string
      responses:
        '200':
          description: Everything held about the contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicContactDataExportDto'
        '403':
          description: The API key lacks `read:contacts` or `read:conversations`.
        '404':
          description: >-
            No contact with that id belongs to the API key's company. An id that
            exists nowhere and an id that belongs to another company answer
            identically, on purpose.
      security:
        - bearer: []
components:
  schemas:
    PublicContactDataExportDto:
      type: object
      properties:
        formatVersion:
          type: string
          example: '1'
          description: >-
            Version of this export's format. Raised when a field is removed or
            changes meaning; adding a field does not raise it.
        exportedAt:
          type: string
          format: date-time
          example: '2026-11-17T10:30:00.000Z'
          description: When the export was made (UTC)
        contact:
          description: >-
            The contact as `GET /contacts/{id}` returns it, with its core fields
            and custom `fields`.
          allOf:
            - $ref: '#/components/schemas/PublicCandidateDto'
        retiredFields:
          type: object
          additionalProperties: true
          example:
            old_referral_code: REF-2291
          description: >-
            Custom field values still stored for the contact whose field has
            since been deleted from the company's catalog. `contact.fields`
            leaves them out, as `GET /contacts/{id}` does; they are personal
            data all the same. Empty object when there are none.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/PublicExportDocumentDto'
          description: >-
            The contact's documents as `GET /contacts/{id}/documents` lists
            them, each with a link to download its file.
        cvs:
          type: array
          items:
            $ref: '#/components/schemas/PublicExportCvDto'
          description: >-
            Every CV processed for the contact, newest first, with the text read
            from it. The original file is not kept after processing, so the text
            is what is held.
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/PublicInterviewDto'
          description: >-
            Every conversation with the contact, oldest first, as `GET
            /conversations/{id}` returns it: call attempts with their
            transcripts and recording links, the analysis and, for a custom
            agent, its analytics. Recording links are signed and valid until one
            hour after `exportedAt`.
        conversationTranscripts:
          type: array
          items:
            $ref: '#/components/schemas/PublicExportConversationTranscriptDto'
          description: >-
            Transcript segments that belong to no call attempt, as an online
            conversation records them, grouped by conversation. `conversations`
            carries transcripts per call attempt only.
        questionAnalyses:
          type: array
          items:
            $ref: '#/components/schemas/PublicExportQuestionAnalysisDto'
          description: >-
            The questions the analysis found in the contact's calls, with a
            summary of each answer.
        callChecks:
          type: array
          items:
            $ref: '#/components/schemas/PublicExportCallCheckDto'
          description: What the post-call check concluded about each call attempt.
      required:
        - formatVersion
        - exportedAt
        - contact
        - retiredFields
        - documents
        - cvs
        - conversations
        - conversationTranscripts
        - questionAnalyses
        - callChecks
    PublicCandidateDto:
      type: object
      properties:
        id:
          type: string
          description: Contact ID
          example: 123e4567-e89b-12d3-a456-426614174000
        jobId:
          type: string
          description: '[Deprecated] Single job ID; use jobIds instead.'
          deprecated: true
          example: 987e6543-e21b-12d3-a456-426614174000
        jobIds:
          type: array
          description: Jobs the contact is assigned to.
          items:
            type: string
            format: uuid
          uniqueItems: true
          maxItems: 50
        firstName:
          type: string
          description: The contact's first name
          example: John
        lastName:
          type: string
          description: The contact's last name
          example: Doe
        email:
          type: string
          description: The contact's email address
          example: john.doe@example.com
        phoneNumber:
          type: string
          description: The contact's phone number
          example: '+421915123456'
        status:
          type: string
          description: Contact status
          enum:
            - UNDEFINED
            - APPLIED
            - IN_PROCESS
            - REJECTED
            - ACCEPTED
          example: APPLIED
        gdprExpiryDate:
          type: string
          description: >-
            GDPR expiry date. Currently returned as a date (no time). NOTE: We
            plan to migrate to a timestamp with timezone (timestamptz) for
            global correctness.
          example: '2026-11-16'
          format: date
        overallRating:
          type: number
          description: Overall rating/match score (0-100)
          example: 85
          minimum: 0
          maximum: 100
        metadata:
          type: object
          description: >-
            Your own scratch space on the contact: free-form, unvalidated, and
            never read by an agent. Replaced wholesale on update. Not the place
            for values you want an agent to say — those are `fields`.
          example:
            source: LinkedIn
            externalId: CAND-12345
        fields:
          type: object
          description: >-
            The contact's catalogued field values, keyed by field key — the
            counterpart of `metadata`, and the only half an agent can speak.
            Each key is defined in the company catalog (`GET /contact-fields`)
            and addressable in a flow as `{{contact.<key>}}`. Written through
            `fields` on `POST /contacts` and `PATCH /contacts/{id}`, never
            through `metadata`. A field with no value is absent rather than
            null; `{}` means none are set.
          example:
            order_number: SO-40128
            is_vip: true
            renewal_date: '2026-04-01'
          additionalProperties: true
        createdAt:
          type: string
          description: Created timestamp (UTC)
          example: '2025-11-20T10:30:00Z'
          format: date-time
        updatedAt:
          type: string
          description: Updated timestamp (UTC)
          example: '2025-11-20T10:30:00Z'
          format: date-time
        analysisCount:
          type: number
          description: >-
            Number of analyses for this contact. Not currently populated by any
            endpoint — treat as absent.
          example: 2
        interviewCount:
          type: number
          description: >-
            Number of conversations for this contact. Keeps its original field
            name, and is not currently populated by any endpoint — treat as
            absent.
          example: 3
        links:
          type: object
          description: >-
            Convenience links to related collections. Endpoints may be added
            incrementally.
          example:
            analyses: /v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/analyses
            interviews: >-
              /v1/public/contacts/123e4567-e89b-12d3-a456-426614174000/conversations
        gender:
          type: string
          description: >-
            The contact's gender. Used for gender-aware addressing on the call.
            Null if not explicitly set (auto-detected from the name).
          enum:
            - male
            - female
          nullable: true
          example: female
        anonymizedCvText:
          type: string
          description: The contact's anonymized CV in plain text.
          example: |-
            [NAME]
            Software Engineer
            Experience: ...
        workHistory:
          type: array
          description: Work history items for the contact.
          maxItems: 20
          items:
            $ref: '#/components/schemas/PublicCandidateWorkHistoryItemDto'
      required:
        - id
        - firstName
        - lastName
        - status
        - fields
        - createdAt
        - updatedAt
    PublicExportDocumentDto:
      description: >-
        A document as `PublicKnowledgeDocumentDto` describes it, with a link to
        its file.
      allOf:
        - $ref: '#/components/schemas/PublicKnowledgeDocumentDto'
        - type: object
          properties:
            downloadUrl:
              type: string
              nullable: true
              example: >-
                https://storage.example.com/contact-documents/cv.pdf?X-Amz-Signature=...
              description: >-
                Signed link that downloads the file, valid until one hour after
                `exportedAt`. Null when no file is stored: an upload that was
                never completed, or the processed CV, whose content is in `cvs`.
          required:
            - downloadUrl
    PublicExportCvDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d
          description: CV processing ID
        originalFilename:
          type: string
          example: jana-novakova-cv.pdf
          description: Name of the file as uploaded
        fileType:
          type: string
          example: PDF
          description: Type of the uploaded file
        fileSizeBytes:
          type: number
          example: 182044
          description: Size of the uploaded file in bytes
        extractedText:
          type: string
          nullable: true
          example: |-
            Jana Nováková
            Warehouse shift lead
            ...
          description: Text read from the file. Null when extraction did not complete.
        anonymizedText:
          type: string
          nullable: true
          example: |-
            [NAME]
            Warehouse shift lead
            ...
          description: >-
            The text with personal details replaced by placeholders, as the
            agent reads it. Null when anonymization did not complete.
        extractedContact:
          type: object
          nullable: true
          properties:
            name:
              type: string
              nullable: true
            surname:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
            phone:
              type: string
              nullable: true
          example:
            name: Jana
            surname: Nováková
            email: jana.novakova@example.com
            phone: '+421915123456'
          description: Contact details read from the CV. Null when none were extracted.
        createdAt:
          type: string
          format: date-time
          example: '2026-11-02T09:12:00.000Z'
          description: When the CV was uploaded (UTC)
      required:
        - id
        - originalFilename
        - fileType
        - fileSizeBytes
        - extractedText
        - anonymizedText
        - extractedContact
        - createdAt
    PublicInterviewDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Conversation ID
          example: 123e4567-e89b-12d3-a456-426614174000
        contactId:
          type: string
          format: uuid
          description: Contact ID
          example: 987e6543-e21b-12d3-a456-426614174000
        candidateId:
          type: string
          format: uuid
          description: >-
            Deprecated alias of `contactId`, always identical to it. Kept for
            the life of v1 so existing integrations keep working; new callers
            should read `contactId`.
          example: 987e6543-e21b-12d3-a456-426614174000
          deprecated: true
        agentId:
          type: string
          description: Agent ID
          format: uuid
          example: 456e7890-e12b-34d5-a678-901234567890
        jobId:
          type: string
          description: Job ID associated with this conversation, if any
          format: uuid
          nullable: true
          example: 123e4567-e89b-12d3-a456-426614174000
        runId:
          type: string
          description: >-
            The run that produced this conversation, or `null` for one created
            on its own. A run mints one conversation per contact, so this is how
            a conversation is traced back to the batch it came from without
            listing the run.
          format: uuid
          nullable: true
          example: 789e0123-e45b-67d8-a901-234567890123
        flowVersion:
          type: string
          description: >-
            Identity of the agent configuration (flow, guardrails and context,
            as compiled) that the most recent call in this conversation was
            placed with. A content hash: two calls that ran the same
            configuration carry the same value, and any edit that changes what
            the agent says produces a new one. Each entry in `callAttempts`
            carries its own, since a retry placed after an edit runs the edited
            configuration. `null` for agents without a designed flow and for
            calls placed before 2026-09-23.
          nullable: true
          pattern: ^[0-9a-f]{64}$
          example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
        status:
          type: string
          description: Conversation status
          enum:
            - UNDEFINED
            - SCHEDULED
            - CANCELLED
            - FAILED
            - COMPLETED
            - IN_PROGRESS
            - UNREACHABLE
          example: SCHEDULED
        result:
          type: string
          description: >-
            How the conversation actually ended, from a fixed list. Set when
            `status` is `COMPLETED`, or `FAILED` because the analysis failed;
            `null` for every other status, including a `FAILED` conversation
            that failed for another reason. Once `status` is final in that way:
            a voicemail, a call under 20 seconds, or a call whose analysis
            failure is already recorded gets its result straight away; any other
            call gets it once the analysis or analytics of the call that closed
            the conversation is stored and is the one the conversation
            publishes, and keeps `null` if that never happens. `COMPLETED`: a
            conversation happened and the analysis or analytics captured at
            least the contact's interest or one answer. `PARTIAL`: the call
            captured the contact's interest or at least one answer, then ended
            early. `NO_CONVERSATION`: the call connected but nothing usable was
            said. `FAILED`: a conversation happened but its analysis failed.
            `status` itself is unchanged.
          enum:
            - COMPLETED
            - PARTIAL
            - NO_CONVERSATION
            - FAILED
            - null
          example: PARTIAL
          nullable: true
        resultReason:
          type: string
          description: >-
            Why `result` is not `COMPLETED`, from a fixed list. `null` when
            `result` is `COMPLETED` or `null`. `PARTIAL`: `MAX_DURATION`,
            `HUNG_UP_MIDWAY`, `CONNECTION_DROPPED`. `NO_CONVERSATION`:
            `HUNG_UP_EARLY`, `VOICEMAIL`, `NO_SPEECH`, and `MAX_DURATION` or
            `CONNECTION_DROPPED` when the call was cut before anything usable
            was said. `FAILED`: `ANALYSIS_ERROR`.
          enum:
            - HUNG_UP_EARLY
            - VOICEMAIL
            - NO_SPEECH
            - MAX_DURATION
            - HUNG_UP_MIDWAY
            - CONNECTION_DROPPED
            - ANALYSIS_ERROR
            - null
          example: MAX_DURATION
          nullable: true
        scheduledAt:
          type: string
          format: date-time
          description: Scheduled time
          example: '2025-11-20T10:00:00Z'
        durationMinutes:
          type: number
          description: Conversation duration in minutes
          example: 15
        finishedDate:
          type: string
          format: date-time
          description: Finished date
          example: '2025-11-20T10:15:00Z'
        metadata:
          type: object
          description: Custom metadata
          example:
            externalInterviewId: INT-789
        callAttempts:
          description: >-
            Call attempt logs for this conversation. Present for PHONE
            conversations, typically empty or undefined for ONLINE ones.
          type: array
          items:
            $ref: '#/components/schemas/PublicCallAttemptDto'
        analysis:
          description: >-
            Conversation analysis data. Present only if analysis has been
            generated.
          allOf:
            - $ref: '#/components/schemas/PublicConversationAnalysisDto'
        analytics:
          allOf:
            - $ref: '#/components/schemas/ConversationAnalytics'
          description: >-
            What the agent's own analytics configuration produced on this call:
            extracted fields, match score, outcomes and tags. Present only for a
            custom agent whose after-call analysis has run.
        createdAt:
          type: string
          description: Created timestamp
          example: '2024-11-16T10:30:00Z'
        updatedAt:
          type: string
          description: Updated timestamp
          example: '2024-11-16T10:30:00Z'
        isTest:
          type: boolean
          description: >-
            Whether this is a test conversation. A test conversation is created
            with isTest=true, completes immediately without consuming billing
            minutes, and is excluded from billing and usage summaries. Use them
            to exercise webhook handlers and integration flows.
          example: false
      required:
        - id
        - contactId
        - candidateId
        - agentId
        - status
        - result
        - resultReason
        - scheduledAt
        - createdAt
        - updatedAt
    PublicExportConversationTranscriptDto:
      type: object
      properties:
        conversationId:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Conversation the segments belong to
        transcript:
          type: array
          items:
            $ref: '#/components/schemas/PublicTranscriptSegmentDto'
          description: The segments, in spoken order
      required:
        - conversationId
        - transcript
    PublicExportQuestionAnalysisDto:
      type: object
      properties:
        conversationId:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Conversation the question was asked in
        callAttemptId:
          type: string
          format: uuid
          nullable: true
          example: c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a
          description: >-
            Call attempt the question was asked in. Null for an online
            conversation.
        order:
          type: number
          example: 0
          description: Position of the question in the conversation, from 0
        question:
          type: string
          example: How many years have you worked as a forklift driver?
          description: The question as asked
        questionType:
          type: string
          enum:
            - AI_TO_CANDIDATE
            - CANDIDATE_TO_AI
            - CANDIDATE_TO_HUMAN
            - HUMAN_TO_CANDIDATE
          example: AI_TO_CANDIDATE
          description: Who asked whom
        category:
          type: string
          example: EXPERIENCE
          description: Topic of the question
        wasAnswered:
          type: boolean
          example: true
          description: Whether the question was answered
        yesNoAnswer:
          type: boolean
          nullable: true
          example: null
          description: >-
            The answer to a yes/no question. Null when the question was not a
            yes/no question.
        summary:
          type: string
          example: Five years, the last two as shift lead.
          description: Summary of the answer
        relevanceScore:
          type: number
          example: 0.9
          description: How relevant the answer was to the question, 0 to 1
        timestampSeconds:
          type: number
          nullable: true
          example: 42
          description: Second of the call the question was asked at. Null when unknown.
      required:
        - conversationId
        - callAttemptId
        - order
        - question
        - questionType
        - category
        - wasAnswered
        - yesNoAnswer
        - summary
        - relevanceScore
        - timestampSeconds
    PublicExportCallCheckDto:
      type: object
      properties:
        conversationId:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Conversation the call belongs to
        callAttemptId:
          type: string
          format: uuid
          example: c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a
          description: Call attempt that was checked
        contactInterested:
          type: boolean
          example: true
          description: Whether the contact was judged interested
        reschedulingRequested:
          type: boolean
          example: false
          description: Whether the contact asked to be called back another time
        conversationCompleted:
          type: boolean
          example: true
          description: Whether the conversation reached its end
        rescheduleTimeInfo:
          type: object
          nullable: true
          example:
            type: absolute_time
            timeOfDay: '14:00'
          description: >-
            When the contact asked to be called back, as understood from the
            call. Null when they did not.
        scheduledCallback:
          type: object
          nullable: true
          example:
            type: absolute_time
            timeOfDay: '14:00'
          description: >-
            The callback the contact agreed to, when the agent scheduled one.
            Once a callback is agreed it is stored here and `rescheduleTimeInfo`
            is cleared. Null when none was scheduled.
        createdAt:
          type: string
          format: date-time
          example: '2026-11-17T10:16:00.000Z'
          description: When the check was made (UTC)
      required:
        - conversationId
        - callAttemptId
        - contactInterested
        - reschedulingRequested
        - conversationCompleted
        - rescheduleTimeInfo
        - scheduledCallback
        - createdAt
    PublicCandidateWorkHistoryItemDto:
      type: object
      properties:
        id:
          type: string
          description: Work history item ID
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        companyName:
          type: string
          description: Name of the employer company
          example: Google
          minLength: 1
          maxLength: 255
        candidatePosition:
          type: string
          description: >-
            The role held at that company. Keeps its original field name, which
            is the name the API accepts.
          example: Software Engineer
          minLength: 1
          maxLength: 255
        referenceName:
          type: string
          description: Name of the reference person
          example: Jane Smith
          maxLength: 255
        referencePhone:
          type: string
          description: Phone number of reference contact in E.164 format
          example: '+1987654321'
          pattern: ^\+[1-9]\d{1,14}$
        startDate:
          type: string
          description: Job start date in calendar format (yyyy-MM-dd)
          example: '2020-01-01'
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
        endDate:
          type: string
          description: Job end date in calendar format (yyyy-MM-dd)
          example: '2022-12-31'
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
      required:
        - companyName
        - candidatePosition
        - referencePhone
    PublicKnowledgeDocumentDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Document ID
        title:
          type: string
          example: Benefits and perks
          description: Human-readable label for the document
        fileName:
          type: string
          example: benefits-and-perks.pdf
          description: Original file name as uploaded
        mimeType:
          type: string
          example: application/pdf
          description: MIME type of the stored file
        sizeBytes:
          type: number
          example: 482133
          description: >-
            Size of the stored file in bytes, as verified against storage.
            Absent until the upload is READY.
        status:
          type: string
          enum:
            - PENDING
            - READY
          example: READY
          description: >-
            `PENDING` while waiting for the file to be uploaded to the presigned
            URL and the upload to be completed; `READY` once the file is
            confirmed stored. Only READY documents are attached to calls.
        isActive:
          type: boolean
          example: true
          description: >-
            Whether the agent may consult this document during a call. Always
            false while the upload is PENDING.
        source:
          type: string
          enum:
            - UPLOAD
            - CV
          example: UPLOAD
          description: >-
            `UPLOAD` for a file attached through the API or the dashboard. `CV`
            for the document the platform produces from a contact's processed CV
            (contacts only); a `CV` document can be deactivated but not renamed
            or deleted. Always `UPLOAD` on an agent's knowledge base.
        createdAt:
          format: date-time
          type: string
          example: '2026-08-08T10:15:00.000Z'
          description: When the document was created
      required:
        - id
        - title
        - status
        - isActive
        - source
        - createdAt
    PublicCallAttemptDto:
      type: object
      properties:
        id:
          type: string
          description: Call attempt ID
          example: c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a
        direction:
          type: string
          description: >-
            How the call was made: OUTBOUND (we dialled the candidate), INBOUND
            (the candidate called in) or ONLINE (a browser session on an online
            interview).
          enum:
            - UNDEFINED
            - INBOUND
            - OUTBOUND
            - ONLINE
          example: OUTBOUND
        status:
          type: string
          description: Current status of the call attempt
          enum:
            - UNDEFINED
            - SCHEDULED
            - IN_PROGRESS
            - COMPLETED
            - NO_ANSWER
            - BUSY
            - FAILED
            - CANCELLED
            - VOICEMAIL
            - REJECTED
            - NO_CONSENT
            - TIMEOUT
            - MAX_ATTEMPTS_REACHED
            - HUMAN_CONTACT_REQUESTED
            - OTHER_ROLE_INTEREST
            - POLITE_DECLINE
            - TIMING_ISSUE
          example: COMPLETED
        reasonCode:
          type: string
          description: Machine-readable reason code for failures or special outcomes
          example: NO_ANSWER
        notes:
          type: string
          description: Human-readable notes associated with this call attempt
          example: Candidate did not pick up, mailbox full
        retryNumber:
          type: number
          description: >-
            Retry number for this attempt (starting from 0 or 1 depending on
            implementation)
          example: 2
        recordingUrl:
          type: string
          description: URL to the call recording, if available
          example: https://audio.example.com/recording.mp3
        duration:
          type: number
          description: Duration of the call attempt in seconds
          example: 180
        scheduledAt:
          type: string
          format: date-time
          description: Scheduled time for this call attempt (ISO 8601, UTC)
          example: '2025-07-22T10:00:00Z'
        calledAt:
          type: string
          format: date-time
          description: Actual time when the call started (ISO 8601, UTC)
          example: '2025-07-22T10:01:00Z'
        transcript:
          description: >-
            Transcript segments for this call attempt, ordered chronologically.
            Each segment contains the speaker, text content, and timing. Omitted
            when the conversation has no transcript or the call attempt did not
            produce one.
          type: array
          items:
            $ref: '#/components/schemas/PublicTranscriptSegmentDto'
        flowVersion:
          type: string
          description: >-
            Identity of the agent configuration this call was placed with; see
            `flowVersion` on the conversation. `null` for agents without a
            designed flow, for inbound calls, for online (browser) calls, whose
            version is recorded on the conversation only, and for calls placed
            before 2026-09-23.
          nullable: true
          pattern: ^[0-9a-f]{64}$
          example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
      required:
        - id
        - direction
    PublicConversationAnalysisDto:
      type: object
      properties:
        id:
          type: string
          description: Analysis ID
          example: 123e4567-e89b-12d3-a456-426614174000
        general:
          description: General analysis data
          allOf:
            - $ref: '#/components/schemas/PublicGeneralAnalysisDto'
        specific:
          type: object
          description: >-
            Specific analysis data, depending on the agent's focus (e.g.
            language test scores, outreach feedback)
          example:
            pronunciationScores:
              accuracy: 90
              fluency: 85
              prosody: 82
            grammar:
              level: C1
        audit:
          allOf:
            - $ref: '#/components/schemas/AnalysisAudit'
          description: >-
            How each result was produced: per analysis, our name for the model,
            the version of its instructions and when it ran. Absent on results
            analysed before the audit trail shipped in November 2026.
      required:
        - id
        - general
    ConversationAnalytics:
      type: object
      description: >-
        What the agent's own `analyticsConfig` produced on this call. Present
        only for a custom agent whose after-call analysis has run. Distinct from
        `analysis`, which is the recruiting pipeline's output.


        Each slice is written by its own after-call job and each job self-gates
        on the agent's config, so an absent field means “not configured, or not
        run yet”.
      required:
        - matchScore
        - updatedAt
      properties:
        matchScore:
          type: number
          description: The weighted overall match score. Null until scoring has run.
          nullable: true
          minimum: 0
          maximum: 100
          example: 72
        fields:
          type: array
          description: The agent's extraction targets, resolved against this call.
          items:
            $ref: '#/components/schemas/AnalyticsFieldResult'
        scoring:
          allOf:
            - $ref: '#/components/schemas/AnalyticsScoring'
          description: How the match score was made up.
        outcomes:
          type: array
          description: The agent's outcomes, decided for this call.
          items:
            $ref: '#/components/schemas/AnalyticsOutcomeResult'
        tags:
          type: array
          description: The agent's output tags, assigned or not.
          items:
            $ref: '#/components/schemas/AnalyticsTagResult'
        qa:
          type: array
          description: The flow's looping questions, answered from the transcript.
          items:
            $ref: '#/components/schemas/AnalyticsQaEntry'
        evaluation:
          allOf:
            - $ref: '#/components/schemas/AnalyticsEvaluation'
          description: Purpose-driven evaluation of the call.
        sentiment:
          allOf:
            - $ref: '#/components/schemas/AnalyticsSentiment'
          description: Overall tone of the call.
        summary:
          type: string
          description: Generic call summary.
          example: Qualified lead; demo booked for Thursday.
        audit:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAudit'
          description: >-
            Which model and which version of the instructions produced each
            result above, and when. Absent on results analysed before November
            17, 2026.
        updatedAt:
          type: string
          format: date-time
          description: When these analytics were last written (UTC).
          example: '2026-08-03T10:30:00Z'
    PublicTranscriptSegmentDto:
      type: object
      description: >-
        A single segment of a call attempt transcript: one utterance, by either
        the agent or the contact.
      properties:
        speaker:
          type: string
          description: Who spoke this segment
          enum:
            - AI
            - HUMAN
          example: AI
        text:
          type: string
          description: Transcribed text of the utterance
          example: Hello, thank you for taking the time to speak with me today.
        startTime:
          type: number
          description: Start time of the segment in seconds from the start of the recording
          example: 0
          minimum: 0
        endTime:
          type: number
          description: End time of the segment in seconds from the start of the recording
          example: 3.5
          minimum: 0
        language:
          type: string
          description: BCP-47 language code detected for this segment (e.g. 'en', 'sk')
          example: en
          pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$
      required:
        - speaker
        - text
        - startTime
        - endTime
    PublicGeneralAnalysisDto:
      type: object
      properties:
        overallRating:
          type: number
          nullable: true
          description: >-
            Overall rating (0-100). Null when scoring did not complete — see
            scoringIncompleteReason. A null rating is never a low one: it means
            no score was produced, not that the candidate scored badly.
          example: 85
        scoringIncompleteReason:
          type: string
          description: >-
            Why no overall rating was produced. Absent on a complete analysis.
            'model_unavailable' means the scoring model could not be reached and
            the analysis is queued to be re-run; 'model_error' means it answered
            unusably and the analysis will not be retried on its own.
          enum:
            - model_unavailable
            - model_error
          example: model_unavailable
        companyFitRating:
          type: string
          description: Company fit rating
          enum:
            - UNDEFINED
            - LOW
            - MEDIUM
            - HIGH
          example: HIGH
        education:
          type: string
          description: Summary of education analysis
          example: Master's degree in Computer Science
        experience:
          type: string
          description: Summary of experience analysis
          example: 5 years of experience in software development
        strongPoints:
          description: Strong points and advantages found in the call
          example:
            - Excellent communication skills
            - Strong technical expertise in React and Node.js
            - Proven track record of leading teams
          type: array
          items:
            type: string
        weakPoints:
          description: Weak points, or areas for improvement, found in the call
          example:
            - Limited experience with microservices
            - Needs improvement in system design
          type: array
          items:
            type: string
        evaluation:
          description: Overall evaluation summary and recommendations
          example:
            - Strong candidate with relevant experience
            - Good cultural fit for the team
            - Recommended for next round
          type: array
          items:
            type: string
        status:
          type: number
          description: Analysis processing status
          enum:
            - 1
            - 2
            - 3
            - 4
          example: 3
        createdAt:
          type: string
          description: Created timestamp (UTC)
          example: '2024-11-16T10:30:00Z'
          format: date-time
        updatedAt:
          type: string
          description: Updated timestamp (UTC)
          example: '2024-11-16T10:30:00Z'
          format: date-time
      required:
        - createdAt
        - updatedAt
    AnalysisAudit:
      type: object
      description: >-
        The audit trail of a conversation's analysis: one entry per analysis
        that called a model, keyed by analysis. Analyses that did not run on the
        conversation have no entry.
      properties:
        conversationCheck:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: >-
            Audit entry for the conversation check: whether the call was
            completed, the contact's interest and any callback they asked for.
          example:
            model: instaview-analysis-1
            promptVersion: hr-conversation-check-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        prosCons:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: >-
            Audit entry for `general.strongPoints`, `general.weakPoints` and
            `general.evaluation`.
          example:
            model: instaview-analysis-1
            promptVersion: hr-pros-cons-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        skillExtraction:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for the skills the contact described on the call.
          example:
            model: instaview-analysis-1
            promptVersion: hr-skills-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        skillMatching:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: >-
            Audit entry for matching those skills against the job's
            requirements.
          example:
            model: instaview-analysis-1
            promptVersion: hr-skills-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        questionAnalysis:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for the questions asked and answered on the call.
          example:
            model: instaview-analysis-1
            promptVersion: hr-question-analysis-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        matchScore:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `general.overallRating` and the scores behind it.
          example:
            model: instaview-analysis-1
            promptVersion: hr-match-score-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        companyFit:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `general.companyFitRating`.
          example:
            model: instaview-analysis-1
            promptVersion: hr-company-fit-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        grammarVocab:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: >-
            Audit entry for the grammar and vocabulary levels of a language
            test.
          example:
            model: instaview-analysis-1
            promptVersion: hr-grammar-vocab-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        pronunciationCefr:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for the pronunciation level of a language test.
          example:
            model: instaview-analysis-1
            promptVersion: hr-pronunciation-cefr-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
        combinedCefr:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for the overall CEFR level of a language test.
          example:
            model: instaview-analysis-1
            promptVersion: hr-combined-cefr-v1
            analyzedAt: '2026-11-17T10:30:00.000Z'
    AnalyticsFieldResult:
      type: object
      description: One extraction target, resolved against the call.
      required:
        - key
        - label
        - type
        - value
      properties:
        key:
          type: string
          description: The key configured on the agent.
          example: budget_confirmed
        label:
          type: string
          example: Budget confirmed
        type:
          type: string
          enum:
            - string
            - number
            - bool
            - enum
        value:
          description: >-
            The extracted value, coerced to `type`. `null` when the call did not
            surface it — which is distinct from a `false` or empty value that
            WAS surfaced.
          anyOf:
            - type: string
              nullable: true
            - type: number
              nullable: true
            - type: boolean
              nullable: true
          example: true
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Model confidence, 0..1.
        evidence:
          type: string
          description: Short transcript-grounded justification.
          example: Said they have signed off on 15k for this quarter
    AnalyticsScoring:
      type: object
      description: The overall match score and what made it up.
      required:
        - total
        - items
      properties:
        total:
          type: number
          minimum: 0
          maximum: 100
          description: The weighted overall match score.
          example: 72
        items:
          type: array
          description: One entry per scored item.
          items:
            $ref: '#/components/schemas/AnalyticsScoreItem'
    AnalyticsOutcomeResult:
      type: object
      description: One of the agent's outcomes, decided for this call.
      required:
        - key
        - label
        - met
      properties:
        key:
          type: string
          description: The key configured on the agent.
          example: meeting_booked
        label:
          type: string
          example: Meeting booked
        met:
          type: boolean
          description: Whether the call achieved it.
          example: true
        confidence:
          type: number
          minimum: 0
          maximum: 1
        evidence:
          type: string
          description: Short transcript-grounded justification.
    AnalyticsTagResult:
      type: object
      description: One of the agent's output tags, assigned or not.
      required:
        - key
        - label
        - applied
      properties:
        key:
          type: string
          description: The key configured on the agent.
          example: needs_followup
        label:
          type: string
          example: Needs follow-up
        applied:
          type: boolean
          description: Whether the AI applied it to this call.
          example: true
        reason:
          type: string
          description: Why.
    AnalyticsQaEntry:
      type: object
      description: One of the flow's looping questions, answered from the transcript.
      required:
        - id
        - question
        - answered
        - answer
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Id of the flow's looping question — the same id the agent read
            returns.
        question:
          type: string
          description: The question, as designed.
        asked:
          type: boolean
          description: >-
            Whether the question came up on the call at all: the agent asked it,
            or the contact answered it unprompted. `asked: true, answered:
            false` is a question that was asked but got no clear answer. Absent
            on results analysed before this field existed, unless `answered` is
            true.
          example: true
        answered:
          type: boolean
          description: >-
            Whether the call actually covered it. Distinguishes “not discussed”
            from an empty answer.
          example: true
        answer:
          type: string
          description: The answer as given on the call; empty when not answered.
        evidence:
          type: string
          description: Short transcript-grounded justification.
    AnalyticsEvaluation:
      type: object
      description: >-
        Purpose-driven evaluation of the call, driven by the agent's design
        rather than a job spec.
      required:
        - strengths
        - concerns
        - objections
        - assessment
      properties:
        strengths:
          type: array
          description: What went well.
          items:
            type: string
        concerns:
          type: array
          description: What went poorly, and the risks.
          items:
            type: string
        objections:
          type: array
          description: Objections or hesitations the contact raised.
          items:
            type: string
        assessment:
          type: array
          description: Overall assessment, a few holistic lines.
          items:
            type: string
    AnalyticsSentiment:
      type: object
      description: Overall tone of the call and how it moved.
      required:
        - overall
      properties:
        overall:
          type: string
          enum:
            - positive
            - neutral
            - negative
          example: positive
        score:
          type: number
          minimum: 0
          maximum: 1
          description: 0 (very negative) .. 1 (very positive).
        trajectory:
          type: string
          enum:
            - improving
            - declining
            - steady
            - mixed
        notes:
          type: string
          description: One-line note explaining the read.
    AnalyticsAudit:
      type: object
      description: >-
        The audit trail of a conversation's analytics: one entry per result that
        has been produced, keyed by the result it describes.
      properties:
        fields:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `fields`.
        scoring:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `scoring`.
        outcomes:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `outcomes`.
        tags:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `tags`.
        qa:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `qa`.
        evaluation:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `evaluation`.
        sentiment:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `sentiment`.
        summary:
          allOf:
            - $ref: '#/components/schemas/AnalyticsAuditEntry'
          description: Audit entry for `summary`.
    AnalyticsAuditEntry:
      type: object
      description: >-
        Which model and which version of the instructions produced one result,
        and when.
      required:
        - model
        - promptVersion
        - analyzedAt
      properties:
        model:
          type: string
          description: >-
            Our name for the model that produced this result. It changes
            whenever the model does.
          example: instaview-analysis-1
        promptVersion:
          type: string
          description: >-
            The version of the instructions the model was given. It changes
            whenever those instructions change.
          example: custom-scoring-v1
        analyzedAt:
          type: string
          format: date-time
          description: When this result was produced (UTC).
          example: '2026-11-17T10:30:00.000Z'
    AnalyticsScoreItem:
      type: object
      description: One item contributing to the match score.
      required:
        - key
        - kind
        - label
        - score
      properties:
        key:
          type: string
          description: >-
            The extraction target's or criterion's key, or the flow question's
            id.
          example: budget_confirmed
        kind:
          type: string
          description: What kind of thing was scored.
          enum:
            - field
            - question
            - criterion
          example: field
        label:
          type: string
          description: The field/criterion label, or the question itself.
          example: Budget confirmed
        score:
          type: number
          minimum: 0
          maximum: 100
          description: How well this item scored.
          example: 80
        weightPercent:
          type: number
          description: >-
            Share of the overall match score this item accounts for, in percent.
            Computed from the configured weights (which are relative, not a
            budget), so the shares across all items sum to 100.
          minimum: 0
          maximum: 100
          example: 33.3
        importance:
          type: string
          enum:
            - REQUIRED
            - PREFERRED
        reasoning:
          type: string
          description: Why it scored that way.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.