Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Candidate portal

Respond to a candidate offer

POST/workforce/candidate-portal/offers/{offerId}/respond

Uses the Candidate Portal capability to accept or decline only the candidate-owned active offer identified by the route. The response is rejected after expiry or when the offer revision has changed.

Authentication

Authorization: Candidate <HALLIFY_CANDIDATE_PORTAL_TOKEN>

Candidate portal credential in Candidate <token> form.

Connection guide

Parameters

offerIdPath · Required

Hallify UUID whose ownership is validated against every parent tenant and aggregate in this route before the selected resource is exposed or changed.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "example": "9b6163a8-afea-4877-818b-8e2ae28a2845"
}

Request body

Required

Uses the Candidate Portal capability to accept or decline only the candidate-owned active offer identified by the route.

application/json

CandidateOfferResponseDto
Full definition
{
  "$ref": "#/components/schemas/CandidateOfferResponseDto"
}

Responses

200Candidate-owned application projection after recording the offer response, including the resulting stage and current revision.
CandidatePortalApplicationDto
Full definition
{
  "$ref": "#/components/schemas/CandidatePortalApplicationDto"
}
Example response · 200 · application/json
{
  "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
}
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

CandidateOfferResponseDto

Uses the Candidate Portal capability to accept or decline only the candidate-owned active offer identified by the route.

expectedRevisionRequired

Current integer revision read by the caller; a stale value rejects the mutation. Accepted values enforce minimum 1.

integer
Full definition
{
  "type": "integer",
  "minimum": 1,
  "description": "Current integer revision read by the caller; a stale value rejects the mutation. Accepted values enforce minimum 1.",
  "example": 1
}
commandKeyRequired

Hallify UUID identifying command key associated with candidate offer representation.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "description": "Hallify UUID identifying command key associated with candidate offer representation.",
  "example": "144a3af2-662b-401d-8893-0abf596c5088"
}
responseRequired

Allowed response for candidate offer representation: ACCEPT, DECLINE.

string
Full definition
{
  "type": "string",
  "enum": [
    "ACCEPT",
    "DECLINE"
  ],
  "description": "Allowed response for candidate offer representation: ACCEPT, DECLINE.",
  "example": "ACCEPT"
}
reasonOptional

Human-entered reason retained with candidate offer representation as decision or audit evidence. Accepted values enforce maximum length 500.

string
Full definition
{
  "type": "string",
  "maxLength": 500,
  "description": "Human-entered reason retained with candidate offer representation as decision or audit evidence. Accepted values enforce maximum length 500.",
  "example": "Synthetic example"
}
Full definition
{
  "type": "object",
  "properties": {
    "expectedRevision": {
      "type": "integer",
      "minimum": 1,
      "description": "Current integer revision read by the caller; a stale value rejects the mutation. Accepted values enforce minimum 1.",
      "example": 1
    },
    "commandKey": {
      "type": "string",
      "format": "uuid",
      "description": "Hallify UUID identifying command key associated with candidate offer representation.",
      "example": "144a3af2-662b-401d-8893-0abf596c5088"
    },
    "response": {
      "type": "string",
      "enum": [
        "ACCEPT",
        "DECLINE"
      ],
      "description": "Allowed response for candidate offer representation: ACCEPT, DECLINE.",
      "example": "ACCEPT"
    },
    "reason": {
      "type": "string",
      "maxLength": 500,
      "description": "Human-entered reason retained with candidate offer representation as decision or audit evidence. Accepted values enforce maximum length 500.",
      "example": "Synthetic example"
    }
  },
  "required": [
    "expectedRevision",
    "commandKey",
    "response"
  ],
  "description": "Uses the Candidate Portal capability to accept or decline only the candidate-owned active offer identified by the route.",
  "example": {
    "expectedRevision": 1,
    "commandKey": "144a3af2-662b-401d-8893-0abf596c5088",
    "response": "ACCEPT"
  }
}
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.