Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Candidate portal

Read the authenticated candidate profile

GET/workforce/candidate-portal/me

Returns the candidate profile, applications, interviews, offers, and allowed actions owned by the authenticated candidate capability.

Authentication

Authorization: Candidate <HALLIFY_CANDIDATE_PORTAL_TOKEN>

Candidate portal credential in Candidate <token> form.

Connection guide

Parameters

cursorQuery · Optional

Optional opaque cursor returned by the preceding page; submit it unchanged with the same scope and filters to continue.

string
Full definition
{
  "maxLength": 2048,
  "type": "string",
  "example": "example"
}
limitQuery · Optional

Optional maximum number of records returned in one page; response pagination metadata indicates how to continue when more matches remain.

integer
Full definition
{
  "minimum": 1,
  "maximum": 50,
  "default": 20,
  "type": "integer",
  "example": 20
}

Responses

200The candidate profile, applications, interviews, offers, and allowed actions owned by the authenticated candidate capability.
CandidatePortalMeDto
Full definition
{
  "$ref": "#/components/schemas/CandidatePortalMeDto"
}
Example response · 200 · application/json
{
  "candidate": {
    "id": "794ae235-ae89-44f0-8118-f8817918f169",
    "firstName": "Example",
    "lastName": "User",
    "email": "user@example.test",
    "status": "ACTIVE",
    "revision": 1
  },
  "applications": [
    {
      "id": "0120f0fe-6880-47e8-895d-c092d269cdd1",
      "requisitionTitle": "Example title",
      "currentStage": {
        "id": "f97fe865-5ff8-488a-8fab-9e27e748514c",
        "code": "EXAMPLE",
        "name": "Example name",
        "category": "APPLIED",
        "isTerminal": true,
        "sortOrder": 1,
        "revision": 1
      },
      "status": "ACTIVE",
      "appliedAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T13:00:00.000Z",
      "revision": 1,
      "canWithdraw": true
    }
  ],
  "sessionExpiresAt": "2026-12-31T18:00:00.000Z",
  "serverTime": "2026-01-15T12:00:00.000Z"
}
401Rejects a missing, malformed, expired, revoked, or invalid candidatePortalToken credential at the owning domain boundary.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 401 · application/json
{
  "statusCode": 401,
  "error": "errors:http.unauthorized",
  "code": "HTTP_UNAUTHORIZED",
  "message": "errors:http.unauthorized",
  "translationKey": "errors:http.unauthorized"
}

Schemas

CandidatePortalMeDto

The candidate profile, applications, interviews, offers, and allowed actions owned by the authenticated candidate capability.

candidateRequired

Recruiting candidate embedded as candidate in candidate portal me.

allOf
Full definition
{
  "allOf": [
    {
      "$ref": "#/components/schemas/RecruitingCandidateDto"
    }
  ],
  "description": "Recruiting candidate embedded as candidate in candidate portal me.",
  "example": {
    "id": "794ae235-ae89-44f0-8118-f8817918f169",
    "firstName": "Example",
    "lastName": "User",
    "email": "user@example.test",
    "status": "ACTIVE",
    "revision": 1
  }
}
applicationsRequired

Candidate portal application included as applications in candidate portal me.

array
Full definition
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/CandidatePortalApplicationDto"
  },
  "description": "Candidate portal application included as applications in candidate portal me.",
  "example": [
    {
      "id": "0120f0fe-6880-47e8-895d-c092d269cdd1",
      "requisitionTitle": "Example title",
      "currentStage": {
        "id": "f97fe865-5ff8-488a-8fab-9e27e748514c",
        "code": "EXAMPLE",
        "name": "Example name",
        "category": "APPLIED",
        "isTerminal": true,
        "sortOrder": 1,
        "revision": 1
      },
      "status": "ACTIVE",
      "appliedAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T13:00:00.000Z",
      "revision": 1,
      "canWithdraw": true
    }
  ]
}
nextCursorOptional

Opaque pagination cursor for candidate portal me; return it unchanged with the same filters. Null means no value is recorded for this representation.

string · null
Full definition
{
  "type": "string",
  "nullable": true,
  "description": "Opaque pagination cursor for candidate portal me; return it unchanged with the same filters. Null means no value is recorded for this representation.",
  "example": "example"
}
sessionExpiresAtRequired

Timestamp recording when session expires occurred for candidate portal me.

string · date-time
Full definition
{
  "type": "string",
  "description": "Timestamp recording when session expires occurred for candidate portal me.",
  "format": "date-time",
  "example": "2026-12-31T18:00:00.000Z"
}
serverTimeRequired

Server-generated timestamp representing when candidate portal me was assembled.

