Candidate

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/100hires-com/json-schema/100hires-com-candidate-schema.json",
  "title": "Candidate",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/100hires-com-openapi.json#/components/schemas/Candidate",
  "type": "object",
  "required": [
    "id",
    "company_id",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Unique identifier"
    },
    "alias": {
      "type": [
        "string",
        "null"
      ],
      "description": "Short alphanumeric alias used in profile URLs. Use this to build candidate profile links — `https://app.100hires.com/candidate/{alias}`. Also accepted as `{id}` in API requests."
    },
    "url_backoffice": {
      "type": "string",
      "format": "uri",
      "description": "Absolute backoffice URL of the candidate in the 100Hires recruiter app. Use to render deep-links in agent UIs."
    },
    "company_id": {
      "type": "integer",
      "description": "ID of the company this candidate belongs to"
    },
    "first_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Candidate's first name"
    },
    "last_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Candidate's last name"
    },
    "emails": {
      "oneOf": [
        {
          "type": "array",
          "items": {
            "type": "string",
            "format": "email"
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "List of candidate email addresses"
    },
    "phones": {
      "oneOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "List of candidate phone numbers"
    },
    "source": {
      "oneOf": [
        {
          "$ref": "#/$defs/IdName"
        },
        {
          "type": "null"
        }
      ],
      "description": "How the candidate was sourced (e.g. LinkedIn, Referral)"
    },
    "origin": {
      "oneOf": [
        {
          "$ref": "#/$defs/IdName"
        },
        {
          "type": "null"
        }
      ],
      "description": "Where the candidate originally came from (e.g. job board name)"
    },
    "profile": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ProfileAnswer"
      },
      "description": "Candidate profile field answers (application form responses). Present only when `view=full` (default); omitted entirely when `view=summary` to keep list responses inside the agent context budget — a single candidate can carry dozens of free-form answers."
    },
    "ip": {
      "type": [
        "string",
        "null"
      ],
      "description": "IP address from which the candidate applied"
    },
    "applications": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CandidateApplicationSummary"
      },
      "description": "Summary of all applications this candidate has across jobs"
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp (seconds)"
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp (seconds)"
    },
    "last_message_at": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "Unix timestamp (seconds) of the most recent message (email or SMS) sent to or received from this candidate. Null if no messages exist."
    },
    "days_since_last_message": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Number of whole days since the last message. Computed at request time. Null if no messages exist."
    }
  },
  "$defs": {
    "CandidateApplicationSummary": {
      "type": "object",
      "required": [
        "id",
        "job"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "Application ID."
        },
        "job": {
          "type": "object",
          "description": "Job summary (id, title, status).",
          "required": [
            "id",
            "title"
          ],
          "properties": {
            "id": {
              "type": "integer"
            },
            "title": {
              "type": "string"
            }
          }
        },
        "stage": {
          "oneOf": [
            {
              "$ref": "#/$defs/IdName"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "IdName": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "description": "Unique identifier."
        },
        "name": {
          "type": "string",
          "description": "Display name."
        }
      }
    },
    "ProfileAnswer": {
      "type": "object",
      "required": [
        "question_id",
        "question_text",
        "value"
      ],
      "properties": {
        "question_id": {
          "type": "integer",
          "description": "Question ID."
        },
        "question_text": {
          "type": "string",
          "description": "Question label."
        },
        "value": {
          "description": "Answer value (string, array, or null)."
        }
      }
    }
  }
}