Create reference request

POST

/reference-requests

Maintainer:Not configured

Create a new reference request for a candidate. Use collection_mode: client_adds to provide referee details directly, or candidate_provides to email the candidate a link to submit their own referees.

When using client_adds, include the referees array with at least one referee. Each referee will immediately receive an email with a link to the reference form.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Admin adds referees directlyAsk candidate to provide referees

{
    "candidate_id": 12345,
    "collection_mode": "client_adds",
    "references_required": 2,
    "template_id": 1,
    "expiry_days": 30,
    "notes": "Urgent - start date next week",
    "referees": [
        {
            "referee_name": "Jane Smith",
            "referee_email": "jane.smith@company.com",
            "referee_organisation": "ABC Corp",
            "referee_position": "Line Manager",
            "referee_phone": "+44 7700 900000",
            "relationship_to_candidate": "Direct supervisor for 3 years"
        },
        {
            "referee_name": "Bob Johnson",
            "referee_email": "bob@another.com",
            "referee_organisation": "XYZ Ltd",
            "referee_position": "HR Director"
        }
    ]
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

cURL

Admin adds referees directlyAsk candidate to provide referees

curl --location --request POST '/reference-requests' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "candidate_id": 12345,
    "collection_mode": "client_adds",
    "references_required": 2,
    "template_id": 1,
    "expiry_days": 30,
    "notes": "Urgent - start date next week",
    "referees": [
        {
            "referee_name": "Jane Smith",
            "referee_email": "jane.smith@company.com",
            "referee_organisation": "ABC Corp",
            "referee_position": "Line Manager",
            "referee_phone": "+44 7700 900000",
            "relationship_to_candidate": "Direct supervisor for 3 years"
        },
        {
            "referee_name": "Bob Johnson",
            "referee_email": "bob@another.com",
            "referee_organisation": "XYZ Ltd",
            "referee_position": "HR Director"
        }
    ]
}'

Responses

🟢201

application/json

Reference request created

Body

Example

{
    "data": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "candidate_id": 0,
        "candidate_name": "John Doe",
        "candidate_email": "user@example.com",
        "template_id": 0,
        "template_name": "string",
        "collection_mode": "client_adds",
        "status": "pending",
        "status_label": "In Progress",
        "references_required": 2,
        "references_completed": 1,
        "is_fully_referenced": true,
        "notes": "string",
        "expires_at": "2019-08-24T14:15:22.123Z",
        "is_expired": true,
        "requested_by": 0,
        "submission_url": "string",
        "references": [
            {
                "id": 0,
                "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
                "reference_request_id": 0,
                "referee_name": "Jane Smith",
                "referee_email": "user@example.com",
                "referee_organisation": "ABC Corp",
                "referee_position": "Line Manager",
                "referee_phone": "string",
                "relationship_to_candidate": "string",
                "status": "pending",
                "status_label": "Completed",
                "score": 4.2,
                "decline_reason": "string",
                "form_url": "string",
                "pdf_url": "string",
                "sent_at": "2019-08-24T14:15:22.123Z",
                "opened_at": "2019-08-24T14:15:22.123Z",
                "submitted_at": "2019-08-24T14:15:22.123Z",
                "expires_at": "2019-08-24T14:15:22.123Z",
                "reminder_count": 0,
                "last_reminder_sent_at": "2019-08-24T14:15:22.123Z",
                "created_at": "2019-08-24T14:15:22.123Z",
                "updated_at": "2019-08-24T14:15:22.123Z"
            }
        ],
        "created_at": "2019-08-24T14:15:22.123Z",
        "updated_at": "2019-08-24T14:15:22.123Z"
    },
    "message": "string"
}

🟠403

🟠422

Modified at 2026-02-17 18:56:15

List reference requests

Get reference request