string · date-time
Full definition
{
  "type": "string",
  "description": "Server-generated timestamp representing when candidate portal me was assembled.",
  "format": "date-time",
  "example": "2026-01-15T12:00:00.000Z"
}
Full definition
{
  "type": "object",
  "properties": {
    "candidate": {
      "allOf": [
        {
          "$ref": "#/components/schemas/RecruitingCandidateDto"
        }
      ],
      "description": "Recruiting candidate embedded as candidate in candidate portal me.",
      "example": {
        "id": "794ae235-ae89-44f0-8118-f8817918f169",
        "firstName": "Example",
        "lastName": "User",
        "email": "user@example.test",
        "status": "ACTIVE",
        "revision": 1
      }
    },
    "applications": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CandidatePortalApplicationDto"
      },
      "description": "Candidate portal application included as applications in candidate portal me.",
      "example": [
        {
          "id": "0120f0fe-6880-47e8-895d-c092d269cdd1",
          "requisitionTitle": "Example title",
          "currentStage": {
            "id": "f97fe865-5ff8-488a-8fab-9e27e748514c",
            "code": "EXAMPLE",
            "name": "Example name",
            "category": "APPLIED",
            "isTerminal": true,
            "sortOrder": 1,
            "revision": 1
          },
          "status": "ACTIVE",
          "appliedAt": "2026-01-15T12:00:00.000Z",
          "updatedAt": "2026-01-15T13:00:00.000Z",
          "revision": 1,
          "canWithdraw": true
        }
      ]
    },
    "nextCursor": {
      "type": "string",
      "nullable": true,
      "description": "Opaque pagination cursor for candidate portal me; return it unchanged with the same filters. Null means no value is recorded for this representation.",
      "example": "example"
    },
    "sessionExpiresAt": {
      "type": "string",
      "description": "Timestamp recording when session expires occurred for candidate portal me.",
      "format": "date-time",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "serverTime": {
      "type": "string",
      "description": "Server-generated timestamp representing when candidate portal me was assembled.",
      "format": "date-time",
      "example": "2026-01-15T12:00:00.000Z"
    }
  },
  "required": [
    "candidate",
    "applications",
    "sessionExpiresAt",
    "serverTime"
  ],
  "description": "The candidate profile, applications, interviews, offers, and allowed actions owned by the authenticated candidate capability.",
  "example": {
    "candidate": {
      "id": "794ae235-ae89-44f0-8118-f8817918f169",
      "firstName": "Example",
      "lastName": "User",
      "email": "user@example.test",
      "status": "ACTIVE",
      "revision": 1
    },
    "applications": [
      {
        "id": "0120f0fe-6880-47e8-895d-c092d269cdd1",
        "requisitionTitle": "Example title",
        "currentStage": {
          "id": "f97fe865-5ff8-488a-8fab-9e27e748514c",
          "code": "EXAMPLE",
          "name": "Example name",
          "category": "APPLIED",
          "isTerminal": true,
          "sortOrder": 1,
          "revision": 1
        },
        "status": "ACTIVE",
        "appliedAt": "2026-01-15T12:00:00.000Z",
        "updatedAt": "2026-01-15T13:00:00.000Z",
        "revision": 1,
        "canWithdraw": true
      }
    ],
    "sessionExpiresAt": "2026-12-31T18:00:00.000Z",
    "serverTime": "2026-01-15T12:00:00.000Z"
  }
}
RecruitingCandidateDto

Recruiting candidate identity, contact channels, source, lifecycle status, and revision.

idRequired

Hallify UUID identifying recruiting candidate.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Hallify UUID identifying recruiting candidate.",
  "example": "794ae235-ae89-44f0-8118-f8817918f169"
}
firstNameRequired

Human-readable first name for recruiting candidate.

string
Full definition
{
  "type": "string",
  "description": "Human-readable first name for recruiting candidate.",
  "example": "Example"
}
lastNameRequired

Human-readable last name for recruiting candidate.

string
Full definition
{
  "type": "string",
  "description": "Human-readable last name for recruiting candidate.",
  "example": "User"
}
preferredNameOptional

Human-readable preferred name for recruiting candidate. Null means no value is recorded for this representation.

string · null
Full definition
{
  "type": "string",
  "nullable": true,
  "description": "Human-readable preferred name for recruiting candidate. Null means no value is recorded for this representation.",
  "example": "Example name"
}
emailRequired

Email address recorded for email in recruiting candidate.

string · email
Full definition
{
  "type": "string",
  "description": "Email address recorded for email in recruiting candidate.",
  "format": "email",
  "example": "user@example.test"
}
phoneOptional

Telephone number recorded for phone in recruiting candidate. Null means no value is recorded for this representation.

string · null
Full definition
{
  "type": "string",
  "nullable": true,
  "description": "Telephone number recorded for phone in recruiting candidate. Null means no value is recorded for this representation.",
  "example": "+995555000000"
}
sourceOptional

Source classification identifying where source originated. Null means no value is recorded for this representation.

string · null
Full definition
{
  "type": "string",
  "nullable": true,
  "description": "Source classification identifying where source originated. Null means no value is recorded for this representation.",
  "example": "example"
}
statusRequired

