---
title: "List candidate messages"
method: GET
path: "/candidates/{id}/messages"
tags: ["Messages"]
---

# List candidate messages

`GET /candidates/{id}/messages`

## Request

- Base URL: `https://api.100hires.com/v2`
- URL: `https://api.100hires.com/v2/candidates/{id}/messages`
- Auth: HTTP bearer

Returns paginated email and messaging history for a candidate. Useful for communication timeline and audit trails. Use `is_scheduled=1` to filter only scheduled (pending) messages.

## Path parameters

- `id` string, required

## Query parameters

- `page` integer
- `size` integer
- `view` 'full' | 'summary'
- `is_scheduled` 1

## Response `200`

Message list

- CandidateMessageListResponse
  - `messages` CandidateMessage[], required: Array of messages.
    - union
      - CandidateMailboxMessage
        - `type` 'mailbox', required: Message type discriminator.
        - `is_sent_by_candidate` boolean, required: Whether the candidate sent this message.
        - `message` MailboxMessage, required
          - `id` integer, required: Message ID.
          - `from` string, nullable, required: Sender address.
          - `to` string, required: Recipient address.
          - `cc` string, required: CC recipients.
          - `subject` string, required: Message subject.
          - `body` string: Message body content. Present only when `view=full` (default); omitted entirely when `view=summary` — message bodies can run into tens of KB.
          - `date` string, required: Message date.
          - `attachments` Attachment[]: Message attachments. Present only when `view=full` (default); omitted entirely when `view=summary`.
            - `uuid` string, uuid, required: Unique attachment identifier. Stable across API calls; use in referencing endpoints.
            - `url` string, uri, nullable, required: Absolute download URL (e.g. `https://api.100hires.com/v2/attachments/application/{uuid}/{file_name}`). Hit with `Authorization: Bearer <API_KEY>`.
            - `relative_time` string, required: Human-readable time since upload (e.g. `"2 days ago"`).
            - `file` AttachmentFile, required
              - …
          - `schedule` union, required
            - ''
            - MailboxSchedule
              - …
          - `opensCount` integer, required: Number of times opened.
          - `opens` MailboxOpenEvent[], required: Array of open tracking events.
            - `label` string, required: Open event label.
          - `autoJobId` union, required
            - integer
            - string
          - `isNurtured` boolean, required: Whether sent via nurture campaign.
      - CandidateTextingMessage
        - `type` 'texting', required: Message type discriminator.
        - `is_sent_by_candidate` boolean, required: Whether the candidate sent this message.
        - `message` TextingMessage, required
          - `id` integer, required: Message ID.
          - `body` string, required: Message body content.
          - `date` string, required: Message date.
          - `isFailed` boolean, required: Whether delivery failed.
          - `sendError` string, nullable, required: Error message on failure.
          - `schedule` union, required
            - ''
            - TextingSchedule
              - …
          - `autoJobId` union, required
            - integer
            - string
          - `isNurtured` boolean, required: Whether sent via nurture campaign.
          - `to` string, required: Recipient address.
          - `from` string, nullable: Sender address.
      - CandidateVoicemailMessage
        - `type` 'voicemail', required: Message type discriminator.
        - `is_sent_by_candidate` boolean, required: Whether the candidate sent this message.
        - `message` VoicemailMessage, required
          - `id` integer, required: Message ID.
          - `date` string, required: Message date.
          - `to` string, required: Recipient address.
          - `from` string, nullable, required: Sender address.
          - `attachment` Attachment, required: Unified attachment shape returned by apiV2 endpoints (resumes, candidate files, application attachments, message attachments, call recordings, voicemail audio in nurture campaigns). `url` is an absolute URL served by the API host (`https://api.100hires.com/v2/attachments/{category}/{uuid}/{file_name}`) and serves the raw file bytes with `Authorization: Bearer <API_KEY>`. The response on `url` sets `Content-Disposition: attachment; filename="..."` with the human-readable filename. Use `uuid` to reference the attachment in other endpoints (e.g. nurture voicemail step).
            - `uuid` string, uuid, required: Unique attachment identifier. Stable across API calls; use in referencing endpoints.
            - `url` string, uri, nullable, required: Absolute download URL (e.g. `https://api.100hires.com/v2/attachments/application/{uuid}/{file_name}`). Hit with `Authorization: Bearer <API_KEY>`.
            - `relative_time` string, required: Human-readable time since upload (e.g. `"2 days ago"`).
            - `file` AttachmentFile, required
              - …
          - `isFailed` boolean, required: Whether delivery failed.
          - `sendError` string, nullable, required: Error message on failure.
          - `schedule` union, required
            - ''
            - VoicemailSchedule
              - …
          - `isCallTook` boolean, required: Whether the call was answered.
          - `autoJobId` union, required
            - integer
            - string
          - `isNurtured` boolean, required: Whether sent via nurture campaign.
      - CandidateInitialMailMessage
        - `type` 'candidate_initial_mail_message', required: Message type discriminator.
        - `is_sent_by_candidate` boolean, required: Whether the candidate sent this message.
        - `message` InitialMailMessage, required
          - `id` integer, required: Message ID.
          - `from` string, required: Sender address.
          - `to` string, required: Recipient address.
          - `subject` string, required: Message subject.
          - `body` string, required: Message body content.
          - `date` string, required: Message date.
      - CandidateNotificationMessage
        - `type` 'notification', required: Message type discriminator.
        - `is_sent_by_candidate` boolean, required: Whether the candidate sent this message.
        - `message` NotificationMessage, required
          - `id` integer, required: Message ID.
          - `from` string, required: Sender address.
          - `to` string, required: Recipient address.
          - `subject` string, required: Message subject.
          - `body` string, required: Message body content.
          - `date` string, required: Message date.
          - `schedule` union, required
            - ''
            - NotificationMessageSchedule
              - …
  - `pagination` Pagination, required
    - `page_size` integer, required: Items per page.
    - `page_count` integer, required: Total number of pages.
    - `page` integer, required: Current page number.
    - `total_count` integer, required: Total number of items.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Too many requests

---

[API](https://skmtc.dev/100hires/apis/100hires-api.md) · [All operations](https://skmtc.dev/100hires/apis/100hires-api/llms.txt) · [OpenAPI document](https://skmtc.dev/100hires/apis/100hires-api/revisions/e63e2d3115f7?raw)