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

# Update Interview Request

> Updates context on an existing interview request. Accepts any combination of
`contact_context`, `contact_name`, and `objective`. At least one field must be provided.

- `contact_context` and `contact_name` update the contact record associated with the request.
  Context is stored in the contact's notes field and used by Paige in every future interview prompt for that contact.
- `objective` updates the interview-specific goal on the request itself.


<Accordion title="Copy for AI context">
  ```text theme={null}
  PATCH https://app.usehindsight.com/api/v1/interviews/{id}
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  Path parameter:
    id: integer  — the interview_request_id returned from POST /interviews

  Request body (at least one field required):
  {
    "contact_context": { ... } | "string",  // overwrites contact notes
    "contact_name": "Jane Smith",            // updates contact display name
    "objective": "string"                    // updates interview-specific goal
  }

  200 Response:
  {
    "interview_request_id": 4821
  }

  Rate limits: 60 req/min (Essentials), 300 req/min (Growth), 1,000 req/min (Enterprise)
  ```
</Accordion>

## Overview

Use this endpoint to update context on an interview request after it has been created.

* **`contact_context`** and **`contact_name`** update the contact record linked to the request. Context is stored in the contact's notes field and included in every future interview prompt Paige runs for that contact.
* **`objective`** updates the interview-specific goal on the request itself, giving Paige a targeted focus for this particular interview.

At least one field must be provided. Fields not included in the request are left unchanged.

## Path Parameter

| Parameter | Type    | Description                                                                                |
| --------- | ------- | ------------------------------------------------------------------------------------------ |
| `id`      | integer | The `interview_request_id` returned when the interview was created via `POST /interviews`. |

## Request Body

| Field             | Type             | Description                                                                                                                                                                                            |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `contact_context` | string \| object | Updated context about the contact. **Overwrites** the existing contact notes — merge manually if you want to preserve prior context. Accepts a plain string or JSON object (serialized automatically). |
| `contact_name`    | string           | Updated display name for the contact.                                                                                                                                                                  |
| `objective`       | string           | Updated goal for this specific interview. Paige uses this when generating questions and conducting the conversation.                                                                                   |

<Warning>
  `contact_context` overwrites the contact's existing notes rather than merging. If you want to preserve prior context, read the contact's current notes first and include them in your update.
</Warning>

## Response

| Field                  | Type    | Description                          |
| ---------------------- | ------- | ------------------------------------ |
| `interview_request_id` | integer | ID of the updated interview request. |

## Rate Limits

| Plan       | Requests per Minute |
| ---------- | ------------------- |
| Essentials | 60                  |
| Growth     | 300                 |
| Enterprise | 1,000               |

## Examples

<RequestExample>
  ```bash Update contact context theme={null}
  curl -X PATCH "https://app.usehindsight.com/api/v1/interviews/4821" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contact_context": {
        "title": "CTO",
        "evaluation_notes": "Completed 30-day POC, main concern is pricing"
      }
    }'
  ```

  ```bash Update objective only theme={null}
  curl -X PATCH "https://app.usehindsight.com/api/v1/interviews/4821" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "objective": "Focus on why pricing was a blocker vs. Competitor X"
    }'
  ```

  ```bash Update all fields theme={null}
  curl -X PATCH "https://app.usehindsight.com/api/v1/interviews/4821" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contact_name": "Jane Smith",
      "contact_context": {
        "title": "CTO",
        "evaluation_notes": "Completed POC, flagged pricing and Jira integration"
      },
      "objective": "Understand the pricing objection and Competitor X comparison"
    }'
  ```

  ```javascript Node.js - Update after CRM enrichment theme={null}
  const interviewRequestId = 4821; // stored from POST /interviews response

  await fetch(`https://app.usehindsight.com/api/v1/interviews/${interviewRequestId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${process.env.HINDSIGHT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      contact_context: {
        title: enrichedContact.title,
        linkedin: enrichedContact.linkedinUrl,
        evaluation_notes: deal.internalNotes,
      },
      objective: `Win-loss: understand loss to ${deal.competitorName}`,
    }),
  });
  ```

  ```python Python - Enrich context before interview sends theme={null}
  import requests

  def update_interview_context(interview_request_id, contact_data, objective=None):
      payload = {
          'contact_context': {
              'title': contact_data.get('title'),
              'seniority': contact_data.get('seniority'),
              'notes': contact_data.get('notes'),
          }
      }
      if objective:
          payload['objective'] = objective

      response = requests.patch(
          f'https://app.usehindsight.com/api/v1/interviews/{interview_request_id}',
          headers={'Authorization': f'Bearer {API_KEY}'},
          json=payload
      )
      response.raise_for_status()
      return response.json()
  ```
</RequestExample>

## Error Responses

| Code                  | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `bad_request`         | No fields provided, or invalid JSON.                           |
| `unauthorized`        | Invalid or missing API key.                                    |
| `not_found`           | Interview request not found, or it belongs to a different org. |
| `rate_limit_exceeded` | Too many requests. Check `X-RateLimit-Reset` and retry after.  |

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Interview request not found"
  }
}
```