Current lifecycle status of recruiting candidate; allowed values are ACTIVE, HIRED, WITHDRAWN, ARCHIVED.

string
Full definition
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "HIRED",
    "WITHDRAWN",
    "ARCHIVED"
  ],
  "description": "Current lifecycle status of recruiting candidate; allowed values are ACTIVE, HIRED, WITHDRAWN, ARCHIVED.",
  "example": "ACTIVE"
}
revisionRequired

Monotonic optimistic-concurrency revision for recruiting candidate.

integer
Full definition
{
  "type": "integer",
  "description": "Monotonic optimistic-concurrency revision for recruiting candidate.",
  "example": 1
}
Full definition
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying recruiting candidate.",
      "example": "794ae235-ae89-44f0-8118-f8817918f169"
    },
    "firstName": {
      "type": "string",
      "description": "Human-readable first name for recruiting candidate.",
      "example": "Example"
    },
    "lastName": {
      "type": "string",
      "description": "Human-readable last name for recruiting candidate.",
      "example": "User"
    },
    "preferredName": {
      "type": "string",
      "nullable": true,
      "description": "Human-readable preferred name for recruiting candidate. Null means no value is recorded for this representation.",
      "example": "Example name"
    },
    "email": {
      "type": "string",
      "description": "Email address recorded for email in recruiting candidate.",
      "format": "email",
      "example": "user@example.test"
    },
    "phone": {
      "type": "string",
      "nullable": true,
      "description": "Telephone number recorded for phone in recruiting candidate. Null means no value is recorded for this representation.",
      "example": "+995555000000"
    },
    "source": {
      "type": "string",
      "nullable": true,
      "description": "Source classification identifying where source originated. Null means no value is recorded for this representation.",
      "example": "example"
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "HIRED",
        "WITHDRAWN",
        "ARCHIVED"
      ],
      "description": "Current lifecycle status of recruiting candidate; allowed values are ACTIVE, HIRED, WITHDRAWN, ARCHIVED.",
      "example": "ACTIVE"
    },
    "revision": {
      "type": "integer",
      "description": "Monotonic optimistic-concurrency revision for recruiting candidate.",
      "example": 1
    }
  },
  "required": [
    "id",
    "firstName",
    "lastName",
    "email",
    "status",
    "revision"
  ],
  "description": "Recruiting candidate identity, contact channels, source, lifecycle status, and revision.",
  "example": {
    "id": "794ae235-ae89-44f0-8118-f8817918f169",
    "firstName": "Example",
    "lastName": "User",
    "email": "user@example.test",
    "status": "ACTIVE",
    "revision": 1
  }
}
CandidatePortalApplicationDto

Candidate-owned application in its withdrawn terminal stage with the updated revision and preserved submission evidence.

idRequired

Hallify UUID identifying candidate portal application.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Hallify UUID identifying candidate portal application.",
  "example": "0120f0fe-6880-47e8-895d-c092d269cdd1"
}
requisitionTitleRequired

Requisition title for candidate portal application.

string
Full definition
{
  "type": "string",
  "description": "Requisition title for candidate portal application.",
  "example": "Example title"
}
currentStageRequired

Recruiting stage embedded as current stage in candidate portal application.

allOf
Full definition
{
  "allOf": [
    {
      "$ref": "#/components/schemas/RecruitingStageDto"
    }
  ],
  "description": "Recruiting stage embedded as current stage in candidate portal application.",
  "example": {
    "id": "f97fe865-5ff8-488a-8fab-9e27e748514c",
    "code": "EXAMPLE",
    "name": "Example name",
    "category": "APPLIED",
    "isTerminal": true,
    "sortOrder": 1,
    "revision": 1
  }
}
statusRequired

Current lifecycle status of candidate portal application; allowed values are ACTIVE, OFFERED, HIRED, REJECTED, WITHDRAWN.

string
Full definition
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "OFFERED",
    "HIRED",
    "REJECTED",
    "WITHDRAWN"
  ],
  "description": "Current lifecycle status of candidate portal application; allowed values are ACTIVE, OFFERED, HIRED, REJECTED, WITHDRAWN.",
  "example": "ACTIVE"
}
appliedAtRequired

Timestamp recording when applied occurred for candidate portal application.

string · date-time
Full definition
{
  "type": "string",
  "description": "Timestamp recording when applied occurred for candidate portal application.",
  "format": "date-time",
  "example": "2026-01-15T12:00:00.000Z"
}
updatedAtRequired

Timestamp recording when updated occurred for candidate portal application.

string · date-time
Full definition
{
  "type": "string",
  "description": "Timestamp recording when updated occurred for candidate portal application.",
  "format": "date-time",
  "example": "2026-01-15T13:00:00.000Z"
}
revisionRequired

Monotonic optimistic-concurrency revision for candidate portal application.

