# Offer to assist candidates

Allows candidate service providers to offer assistance to one or more candidates. For example, to invite eligible candidate's to access specialised services for education, migration or settlement support.

Endpoint: POST /v1/candidates/offer-to-assist
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `candidates` (array)
    A list of candidate public IDs and optional coupon codes.

  - `candidates.publicId` (string, required)
    The unique public ID of the candidate.
    Example: "ABcd2EFgHIjkLMNOp3QR-S"

  - `candidates.couponCode` (string)
    An optional coupon code that the candidate may use for service access.
    Example: "COUPON2025"

  - `reason` (string)
    The reason for expressing interest in the candidate
    Enum: "JOB_OPPORTUNITY", "EDUCATION_SERVICE", "MIGRATION_SERVICE", "FINANCIAL_SUPPORT_SERVICE", "SETTLEMENT_SERVICE", "OTHER"

  - `additionalNotes` (string)
    Optional additional notes provided by the candidate service provider
    Example: "We would like to provide our services to these candidates."

## Response 201 fields (application/json):

  - `message` (string)
    Success message
    Example: "Your offer has been successfully recorded."

  - `offerId` (string)
    The unique ID for the offer to assist record
    Example: "interest-7890"

## Response 400 fields (application/problem+json):

  - `type` (string)
    A URI reference that identifies the problem type with a link to human-readable  documentation for the error.
    Example: "https://example.com/probs/doc"

  - `title` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Invalid Request"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "Request body is missing required fields."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"

## Response 401 fields (application/problem+json):

  - `type` (string)
    A URI reference that identifies the problem type with a link to human-readable  documentation for the error.
    Example: "https://example.com/probs/doc"

  - `title` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Authentication required"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 401

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "Invalid API key."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"

## Response 403 fields (application/problem+json):

  - `type` (string)
    A URI reference that identifies the problem type with a link to human-readable  documentation for the error.
    Example: "https://example.com/probs/doc"

  - `title` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Forbidden"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 403

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "You do not have permission to offer candidate services."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"

## Response 404 fields (application/problem+json):

  - `type` (string)
    A URI reference that identifies the problem type with a link to human-readable  documentation for the error.
    Example: "https://example.com/probs/doc"

  - `title` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Resource not found"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 404

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "Candidate with the provided publicId was not found."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"

## Response 500 fields (application/problem+json):

  - `type` (string)
    A URI reference that identifies the problem type with a link to human-readable  documentation for the error.
    Example: "https://example.com/probs/doc"

  - `title` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Service Unavailable"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 500

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "An unexpected error occurred. Please try again later."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"