## OpenAPI

````yaml PATCH /interviews/{id}
openapi: 3.1.0
info:
  title: Hindsight API
  description: >
    Integrate Hindsight competitive intelligence, win-loss insights, and deal
    data into your applications.


    ## Authentication

    All API requests require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    Get your API key from the [Hindsight
    dashboard](https://app.usehindsight.com/settings/keys).


    ## Rate Limits


    API requests are rate-limited per plan:


    | Plan | Per Minute | Per Month |

    |------|-----------|----------|

    | Essentials | 10 | 10,000 |

    | Growth | 60 | 30,000 |

    | Enterprise | 300 | 100,000 |


    When a limit is exceeded, the API returns a `429` response. Check the
    `Retry-After` header for when to retry.
  version: 1.0.0
  contact:
    name: Hindsight Support
    url: https://usehindsight.com/support
    email: support@hindsight.com
servers:
  - url: https://app.usehindsight.com/api/v1
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: AI-powered chat completions with competitive intelligence
  - name: Deals
    description: Access and export deal data
  - name: Documents
    description: Upload and manage documents
  - name: Interviews
    description: Create and manage win-loss interview requests
paths:
  /interviews/{id}:
    patch:
      tags:
        - Interviews
      summary: Update an interview request
      description: >
        Updates context on an existing interview request. Accepts any
        combination of

        `contact_context`, `contact_name`, and `objective`. At least one field
        must be provided.


        - `contact_context` and `contact_name` update the contact record
        associated with the request.
          Context is stored in the contact's notes field and used by Paige in every future interview prompt for that contact.
        - `objective` updates the interview-specific goal on the request itself.
      operationId: updateInterview
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: The `interview_request_id` returned when the interview was created.
          example: 4821
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInterviewRequest'
            examples:
              updateContext:
                summary: Update contact context
                value:
                  contact_context:
                    title: CTO
                    evaluation_notes: Completed POC, main concern is pricing
              updateObjective:
                summary: Update interview objective
                value:
                  objective: Focus on why pricing was a blocker vs. Competitor X
              updateAll:
                summary: Update everything
                value:
                  contact_name: Jane Smith
                  contact_context:
                    title: CTO
                    evaluation_notes: Completed POC
                  objective: Focus on pricing concerns
      responses:
        '200':
          description: Interview request updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateInterviewResponse'
              example:
                interview_request_id: 4821
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Interview request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Interview request not found
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    UpdateInterviewRequest:
      type: object
      properties:
        contact_context:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >
            Updated context about the contact. Overwrites the existing contact
            notes.

            Used by Paige as background in every future interview prompt for
            this contact.
          example:
            title: CTO
            evaluation_notes: Completed 30-day POC, main concern is pricing
        contact_name:
          type: string
          description: Updated display name for the contact.
          example: Jane Smith
        objective:
          type: string
          description: Updated goal for this specific interview.
          example: Focus on why pricing was a blocker vs. Competitor X
    UpdateInterviewResponse:
      type: object
      properties:
        interview_request_id:
          type: integer
          description: ID of the updated interview request.
          example: 4821
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: unauthorized
            message:
              type: string
              description: Human-readable error message
              example: Invalid API key
            details:
              type: object
              description: Additional error details
              additionalProperties: true
  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: bad_request
              message: Invalid parameters
              details:
                missing_fields:
                  - file_name
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid API key
    RateLimitExceeded:
      description: Too many requests - rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limit_exceeded
              message: >-
                Rate limit exceeded. Limits are 10/min on Essentials, 60/min on
                Growth, and 300/min on Enterprise. Check the Retry-After header.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Number of seconds to wait before retrying
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: internal_error
              message: An unexpected error occurred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from Hindsight dashboard

````