integer
Full definition
{
  "type": "integer",
  "description": "Monotonic optimistic-concurrency revision for candidate portal application.",
  "example": 1
}
offerOptional

Offer details embedded in candidate portal application. Null means no value is recorded for this representation.

object · null
Full definition
{
  "nullable": true,
  "type": "object",
  "description": "Offer details embedded in candidate portal application. Null means no value is recorded for this representation.",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying candidate portal offer.",
      "example": "dfa73755-b161-462c-87aa-7f0d20d8a424"
    },
    "status": {
      "type": "string",
      "enum": [
        "DRAFT",
        "SENT",
        "ACCEPTED",
        "DECLINED",
        "EXPIRED",
        "WITHDRAWN",
        "CONVERTED"
      ],
      "description": "Current lifecycle status of candidate portal offer; allowed values are DRAFT, SENT, ACCEPTED, DECLINED, EXPIRED, WITHDRAWN, CONVERTED.",
      "example": "DRAFT"
    },
    "legalEntity": {
      "allOf": [
        {
          "$ref": "#/components/schemas/RecruitingReferenceItemDto"
        }
      ],
      "description": "Recruiting reference item embedded as legal entity in candidate portal offer.",
      "example": {
        "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
        "name": "Example name"
      }
    },
    "venue": {
      "allOf": [
        {
          "$ref": "#/components/schemas/RecruitingReferenceItemDto"
        }
      ],
      "description": "Recruiting reference item embedded as venue in candidate portal offer.",
      "example": {
        "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
        "name": "Example name"
      }
    },
    "department": {
      "nullable": true,
      "type": "object",
      "description": "Department details embedded in candidate portal offer. Null means no value is recorded for this representation.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Hallify UUID identifying recruiting reference item.",
          "example": "e6112f96-9ef5-48fb-82cf-4187a8ce329c"
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for recruiting reference item.",
          "example": "Example name"
        },
        "code": {
          "type": "string",
          "nullable": true,
          "description": "Stable code used to classify or address recruiting reference item. Null means no value is recorded for this representation.",
          "example": "EXAMPLE"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "example": {
        "id": "e6112f96-9ef5-48fb-82cf-4187a8ce329c",
        "name": "Example name"
      }
    },
    "jobProfile": {
      "nullable": true,
      "type": "object",
      "description": "Job profile details embedded in candidate portal offer. Null means no value is recorded for this representation.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Hallify UUID identifying recruiting reference item.",
          "example": "66c21fb4-4f9b-4f13-817d-088bf2bee5ca"
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for recruiting reference item.",
          "example": "Example name"
        },
        "code": {
          "type": "string",
          "nullable": true,
          "description": "Stable code used to classify or address recruiting reference item. Null means no value is recorded for this representation.",
          "example": "EXAMPLE"
        }
      },
      "required": [
        "id",
        "name"
      ],
      "example": {
        "id": "66c21fb4-4f9b-4f13-817d-088bf2bee5ca",
        "name": "Example name"
      }
    },
    "classification": {
      "type": "string",
      "enum": [
        "EMPLOYEE",
        "CONTRACTOR",
        "INTERN",
        "APPRENTICE"
      ],
      "description": "Allowed classification for candidate portal offer: EMPLOYEE, CONTRACTOR, INTERN, APPRENTICE.",
      "example": "EMPLOYEE"
    },
    "contractType": {
      "type": "string",
      "enum": [
        "FULL_TIME",
        "PART_TIME",
        "FIXED_TERM",
        "CASUAL",
        "SEASONAL",
        "ON_CALL"
      ],
      "description": "Allowed contract type for candidate portal offer: FULL_TIME, PART_TIME, FIXED_TERM, CASUAL, SEASONAL, ON_CALL.",
      "example": "FULL_TIME"
    },
    "startDate": {
      "type": "string",
      "description": "Calendar date for start date serialized as ISO 8601 YYYY-MM-DD without an implicit time of day.",
      "format": "date",
      "example": "2026-01-15"
    },
    "compensationAmount": {
      "type": "string",
      "nullable": true,
      "description": "Decimal monetary compensation amount serialized as a string in the currency identified by the `compensationCurrency` field; zero is a recorded amount, not absence. Null means no value is recorded for this representation.",
      "example": "1.00"
    },
    "compensationCurrency": {
      "type": "string",
      "nullable": true,
      "description": "ISO 4217 currency code for the monetary values carried by candidate portal offer. Null means no value is recorded for this representation.",
      "example": "GEL"
    },
    "compensationPeriod": {
      "type": "string",
      "enum": [
        "HOURLY",
        "DAILY",
        "WEEKLY",
        "MONTHLY",
        "ANNUAL",
        null
      ],
      "nullable": true,
      "description": "Allowed compensation period for candidate portal offer: HOURLY, DAILY, WEEKLY, MONTHLY, ANNUAL. Null means no value is recorded for this representation.",
      "example": "HOURLY"
    },
    "terms": {
      "type": "string",
      "description": "Terms for candidate portal offer.",
      "example": "example"
    },
    "expiresAt": {
      "type": "string",
      "nullable": true,
      "description": "Timestamp recording when expires occurred for candidate portal offer. Null means no value is recorded for this representation.",
      "format": "date-time",
      "example": "2026-12-31T18:00:00.000Z"
    },
    "revision": {
      "type": "integer",
      "description": "Monotonic optimistic-concurrency revision for candidate portal offer.",
      "example": 1
    },
    "canRespond": {
      "type": "boolean",
      "description": "Whether the caller can respond through candidate portal offer.",
      "example": true
    }
  },
  "required": [
    "id",
    "status",
    "legalEntity",
    "venue",
    "classification",
    "contractType",
    "startDate",
    "terms",
    "revision",
    "canRespond"
  ],
  "example": {
    "id": "dfa73755-b161-462c-87aa-7f0d20d8a424",
    "status": "DRAFT",
    "legalEntity": {
      "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
      "name": "Example name"
    },
    "venue": {
      "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
      "name": "Example name"
    },
    "classification": "EMPLOYEE",
    "contractType": "FULL_TIME",
    "startDate": "2026-01-15",
    "terms": "example",
    "revision": 1,
    "canRespond": true
  }
}
canWithdrawRequired

