CandidateWriteRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/100hires-com/json-schema/100hires-com-candidate-write-request-schema.json",
  "title": "CandidateWriteRequest",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/100hires-com-openapi.json#/components/schemas/CandidateWriteRequest",
  "type": "object",
  "properties": {
    "company_id": {
      "type": "integer",
      "description": "Target company ID. Required only when the API key has access to multiple companies."
    },
    "first_name": {
      "type": "string",
      "description": "Candidate first name."
    },
    "last_name": {
      "type": "string",
      "description": "Candidate last name."
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Candidate email address. Used for deduplication."
    },
    "phone": {
      "type": "string",
      "description": "Candidate phone number."
    },
    "profile": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "array",
            "items": {}
          }
        ]
      },
      "description": "Key-value map of profile field answers. Keys can be either question text (string) or question_id (integer from GET /questions). Library fields (First name, Last name, Email, Phone, etc.) and custom fields both support text-based keys. Example: {\"Years of experience\": \"5\"} or {\"42\": \"5\"}. Must be a JSON object — a JSON array or a plain string is rejected with 400 Validation Error. Every key must resolve to a question of the target company and every value must be acceptable for that question's type; otherwise the request is rejected with 400 Validation Error listing the offending keys in validation_errors.profile, and nothing is saved. Multi-value fields such as Email accept an array of values, e.g. {\"Email\": [\"a@example.com\", \"b@example.com\"]}. Yes/No questions take 1 or 0, as a number or as a string — send JSON false as 0, since a JSON false is indistinguishable from an empty value and is rejected.\n"
    },
    "job_id": {
      "type": "integer",
      "description": "Job ID to create an application for this candidate. If omitted, candidate is created without an application."
    },
    "stage_id": {
      "type": "integer",
      "description": "Pipeline stage ID for the initial application. Requires job_id. If omitted with job_id, defaults to the first stage."
    },
    "cv": {
      "$ref": "#/$defs/FileData"
    },
    "city": {
      "type": "string",
      "description": "Candidate city. Used together with state/country to resolve timezone and location display in the profile header. If omitted or empty, taken from the candidate's 'City' profile answer when present."
    },
    "state": {
      "type": "string",
      "description": "Candidate state or region. If omitted or empty, taken from the candidate's 'State' profile answer when present."
    },
    "country": {
      "type": "string",
      "description": "Candidate country name or ISO 3166-1 alpha-2 code (e.g. 'United States' or 'US'). If omitted or empty, taken from the candidate's 'Country' profile answer when present."
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone (e.g. 'America/Los_Angeles'). If omitted, resolved automatically from city/country. If provided alongside city, overrides the auto-resolved timezone."
    }
  },
  "additionalProperties": false,
  "$defs": {
    "FileData": {
      "type": "object",
      "required": [
        "data",
        "file_name",
        "mime_type"
      ],
      "properties": {
        "data": {
          "type": "string",
          "description": "Base64 content"
        },
        "file_name": {
          "type": "string",
          "description": "Original file name."
        },
        "mime_type": {
          "type": "string",
          "description": "MIME type (e.g. application/pdf)."
        },
        "size": {
          "type": "integer",
          "description": "Optional for uploads, returned in responses"
        }
      }
    }
  }
}