Whether the caller can withdraw through candidate portal application.

boolean
Full definition
{
  "type": "boolean",
  "description": "Whether the caller can withdraw through candidate portal application.",
  "example": true
}
Full definition
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying candidate portal application.",
      "example": "0120f0fe-6880-47e8-895d-c092d269cdd1"
    },
    "requisitionTitle": {
      "type": "string",
      "description": "Requisition title for candidate portal application.",
      "example": "Example title"
    },
    "currentStage": {
      "allOf": [
        {
          "$ref": "#/components/schemas/RecruitingStageDto"
        }
      ],
      "description": "Recruiting stage embedded as current stage in candidate portal application.",
      "example": {
        "id": "f97fe865-5ff8-488a-8fab-9e27e748514c",
        "code": "EXAMPLE",
        "name": "Example name",
        "category": "APPLIED",
        "isTerminal": true,
        "sortOrder": 1,
        "revision": 1
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "OFFERED",
        "HIRED",
        "REJECTED",
        "WITHDRAWN"
      ],
      "description": "Current lifecycle status of candidate portal application; allowed values are ACTIVE, OFFERED, HIRED, REJECTED, WITHDRAWN.",
      "example": "ACTIVE"
    },
    "appliedAt": {
      "type": "string",
      "description": "Timestamp recording when applied occurred for candidate portal application.",
      "format": "date-time",
      "example": "2026-01-15T12:00:00.000Z"
    },
    "updatedAt": {
      "type": "string",
      "description": "Timestamp recording when updated occurred for candidate portal application.",
      "format": "date-time",
      "example": "2026-01-15T13:00:00.000Z"
    },
    "revision": {
      "type": "integer",
      "description": "Monotonic optimistic-concurrency revision for candidate portal application.",
      "example": 1
    },
    "offer": {
      "nullable": true,
      "type": "object",
      "description": "Offer details embedded in candidate portal application. Null means no value is recorded for this representation.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Hallify UUID identifying candidate portal offer.",
          "example": "dfa73755-b161-462c-87aa-7f0d20d8a424"
        },
        "status": {
          "type": "string",
          "enum": [
            "DRAFT",
            "SENT",
            "ACCEPTED",
            "DECLINED",
            "EXPIRED",
            "WITHDRAWN",
            "CONVERTED"
          ],
          "description": "Current lifecycle status of candidate portal offer; allowed values are DRAFT, SENT, ACCEPTED, DECLINED, EXPIRED, WITHDRAWN, CONVERTED.",
          "example": "DRAFT"
        },
        "legalEntity": {
          "allOf": [
            {
              "$ref": "#/components/schemas/RecruitingReferenceItemDto"
            }
          ],
          "description": "Recruiting reference item embedded as legal entity in candidate portal offer.",
          "example": {
            "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
            "name": "Example name"
          }
        },
        "venue": {
          "allOf": [
            {
              "$ref": "#/components/schemas/RecruitingReferenceItemDto"
            }
          ],
          "description": "Recruiting reference item embedded as venue in candidate portal offer.",
          "example": {
            "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
            "name": "Example name"
          }
        },
        "department": {
          "nullable": true,
          "type": "object",
          "description": "Department details embedded in candidate portal offer. Null means no value is recorded for this representation.",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Hallify UUID identifying recruiting reference item.",
              "example": "e6112f96-9ef5-48fb-82cf-4187a8ce329c"
            },
            "name": {
              "type": "string",
              "description": "Human-readable name for recruiting reference item.",
              "example": "Example name"
            },
            "code": {
              "type": "string",
              "nullable": true,
              "description": "Stable code used to classify or address recruiting reference item. Null means no value is recorded for this representation.",
              "example": "EXAMPLE"
            }
          },
          "required": [
            "id",
            "name"
          ],
          "example": {
            "id": "e6112f96-9ef5-48fb-82cf-4187a8ce329c",
            "name": "Example name"
          }
        },
        "jobProfile": {
          "nullable": true,
          "type": "object",
          "description": "Job profile details embedded in candidate portal offer. Null means no value is recorded for this representation.",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Hallify UUID identifying recruiting reference item.",
              "example": "66c21fb4-4f9b-4f13-817d-088bf2bee5ca"
            },
            "name": {
              "type": "string",
              "description": "Human-readable name for recruiting reference item.",
              "example": "Example name"
            },
            "code": {
              "type": "string",
              "nullable": true,
              "description": "Stable code used to classify or address recruiting reference item. Null means no value is recorded for this representation.",
              "example": "EXAMPLE"
            }
          },
          "required": [
            "id",
            "name"
          ],
          "example": {
            "id": "66c21fb4-4f9b-4f13-817d-088bf2bee5ca",
            "name": "Example name"
          }
        },
        "classification": {
          "type": "string",
          "enum": [
            "EMPLOYEE",
            "CONTRACTOR",
            "INTERN",
            "APPRENTICE"
          ],
          "description": "Allowed classification for candidate portal offer: EMPLOYEE, CONTRACTOR, INTERN, APPRENTICE.",
          "example": "EMPLOYEE"
        },
        "contractType": {
          "type": "string",
          "enum": [
            "FULL_TIME",
            "PART_TIME",
            "FIXED_TERM",
            "CASUAL",
            "SEASONAL",
            "ON_CALL"
          ],
          "description": "Allowed contract type for candidate portal offer: FULL_TIME, PART_TIME, FIXED_TERM, CASUAL, SEASONAL, ON_CALL.",
          "example": "FULL_TIME"
        },
        "startDate": {
          "type": "string",
          "description": "Calendar date for start date serialized as ISO 8601 YYYY-MM-DD without an implicit time of day.",
          "format": "date",
          "example": "2026-01-15"
        },
        "compensationAmount": {
          "type": "string",
          "nullable": true,
          "description": "Decimal monetary compensation amount serialized as a string in the currency identified by the `compensationCurrency` field; zero is a recorded amount, not absence. Null means no value is recorded for this representation.",
          "example": "1.00"
        },
        "compensationCurrency": {
          "type": "string",
          "nullable": true,
          "description": "ISO 4217 currency code for the monetary values carried by candidate portal offer. Null means no value is recorded for this representation.",
          "example": "GEL"
        },
        "compensationPeriod": {
          "type": "string",
          "enum": [
            "HOURLY",
            "DAILY",
            "WEEKLY",
            "MONTHLY",
            "ANNUAL",
            null
          ],
          "nullable": true,
          "description": "Allowed compensation period for candidate portal offer: HOURLY, DAILY, WEEKLY, MONTHLY, ANNUAL. Null means no value is recorded for this representation.",
          "example": "HOURLY"
        },
        "terms": {
          "type": "string",
          "description": "Terms for candidate portal offer.",
          "example": "example"
        },
        "expiresAt": {
          "type": "string",
          "nullable": true,
          "description": "Timestamp recording when expires occurred for candidate portal offer. Null means no value is recorded for this representation.",
          "format": "date-time",
          "example": "2026-12-31T18:00:00.000Z"
        },
        "revision": {
          "type": "integer",
          "description": "Monotonic optimistic-concurrency revision for candidate portal offer.",
          "example": 1
        },
        "canRespond": {
          "type": "boolean",
          "description": "Whether the caller can respond through candidate portal offer.",
          "example": true
        }
      },
      "required": [
        "id",
        "status",
        "legalEntity",
        "venue",
        "classification",
        "contractType",
        "startDate",
        "terms",
        "revision",
        "canRespond"
      ],
      "example": {
        "id": "dfa73755-b161-462c-87aa-7f0d20d8a424",
        "status": "DRAFT",
        "legalEntity": {
          "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
          "name": "Example name"
        },
        "venue": {
          "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
          "name": "Example name"
        },
        "classification": "EMPLOYEE",
        "contractType": "FULL_TIME",
        "startDate": "2026-01-15",
        "terms": "example",
        "revision": 1,
        "canRespond": true
      }
    },
    "canWithdraw": {
      "type": "boolean",
      "description": "Whether the caller can withdraw through candidate portal application.",
      "example": true
    }
  },
  "required": [
    "id",
    "requisitionTitle",
    "currentStage",
    "status",
    "appliedAt",
    "updatedAt",
    "revision",
    "canWithdraw"
  ],
  "description": "Candidate-owned application in its withdrawn terminal stage with the updated revision and preserved submission evidence.",
  "example": {
    "id": "0120f0fe-6880-47e8-895d-c092d269cdd1",
    "requisitionTitle": "Example title",
    "currentStage": {
      "id": "f97fe865-5ff8-488a-8fab-9e27e748514c",
      "code": "EXAMPLE",
      "name": "Example name",
      "category": "APPLIED",
      "isTerminal": true,
      "sortOrder": 1,
      "revision": 1
    },
    "status": "ACTIVE",
    "appliedAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T13:00:00.000Z",
    "revision": 1,
    "canWithdraw": true
  }
}
RecruitingStageDto

Recruiting stage ordered workflow stage with its category and terminal-state semantics.

idRequired

Hallify UUID identifying recruiting stage.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Hallify UUID identifying recruiting stage.",
  "example": "f97fe865-5ff8-488a-8fab-9e27e748514c"
}
codeRequired

Stable code used to classify or address recruiting stage.

string
Full definition
{
  "type": "string",
  "description": "Stable code used to classify or address recruiting stage.",
  "example": "EXAMPLE"
}
nameRequired

Human-readable name for recruiting stage.

string
Full definition
{
  "type": "string",
  "description": "Human-readable name for recruiting stage.",
  "example": "Example name"
}
categoryRequired

Allowed category for recruiting stage: APPLIED, SCREENING, INTERVIEW, ASSESSMENT, OFFER, HIRED, REJECTED, WITHDRAWN.

string
Full definition
{
  "type": "string",
  "enum": [
    "APPLIED",
    "SCREENING",
    "INTERVIEW",
    "ASSESSMENT",
    "OFFER",
    "HIRED",
    "REJECTED",
    "WITHDRAWN"
  ],
  "description": "Allowed category for recruiting stage: APPLIED, SCREENING, INTERVIEW, ASSESSMENT, OFFER, HIRED, REJECTED, WITHDRAWN.",
  "example": "APPLIED"
}
isTerminalRequired

True when recruiting stage is a terminal recruiting stage from which the candidate does not advance automatically.

boolean
Full definition
{
  "type": "boolean",
  "description": "True when recruiting stage is a terminal recruiting stage from which the candidate does not advance automatically.",
  "example": true
}
sortOrderRequired

Whole-number ordering position for sort order in recruiting stage; smaller values sort first.

integer
Full definition
{
  "type": "integer",
  "description": "Whole-number ordering position for sort order in recruiting stage; smaller values sort first.",
  "example": 1
}
revisionRequired

Monotonic optimistic-concurrency revision for recruiting stage.

integer
Full definition
{
  "type": "integer",
  "description": "Monotonic optimistic-concurrency revision for recruiting stage.",
  "example": 1
}
Full definition
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying recruiting stage.",
      "example": "f97fe865-5ff8-488a-8fab-9e27e748514c"
    },
    "code": {
      "type": "string",
      "description": "Stable code used to classify or address recruiting stage.",
      "example": "EXAMPLE"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name for recruiting stage.",
      "example": "Example name"
    },
    "category": {
      "type": "string",
      "enum": [
        "APPLIED",
        "SCREENING",
        "INTERVIEW",
        "ASSESSMENT",
        "OFFER",
        "HIRED",
        "REJECTED",
        "WITHDRAWN"
      ],
      "description": "Allowed category for recruiting stage: APPLIED, SCREENING, INTERVIEW, ASSESSMENT, OFFER, HIRED, REJECTED, WITHDRAWN.",
      "example": "APPLIED"
    },
    "isTerminal": {
      "type": "boolean",
      "description": "True when recruiting stage is a terminal recruiting stage from which the candidate does not advance automatically.",
      "example": true
    },
    "sortOrder": {
      "type": "integer",
      "description": "Whole-number ordering position for sort order in recruiting stage; smaller values sort first.",
      "example": 1
    },
    "revision": {
      "type": "integer",
      "description": "Monotonic optimistic-concurrency revision for recruiting stage.",
      "example": 1
    }
  },
  "required": [
    "id",
    "code",
    "name",
    "category",
    "isTerminal",
    "sortOrder",
    "revision"
  ],
  "description": "Recruiting stage ordered workflow stage with its category and terminal-state semantics.",
  "example": {
    "id": "f97fe865-5ff8-488a-8fab-9e27e748514c",
    "code": "EXAMPLE",
    "name": "Example name",
    "category": "APPLIED",
    "isTerminal": true,
    "sortOrder": 1,
    "revision": 1
  }
}
RecruitingReferenceItemDto

Recruiting reference entry embedded in a workforce collection or aggregate.

idRequired

Hallify UUID identifying recruiting reference item.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Hallify UUID identifying recruiting reference item.",
  "example": "ba0372fd-c434-407b-8ec5-0634b02050cc"
}
nameRequired

Human-readable name for recruiting reference item.

string
Full definition
{
  "type": "string",
  "description": "Human-readable name for recruiting reference item.",
  "example": "Example name"
}
codeOptional

Stable code used to classify or address recruiting reference item. Null means no value is recorded for this representation.

string · null
Full definition
{
  "type": "string",
  "nullable": true,
  "description": "Stable code used to classify or address recruiting reference item. Null means no value is recorded for this representation.",
  "example": "EXAMPLE"
}
Full definition
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying recruiting reference item.",
      "example": "ba0372fd-c434-407b-8ec5-0634b02050cc"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name for recruiting reference item.",
      "example": "Example name"
    },
    "code": {
      "type": "string",
      "nullable": true,
      "description": "Stable code used to classify or address recruiting reference item. Null means no value is recorded for this representation.",
      "example": "EXAMPLE"
    }
  },
  "required": [
    "id",
    "name"
  ],
  "description": "Recruiting reference entry embedded in a workforce collection or aggregate.",
  "example": {
    "id": "ba0372fd-c434-407b-8ec5-0634b02050cc",
    "name": "Example name"
  }
}
TranslatedErrorDto

Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.

statusCodeRequired

HTTP status code repeated from the response.

integer
Full definition
{
  "type": "integer",
  "description": "HTTP status code repeated from the response.",
  "example": 400
}
errorRequired

Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.

string
Full definition
{
  "type": "string",
  "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
  "example": "errors.request.invalid"
}
codeRequired

Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions.

string
Full definition
{
  "type": "string",
  "example": "HTTP_BAD_REQUEST",
  "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
}
messageRequired

Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.

string
Full definition
{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
}
translationKeyRequired

Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback.

string
Full definition
{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full definition
{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}
validationErrorsOptional

Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.

array
Full definition
{
  "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/ValidationErrorDto"
  },
  "example": [
    {
      "field": "email",
      "translationKey": "validation:isEmail",
      "code": "isEmail",
      "message": "validation:isEmail"
    }
  ]
}
detailsOptional

Optional domain-specific blocker or validation details

oneOf
Full definition
{
  "description": "Optional domain-specific blocker or validation details",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "example": [
    "example"
  ]
}
Full definition
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "integer",
      "description": "HTTP status code repeated from the response.",
      "example": 400
    },
    "error": {
      "type": "string",
      "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
      "example": "errors.request.invalid"
    },
    "code": {
      "type": "string",
      "example": "HTTP_BAD_REQUEST",
      "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
    },
    "message": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
    },
    "translationKey": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    },
    "validationErrors": {
      "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorDto"
      },
      "example": [
        {
          "field": "email",
          "translationKey": "validation:isEmail",
          "code": "isEmail",
          "message": "validation:isEmail"
        }
      ]
    },
    "details": {
      "description": "Optional domain-specific blocker or validation details",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": [
            "example"
          ]
        },
        {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": {
            "exampleKey": "example"
          }
        }
      ],
      "example": [
        "example"
      ]
    }
  },
  "required": [
    "statusCode",
    "error",
    "code",
    "message",
    "translationKey"
  ],
  "description": "Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.",
  "example": {
    "statusCode": 400,
    "error": "errors:http.badRequest",
    "code": "HTTP_BAD_REQUEST",
    "message": "errors:http.badRequest",
    "translationKey": "errors:http.badRequest"
  }
}
ValidationErrorDto

Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.

fieldRequired

Public field path. Nested properties and array indices are separated by dots.

string
Full definition
{
  "type": "string",
  "example": "email",
  "description": "Public field path. Nested properties and array indices are separated by dots."
}
translationKeyRequired

Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.

string
Full definition
{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
}
codeRequired

Stable validator identifier for this field failure. Custom validators may define additional identifiers.

string
Full definition
{
  "type": "string",
  "example": "isEmail",
  "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
}
messageRequired

Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.

string
Full definition
{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full definition
{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}
Full definition
{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "example": "email",
      "description": "Public field path. Nested properties and array indices are separated by dots."
    },
    "translationKey": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
    },
    "code": {
      "type": "string",
      "example": "isEmail",
      "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
    },
    "message": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    }
  },
  "required": [
    "field",
    "translationKey",
    "code",
    "message"
  ],
  "description": "Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.",
  "example": {
    "field": "email",
    "translationKey": "validation:isEmail",
    "code": "isEmail",
    "message": "validation:isEmail"
  }
}
JsonValue

Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.

Full definition
{
  "oneOf": [
    {
      "type": "string",
      "nullable": true,
      "example": "example"
    },
    {
      "type": "number",
      "example": 0
    },
    {
      "type": "boolean",
      "example": true
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "description": "Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.",
  "example": "example"
}

Hallify uses essential cookies and optional analytics.

Essential cookies keep sign-in, locale, and theme preferences working. Analytics is off until you choose to allow it.