API Reference

ALLPS Talent AI Interview Backend 0.1.0

OpenAPI specification for the Interview endpoints and the outbound webhook management API.

Interview APIs cover creating, running and reading interviews.

Webhook management APIs let a client register a delivery URL and receive interview transcripts, evaluations and recording URLs once media processing completes. See GET /webhooks/catalog for the event contract and a sample payload.

All endpoints require the x-application-secret-key header.

---

Interview APIs

GET /interview/details/{interview_id}

Get Interview Details

Input parameters

Parameter	In	Type	Default	Nullable	Description
interview_id	path	string		No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "id": "0b6e751e-7e90-4eff-a454-c5d82fd192a7",
    "job_info": null,
    "allpsai_interview_id": null,
    "userip": null,
    "user": null,
    "call_api_id": null,
    "call_length": null,
    "feedback": null,
    "created_at": null,
    "next_question_index": 0,
    "state": 0,
    "user_disconnected": true,
    "language_code": 0,
    "archival_status": 0,
    "ending_reason": 0,
    "interview_type": 0,
    "interview_agent_meta": null,
    "resume_count": null,
    "transcript": null
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "job_info": {
            "title": "Job Info"
        },
        "allpsai_interview_id": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Allpsai Interview Id"
        },
        "userip": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Userip"
        },
        "user": {
            "title": "User"
        },
        "call_api_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Call Api Id"
        },
        "call_length": {
            "anyOf": [
                {
                    "type": "number"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Call Length"
        },
        "feedback": {
            "title": "Feedback"
        },
        "created_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Created At"
        },
        "next_question_index": {
            "type": "integer",
            "title": "Next Question Index",
            "default": 0
        },
        "state": {
            "type": "integer",
            "title": "State",
            "default": 0
        },
        "user_disconnected": {
            "type": "boolean",
            "title": "User Disconnected",
            "default": false
        },
        "language_code": {
            "type": "integer",
            "title": "Language Code",
            "default": 1
        },
        "archival_status": {
            "type": "integer",
            "title": "Archival Status",
            "default": 0
        },
        "ending_reason": {
            "type": "integer",
            "title": "Ending Reason",
            "default": 0
        },
        "interview_type": {
            "type": "integer",
            "title": "Interview Type",
            "default": 0
        },
        "interview_agent_meta": {
            "anyOf": [
                {
                    "additionalProperties": true,
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Interview Agent Meta"
        },
        "resume_count": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Resume Count"
        },
        "transcript": {
            "anyOf": [
                {
                    "items": {
                        "additionalProperties": true,
                        "type": "object"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Transcript"
        }
    },
    "additionalProperties": true,
    "type": "object",
    "required": [
        "id"
    ],
    "title": "InterviewDetailsResponse",
    "description": "Serialized representation of an interview record.\n\nWhen the caller sends the header `x-frontend: talentui`, an additional\n`transcript` array is appended to the payload. It is modelled here as\noptional. `extra=\"allow\"` keeps any peewee-specific fields that are added\nin future without breaking the contract."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /interview/create-from-questions

Create From Qs

Input parameters

Parameter	In	Type	Default	Nullable	Description
APIKeyHeader	header	string	N/A	No	API key
x-application-secret-key	header			No

Request body

application/json

{
    "job_title": "string",
    "candidate_id": "string",
    "language_code": 0,
    "questions": [
        {
            "question": "string",
            "evaluation_criteria": [
                "string"
            ],
            "sample_answer": null,
            "type": "technical"
        }
    ],
    "experience_level": "junior",
    "difficulty_level": "easy",
    "primary_tech_focus": "string"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "job_title": {
            "type": "string",
            "title": "Job Title",
            "description": "Title of the job for which this interview is being conducted"
        },
        "candidate_id": {
            "type": "string",
            "title": "Candidate Id"
        },
        "language_code": {
            "type": "integer",
            "title": "Language Code",
            "default": 1
        },
        "questions": {
            "items": {
                "$ref": "#/components/schemas/SkillInterviewQuestion"
            },
            "type": "array",
            "title": "Questions",
            "description": "List of questions to ask."
        },
        "experience_level": {
            "type": "string",
            "enum": [
                "junior",
                "senior",
                "assistant",
                "intern"
            ],
            "title": "Experience Level",
            "default": "junior"
        },
        "difficulty_level": {
            "type": "string",
            "enum": [
                "easy",
                "medium",
                "hard"
            ],
            "title": "Difficulty Level",
            "default": "easy"
        },
        "primary_tech_focus": {
            "type": "string",
            "title": "Primary Tech Focus",
            "description": "core domain focus of the interview."
        }
    },
    "type": "object",
    "required": [
        "job_title",
        "candidate_id",
        "questions",
        "primary_tech_focus"
    ],
    "title": "CreateInterviewFromQuestionsRequest"
}

Response 200 OK

application/json

{
    "message": "Interview created successfully",
    "interview_id": "0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b",
    "interview_link": "https://sandbox.tara.allps.ai/interview?iid=0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "message": {
            "type": "string",
            "title": "Message",
            "examples": [
                "Interview created successfully"
            ]
        },
        "interview_id": {
            "type": "string",
            "title": "Interview Id",
            "examples": [
                "0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b"
            ]
        },
        "interview_link": {
            "type": "string",
            "title": "Interview Link",
            "examples": [
                "https://sandbox.tara.allps.ai/interview?iid=0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b"
            ]
        }
    },
    "type": "object",
    "required": [
        "message",
        "interview_id",
        "interview_link"
    ],
    "title": "InterviewCreatedResponse",
    "description": "Returned by `create_interview_from_questions` when a new interview is\nbuilt from a caller-supplied question list."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /interview/screening/create-from-questions

Create Screening Interview From Qs

Input parameters

Parameter	In	Type	Default	Nullable	Description
APIKeyHeader	header	string	N/A	No	API key
x-application-secret-key	header			No

Request body

application/json

{
    "job_title": "string",
    "candidate_id": "string",
    "interview_lang_code": 0,
    "questions": [
        {
            "question_text": "string",
            "question_type": "information",
            "asking_order": 0,
            "qualifying_criteria": null
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "job_title": {
            "type": "string",
            "title": "Job Title",
            "description": "Title of the job for which this interview is being conducted"
        },
        "candidate_id": {
            "type": "string",
            "title": "Candidate Id"
        },
        "interview_lang_code": {
            "type": "integer",
            "title": "Interview Lang Code",
            "default": 1
        },
        "questions": {
            "items": {
                "$ref": "#/components/schemas/ScreeningQuestionSchema"
            },
            "type": "array",
            "title": "Questions",
            "description": "List of questions to ask."
        }
    },
    "type": "object",
    "required": [
        "job_title",
        "candidate_id",
        "questions"
    ],
    "title": "ScreeningInterviewATSCreateRequest"
}

Response 200 OK

application/json

{
    "message": "Interview created successfully",
    "interview_id": "0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b",
    "interview_link": "https://sandbox.tara.allps.ai/interview?iid=0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "message": {
            "type": "string",
            "title": "Message",
            "examples": [
                "Interview created successfully"
            ]
        },
        "interview_id": {
            "type": "string",
            "title": "Interview Id",
            "examples": [
                "0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b"
            ]
        },
        "interview_link": {
            "type": "string",
            "title": "Interview Link",
            "examples": [
                "https://sandbox.tara.allps.ai/interview?iid=0f2b8c6e-4c9b-4d1a-9b2f-0f2b8c6e4c9b"
            ]
        }
    },
    "type": "object",
    "required": [
        "message",
        "interview_id",
        "interview_link"
    ],
    "title": "InterviewCreatedResponse",
    "description": "Returned by `create_interview_from_questions` when a new interview is\nbuilt from a caller-supplied question list."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /interview/reset/{interview_id}

Reset Interview Details

Input parameters

Parameter	In	Type	Default	Nullable	Description
interview_id	path	string		No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "success": true,
    "message": "interview reset. You can retake it"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "success": {
            "type": "boolean",
            "title": "Success",
            "examples": [
                true
            ]
        },
        "message": {
            "type": "string",
            "title": "Message",
            "examples": [
                "interview reset. You can retake it"
            ]
        }
    },
    "type": "object",
    "required": [
        "success",
        "message"
    ],
    "title": "InterviewResetResponse",
    "description": "Result of resetting an interview so it can be retaken. Only available\nin non-production environments."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /interview/evaluation-report/{interview_id}

Get Interview Evaluation Report

Input parameters

Parameter	In	Type	Default	Nullable	Description
interview_id	path	string		No
locale	header	string	en	No
x-application-secret-key	header			No

Response 200 OK

application/json

Schema of the response body

{
    "anyOf": [
        {
            "$ref": "#/components/schemas/OverallEvaluation"
        },
        {
            "$ref": "#/components/schemas/InterviewEvaluationReportResponse"
        }
    ],
    "title": "Response  Get Interview Evaluation Report Interview Evaluation Report  Interview Id  Get"
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /interview/transcript/{interview_id}

Get Interview Transcript

Input parameters

Parameter	In	Type	Default	Nullable	Description
interview_id	path	string		No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "transcript": [
        {
            "role": "string",
            "content": "string",
            "created_at": "string",
            "control_id": null,
            "video_time": null
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "transcript": {
            "items": {
                "$ref": "#/components/schemas/InterviewTranscriptEntry"
            },
            "type": "array",
            "title": "Transcript"
        }
    },
    "type": "object",
    "title": "InterviewTranscriptResponse"
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /interview/overall-evaluation-report/{interview_id}

Get Overall Interview Evaluation Report

Input parameters

Parameter	In	Type	Default	Nullable	Description
interview_id	path	string		No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "overall_assessment": {
        "suitability": null,
        "strengths": [
            "string"
        ],
        "weaknesses": [
            "string"
        ],
        "recommendations": [
            "string"
        ]
    }
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "overall_assessment": {
            "$ref": "#/components/schemas/OverallAssessment"
        }
    },
    "additionalProperties": true,
    "type": "object",
    "required": [
        "overall_assessment"
    ],
    "title": "OverallEvaluation",
    "description": "Short-form payload returned by `/overall-evaluation-report/{id}` and by\n`/evaluation-report/{id}` for JOB interviews (`interview_type == 0`)."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /interview/get-recording/{interview_id}

Get Rcording

Input parameters

Parameter	In	Type	Default	Nullable	Description
interview_id	path	string		No
locale	header	string	en	No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "interview_recording": "https://sonny-assets.s3.eu-central-1.amazonaws.com/.../_recording.mp3"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "interview_recording": {
            "type": "string",
            "title": "Interview Recording",
            "examples": [
                "https://sonny-assets.s3.eu-central-1.amazonaws.com/.../_recording.mp3"
            ]
        }
    },
    "type": "object",
    "required": [
        "interview_recording"
    ],
    "title": "InterviewRecordingResponse"
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /interview/get-logs/{interview_id}

Get Int Logs

Input parameters

Parameter	In	Type	Default	Nullable	Description
interview_id	path	string		No
locale	header	string	en	No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "interview_logs": "string"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "interview_logs": {
            "type": "string",
            "title": "Interview Logs",
            "description": "Either a presigned S3 URL (if logs have been archived) or the raw log text (if served from local disk)."
        }
    },
    "type": "object",
    "required": [
        "interview_logs"
    ],
    "title": "InterviewLogsResponse"
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /interview/get-video-recording/{interview_id}

Get Video Recording

Input parameters

Parameter	In	Type	Default	Nullable	Description
interview_id	path	string		No
locale	header	string	en	No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "interview_video_recording": "https://sonny-assets.s3.eu-central-1.amazonaws.com/.../_video_recording.webm"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "interview_video_recording": {
            "type": "string",
            "title": "Interview Video Recording",
            "examples": [
                "https://sonny-assets.s3.eu-central-1.amazonaws.com/.../_video_recording.webm"
            ]
        }
    },
    "type": "object",
    "required": [
        "interview_video_recording"
    ],
    "title": "InterviewVideoRecordingResponse"
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

Webhook management APIs

GET /webhooks/catalog

Describe the webhook contract

Description Events, interview kinds and a sample payload -- no guessing required.

Input parameters

Parameter	In	Type	Default	Nullable	Description
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "schema_version": "string",
    "events": [
        {
            "event": "string",
            "description": "string"
        }
    ],
    "interview_types": {},
    "interview_kinds": [
        "string"
    ],
    "signature_header": "string",
    "payload_contracts": [
        {
            "interview_type": 0,
            "kind": "string",
            "description": "string",
            "evaluation_present": true,
            "evaluation_fields": [
                "string"
            ],
            "communication_analysis_present": true,
            "sample_payload_key": "string"
        }
    ],
    "sample_payloads": {
        "interview_media_processed": {
            "job_interview": {
                "schema_version": "string",
                "event": "string",
                "event_id": "string",
                "occurred_at": "string",
                "interview": {
                    "id": "string",
                    "kind": "string",
                    "interview_type": null,
                    "allpsai_interview_id": null,
                    "language_code": null,
                    "state": null,
                    "ending_reason": null,
                    "archival_status": null,
                    "duration_secs": null,
                    "created_at": null,
                    "user_id": null,
                    "job_info_id": null,
                    "has_video": true
                },
                "media": {
                    "audio_url": "string",
                    "video_url": "string"
                },
                "transcript": [
                    {
                        "role": "string",
                        "content": "string",
                        "created_at": null,
                        "control_id": null,
                        "video_time": null
                    }
                ],
                "evaluation": {
                    "kind": "string",
                    "overall_summary": null,
                    "primary_tech_focus": null,
                    "experience_level": null,
                    "questions": [
                        {
                            "question": null,
                            "question_type": null,
                            "transcript": [
                                {}
                            ],
                            "evaluation": null,
                            "video_timeline": null,
                            "category": null,
                            "is_evaluated": null,
                            "eval_criteria": null
                        }
                    ],
                    "summary": {}
                },
                "communication_analysis": {
                    "type": "null",
                    "title": "Communication Analysis",
                    "description": "Only populated for screening interviews; null here."
                },
                "metrics": {
                    "attempted_questions_count": null,
                    "transcript_turns": 0
                }
            },
            "screening_interview": {
                "schema_version": "string",
                "event": "string",
                "event_id": "string",
                "occurred_at": "string",
                "interview": null,
                "media": null,
                "transcript": null,
                "evaluation": {
                    "kind": "string",
                    "overall_summary": {
                        "type": "null",
                        "title": "Overall Summary",
                        "description": "Always null for screening interviews."
                    },
                    "primary_tech_focus": {
                        "type": "null",
                        "title": "Primary Tech Focus",
                        "description": "Always null for screening interviews."
                    },
                    "experience_level": {
                        "type": "null",
                        "title": "Experience Level",
                        "description": "Always null for screening interviews."
                    },
                    "questions": null,
                    "qualifying_questions": null,
                    "information_questions": null,
                    "summary": {}
                },
                "communication_analysis": null,
                "metrics": null
            },
            "video_introduction": {
                "schema_version": "string",
                "event": "string",
                "event_id": "string",
                "occurred_at": "string",
                "interview": null,
                "media": null,
                "transcript": null,
                "evaluation": {
                    "type": "null",
                    "title": "Evaluation",
                    "description": "Always null for video introductions."
                },
                "communication_analysis": {
                    "type": "null",
                    "title": "Communication Analysis",
                    "description": "Always null for video introductions."
                },
                "metrics": null
            }
        },
        "webhook_test": {
            "schema_version": "string",
            "event": "string",
            "event_id": "string",
            "occurred_at": "string",
            "interview": {
                "type": "null",
                "title": "Interview"
            },
            "media": {
                "type": "null",
                "title": "Media"
            },
            "transcript": [
                null
            ],
            "evaluation": {
                "type": "null",
                "title": "Evaluation"
            },
            "communication_analysis": {
                "type": "null",
                "title": "Communication Analysis"
            },
            "metrics": {}
        }
    }
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "schema_version": {
            "type": "string",
            "title": "Schema Version",
            "description": "Version of the payload contract; bumped on breaking changes."
        },
        "events": {
            "items": {
                "$ref": "#/components/schemas/WebhookEventCatalogEntry"
            },
            "type": "array",
            "title": "Events",
            "description": "Events that can be delivered to a registered endpoint."
        },
        "interview_types": {
            "additionalProperties": {
                "type": "integer"
            },
            "type": "object",
            "title": "Interview Types",
            "description": "Mapping of interview kind name to numeric interview type code."
        },
        "interview_kinds": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Interview Kinds",
            "description": "Every value that can appear in `interview.kind`."
        },
        "signature_header": {
            "type": "string",
            "title": "Signature Header",
            "description": "HTTP header carrying the HMAC-SHA256 signature."
        },
        "payload_contracts": {
            "items": {
                "$ref": "#/components/schemas/InterviewTypePayloadContract"
            },
            "type": "array",
            "title": "Payload Contracts",
            "description": "Per-interview-type description of which payload shape and fields are delivered. Every entry in this list maps to one example under `sample_payloads.interview_media_processed`."
        },
        "sample_payloads": {
            "$ref": "#/components/schemas/WebhookSamplePayloads",
            "description": "Example payloads grouped by event and, for `interview.media_processed`, by interview kind."
        }
    },
    "type": "object",
    "required": [
        "schema_version",
        "events",
        "signature_header",
        "sample_payloads"
    ],
    "title": "WebhookCatalog",
    "description": "Self-describing catalogue so a client can discover the contract.\n\nThe payload envelope is identical for every interview type; only the\n``evaluation`` (and, for screening, ``communication_analysis``) sections\ndiffer. ``payload_contracts`` spells out which shape applies to which\ninterview type, and ``sample_payloads`` holds a fully-formed example of\neach one."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /webhooks/endpoints

Register a webhook URL

Description Register a delivery URL.

The response contains the HMAC signing secret. This is the only time it is returned in full, so store it before discarding the response.

Input parameters

Parameter	In	Type	Default	Nullable	Description
x-application-secret-key	header			No

Request body

application/json

{
    "url": "string",
    "name": "string",
    "description": null,
    "interview_type": null,
    "event_types": null,
    "is_active": true
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "url": {
            "type": "string",
            "maxLength": 2048,
            "title": "Url",
            "description": "Absolute http(s) URL that will receive events."
        },
        "name": {
            "type": "string",
            "maxLength": 120,
            "title": "Name",
            "description": "Label to tell endpoints apart.",
            "default": "Default webhook"
        },
        "description": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Description",
            "description": "Free-form note for your own reference."
        },
        "interview_type": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Interview Type",
            "description": "Restrict delivery to one interview type. 0=job, 1=screening, 2=video introduction. Omit for all."
        },
        "event_types": {
            "anyOf": [
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Event Types",
            "description": "Restrict delivery to these events. Omit for all. Supported: ['interview.media_processed']"
        },
        "is_active": {
            "type": "boolean",
            "title": "Is Active",
            "description": "Inactive endpoints are skipped during dispatch.",
            "default": true
        }
    },
    "type": "object",
    "required": [
        "url"
    ],
    "title": "WebhookEndpointCreate",
    "description": "Register a new delivery URL."
}

Response 201 Created

application/json

{
    "id": "string",
    "url": "string",
    "name": "string",
    "description": null,
    "interview_type": null,
    "event_types": null,
    "is_active": true,
    "secret_masked": "string",
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": null,
    "updated_at": null,
    "secret": "string"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "title": "Id"
        },
        "url": {
            "type": "string",
            "title": "Url"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "description": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Description"
        },
        "interview_type": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Interview Type"
        },
        "event_types": {
            "anyOf": [
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Event Types"
        },
        "is_active": {
            "type": "boolean",
            "title": "Is Active",
            "default": true
        },
        "secret_masked": {
            "type": "string",
            "title": "Secret Masked",
            "description": "First 6 characters of the secret, for identification only.",
            "default": ""
        },
        "last_success_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Success At"
        },
        "last_failure_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Failure At"
        },
        "created_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Created At"
        },
        "updated_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Updated At"
        },
        "secret": {
            "type": "string",
            "title": "Secret",
            "description": "HMAC-SHA256 signing secret. Store it securely; it is not shown again."
        }
    },
    "type": "object",
    "required": [
        "id",
        "url",
        "name",
        "secret"
    ],
    "title": "WebhookEndpointCreated",
    "description": "Returned only on create/rotate. This is the one time the secret is shown."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /webhooks/endpoints

List your webhook URLs

Input parameters

Parameter	In	Type	Default	Nullable	Description
is_active	query			No	Filter by active state.
limit	query	integer	100	No
offset	query	integer	0	No
x-application-secret-key	header			No

Response 200 OK

application/json

[
    {
        "id": "string",
        "url": "string",
        "name": "string",
        "description": null,
        "interview_type": null,
        "event_types": null,
        "is_active": true,
        "secret_masked": "string",
        "last_success_at": null,
        "last_failure_at": null,
        "created_at": null,
        "updated_at": null
    }
]

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/WebhookEndpointRead"
    },
    "title": "Response  List Webhook Endpoints Webhooks Endpoints Get"
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /webhooks/endpoints/{endpoint_id}

Fetch one webhook URL

Input parameters

Parameter	In	Type	Default	Nullable	Description
endpoint_id	path	string		No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "id": "string",
    "url": "string",
    "name": "string",
    "description": null,
    "interview_type": null,
    "event_types": null,
    "is_active": true,
    "secret_masked": "string",
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": null,
    "updated_at": null
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "title": "Id"
        },
        "url": {
            "type": "string",
            "title": "Url"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "description": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Description"
        },
        "interview_type": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Interview Type"
        },
        "event_types": {
            "anyOf": [
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Event Types"
        },
        "is_active": {
            "type": "boolean",
            "title": "Is Active",
            "default": true
        },
        "secret_masked": {
            "type": "string",
            "title": "Secret Masked",
            "description": "First 6 characters of the secret, for identification only.",
            "default": ""
        },
        "last_success_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Success At"
        },
        "last_failure_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Failure At"
        },
        "created_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Created At"
        },
        "updated_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Updated At"
        }
    },
    "type": "object",
    "required": [
        "id",
        "url",
        "name"
    ],
    "title": "WebhookEndpointRead",
    "description": "An endpoint as returned by the API. The signing secret is masked."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

PATCH /webhooks/endpoints/{endpoint_id}

Update a webhook URL

Description Partial update. Omitted fields are left untouched.

Input parameters

Parameter	In	Type	Default	Nullable	Description
endpoint_id	path	string		No
x-application-secret-key	header			No

Request body

application/json

{
    "url": null,
    "name": null,
    "description": null,
    "interview_type": null,
    "event_types": null,
    "is_active": null
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "url": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 2048
                },
                {
                    "type": "null"
                }
            ],
            "title": "Url"
        },
        "name": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 120
                },
                {
                    "type": "null"
                }
            ],
            "title": "Name"
        },
        "description": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Description"
        },
        "interview_type": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Interview Type"
        },
        "event_types": {
            "anyOf": [
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Event Types"
        },
        "is_active": {
            "anyOf": [
                {
                    "type": "boolean"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Is Active"
        }
    },
    "type": "object",
    "title": "WebhookEndpointUpdate",
    "description": "Partial update. Only the provided fields are changed."
}

Response 200 OK

application/json

{
    "id": "string",
    "url": "string",
    "name": "string",
    "description": null,
    "interview_type": null,
    "event_types": null,
    "is_active": true,
    "secret_masked": "string",
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": null,
    "updated_at": null
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "title": "Id"
        },
        "url": {
            "type": "string",
            "title": "Url"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "description": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Description"
        },
        "interview_type": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Interview Type"
        },
        "event_types": {
            "anyOf": [
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Event Types"
        },
        "is_active": {
            "type": "boolean",
            "title": "Is Active",
            "default": true
        },
        "secret_masked": {
            "type": "string",
            "title": "Secret Masked",
            "description": "First 6 characters of the secret, for identification only.",
            "default": ""
        },
        "last_success_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Success At"
        },
        "last_failure_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Failure At"
        },
        "created_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Created At"
        },
        "updated_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Updated At"
        }
    },
    "type": "object",
    "required": [
        "id",
        "url",
        "name"
    ],
    "title": "WebhookEndpointRead",
    "description": "An endpoint as returned by the API. The signing secret is masked."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

DELETE /webhooks/endpoints/{endpoint_id}

Delete a webhook URL

Description Remove the endpoint. Delivery history is retained for auditing.

Input parameters

Parameter	In	Type	Default	Nullable	Description
endpoint_id	path	string		No
x-application-secret-key	header			No

Response 204 No Content

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /webhooks/endpoints/{endpoint_id}/rotate-secret

Rotate the signing secret

Description Issue a new signing secret. The previous one stops working immediately.

Input parameters

Parameter	In	Type	Default	Nullable	Description
endpoint_id	path	string		No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "id": "string",
    "url": "string",
    "name": "string",
    "description": null,
    "interview_type": null,
    "event_types": null,
    "is_active": true,
    "secret_masked": "string",
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": null,
    "updated_at": null,
    "secret": "string"
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "title": "Id"
        },
        "url": {
            "type": "string",
            "title": "Url"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "description": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Description"
        },
        "interview_type": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Interview Type"
        },
        "event_types": {
            "anyOf": [
                {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Event Types"
        },
        "is_active": {
            "type": "boolean",
            "title": "Is Active",
            "default": true
        },
        "secret_masked": {
            "type": "string",
            "title": "Secret Masked",
            "description": "First 6 characters of the secret, for identification only.",
            "default": ""
        },
        "last_success_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Success At"
        },
        "last_failure_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Failure At"
        },
        "created_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Created At"
        },
        "updated_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Updated At"
        },
        "secret": {
            "type": "string",
            "title": "Secret",
            "description": "HMAC-SHA256 signing secret. Store it securely; it is not shown again."
        }
    },
    "type": "object",
    "required": [
        "id",
        "url",
        "name",
        "secret"
    ],
    "title": "WebhookEndpointCreated",
    "description": "Returned only on create/rotate. This is the one time the secret is shown."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /webhooks/endpoints/{endpoint_id}/test

Send a test event

Description Deliver a synthetic webhook.test event and report the attempt result.

Runs inline so you get the HTTP status and any error straight back, and the attempt is recorded in the delivery history like any other.

Input parameters

Parameter	In	Type	Default	Nullable	Description
endpoint_id	path	string		No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "endpoint_id": "string",
    "delivery": {
        "id": "string",
        "endpoint_id": null,
        "interview_id": null,
        "event": "string",
        "event_id": "string",
        "target_url": "string",
        "status": 0,
        "status_name": "string",
        "attempts": 0,
        "max_attempts": 0,
        "response_status": null,
        "error": null,
        "created_at": null,
        "delivered_at": null
    },
    "success": true,
    "detail": null
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "endpoint_id": {
            "type": "string",
            "title": "Endpoint Id"
        },
        "delivery": {
            "$ref": "#/components/schemas/WebhookDeliveryRead"
        },
        "success": {
            "type": "boolean",
            "title": "Success"
        },
        "detail": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Detail"
        }
    },
    "type": "object",
    "required": [
        "endpoint_id",
        "delivery",
        "success"
    ],
    "title": "WebhookTestResult"
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

GET /webhooks/deliveries

Inspect delivery history

Input parameters

Parameter	In	Type	Default	Nullable	Description
endpoint_id	query			No	Restrict to one endpoint.
interview_id	query			No	Restrict to one interview.
limit	query	integer	50	No
offset	query	integer	0	No
status	query			No	0=pending 1=delivering 2=success 3=failed
x-application-secret-key	header			No

Response 200 OK

application/json

[
    {
        "id": "string",
        "endpoint_id": null,
        "interview_id": null,
        "event": "string",
        "event_id": "string",
        "target_url": "string",
        "status": 0,
        "status_name": "string",
        "attempts": 0,
        "max_attempts": 0,
        "response_status": null,
        "error": null,
        "created_at": null,
        "delivered_at": null
    }
]

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/WebhookDeliveryRead"
    },
    "title": "Response  List Webhook Deliveries Webhooks Deliveries Get"
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

POST /webhooks/deliveries/{delivery_id}/redeliver

Replay a delivery

Description Replay a stored delivery using the exact original payload.

Input parameters

Parameter	In	Type	Default	Nullable	Description
delivery_id	path	string		No
x-application-secret-key	header			No

Response 200 OK

application/json

{
    "id": "string",
    "endpoint_id": null,
    "interview_id": null,
    "event": "string",
    "event_id": "string",
    "target_url": "string",
    "status": 0,
    "status_name": "string",
    "attempts": 0,
    "max_attempts": 0,
    "response_status": null,
    "error": null,
    "created_at": null,
    "delivered_at": null
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "title": "Id"
        },
        "endpoint_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Endpoint Id"
        },
        "interview_id": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Interview Id"
        },
        "event": {
            "type": "string",
            "title": "Event"
        },
        "event_id": {
            "type": "string",
            "title": "Event Id"
        },
        "target_url": {
            "type": "string",
            "title": "Target Url"
        },
        "status": {
            "type": "integer",
            "title": "Status"
        },
        "status_name": {
            "type": "string",
            "title": "Status Name"
        },
        "attempts": {
            "type": "integer",
            "title": "Attempts"
        },
        "max_attempts": {
            "type": "integer",
            "title": "Max Attempts"
        },
        "response_status": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Response Status"
        },
        "error": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Error"
        },
        "created_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Created At"
        },
        "delivered_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Delivered At"
        }
    },
    "type": "object",
    "required": [
        "id",
        "event",
        "event_id",
        "target_url",
        "status",
        "status_name",
        "attempts",
        "max_attempts"
    ],
    "title": "WebhookDeliveryRead",
    "description": "Delivery attempt record, for observability and troubleshooting."
}

Response 422 Unprocessable Content

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

Schemas

CreateInterviewFromQuestionsRequest

Name	Type	Description
candidate_id	string
difficulty_level	string
experience_level	string
job_title	string	Title of the job for which this interview is being conducted
language_code	integer
primary_tech_focus	string	core domain focus of the interview.
questions	Array<SkillInterviewQuestion>	List of questions to ask.

EvaluatedQuestion

Name	Type	Description
category		Screening only: 'qualifying' (graded) or 'information' (recorded only).
eval_criteria		Screening only: criteria used to grade a qualifying question.
evaluation		Per-question grading result. For job interviews this is an object with rating and improvement_points. For screening qualifying questions this is an object with outcome and analysis.
is_evaluated		Screening only: True for qualifying questions.
question		The question text.
question_type		Question classification, e.g. 'technical', 'behavioral', 'qualifying', 'information'.
transcript	Array<>	Interleaved interviewer/candidate exchange for this question.
video_timeline		Position of this question on the recording.

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

InterviewCreatedResponse

Name	Type	Description
interview_id	string
interview_link	string
message	string

InterviewDetailsResponse

Name	Type	Description
allpsai_interview_id
archival_status	integer
call_api_id
call_length
created_at
ending_reason	integer
feedback
id	string(uuid)
interview_agent_meta
interview_type	integer
job_info
language_code	integer
next_question_index	integer
resume_count
state	integer
transcript
user
user_disconnected	boolean
userip

InterviewEvaluationReportResponse

Name	Type	Description
comm_analysis_report
created_at
evaluation_report
id	string(uuid)
interview
overall_evaluation
user
video_analysis_report

InterviewLogsResponse

Name	Type	Description
interview_logs	string	Either a presigned S3 URL (if logs have been archived) or the raw log text (if served from local disk).

InterviewRecordingResponse

Name	Type	Description
interview_recording	string

InterviewResetResponse

Name	Type	Description
message	string
success	boolean

InterviewSection

Name	Type	Description
allpsai_interview_id		Upstream interview id, when the interview originated from the talent platform.
archival_status		Recording archival status.
created_at		ISO-8601 timestamp of interview creation.
duration_secs		Recorded duration in seconds.
ending_reason		Why the interview ended.
has_video	boolean	True when media.video_url is populated.
id	string	Interview UUID.
interview_type		Numeric interview type code.
job_info_id		Job info UUID, when the interview is tied to a job.
kind	string	One of 'job_interview', 'screening_interview', 'video_introduction'.
language_code		Language the interview was conducted in.
state		Runtime state of the interview when the event fired.
user_id		Owning user UUID, or null for guest interviews.

InterviewTranscriptEntry

Name	Type	Description
content	string
control_id
created_at	string
role	string
video_time

InterviewTranscriptResponse

Name	Type	Description
transcript	Array<InterviewTranscriptEntry>

InterviewTypePayloadContract

Name	Type	Description
communication_analysis_present	boolean	Whether communication_analysis is populated for this interview type.
description	string	How this payload differs from the others.
evaluation_fields	Array<string>	Keys that are populated inside evaluation for this interview type. Job and screening payloads share the same envelope; screening adds qualifying_questions and information_questions. Video introductions have no evaluation at all.
evaluation_present	boolean	Whether the top-level evaluation section is populated.
interview_type	integer	Numeric interview type code (0 = job, 1 = screening, 2 = video introduction).
kind	string	Value of interview.kind used for this interview type.
sample_payload_key	string	Dot-path into sample_payloads pointing at an example of this payload, e.g. 'interview_media_processed.job_interview'.

InterviewVideoRecordingResponse

Name	Type	Description
interview_video_recording	string

JobInterviewEvaluationSection

Name	Type	Description
experience_level		Seniority level the interview was tuned for.
kind	string	Always 'job_interview'.
overall_summary		LLM-written overall assessment. Null if the summary could not be generated.
primary_tech_focus		Primary technology focus of the question set.
questions	Array<EvaluatedQuestion>	Every question with its per-question evaluation.
summary		Roll-up counts: {'total_questions': N, 'evaluated_questions': N}.

JobInterviewMediaProcessedPayload

Name	Type	Description
communication_analysis	null	Only populated for screening interviews; null here.
evaluation	JobInterviewEvaluationSection
event	string
event_id	string
interview	InterviewSection
media	MediaSection
metrics	MetricsSection
occurred_at	string
schema_version	string
transcript	Array<TranscriptEntry>

MediaProcessedSamplePayloads

Name	Type	Description
job_interview	JobInterviewMediaProcessedPayload	Example for interview_type = 0.
screening_interview	ScreeningInterviewMediaProcessedPayload	Example for interview_type = 1.
video_introduction	VideoIntroductionMediaProcessedPayload	Example for interview_type = 2.

MediaSection

Name	Type	Description
audio_url	string	S3 URL of the mixed audio recording. Empty string when no audio was captured.
video_url	string	S3 URL of the mixed video recording. Empty string when the interview had no video.

MetricsSection

Name	Type	Description
attempted_questions_count		How many questions the candidate actually reached.
transcript_turns	integer	Number of entries in the transcript array.

OverallAssessment

Name	Type	Description
recommendations	Array<string>
strengths	Array<string>
suitability
weaknesses	Array<string>

OverallEvaluation

Name	Type	Description
overall_assessment	OverallAssessment

ScreeningInterviewATSCreateRequest

Name	Type	Description
candidate_id	string
interview_lang_code	integer
job_title	string	Title of the job for which this interview is being conducted
questions	Array<ScreeningQuestionSchema>	List of questions to ask.

ScreeningInterviewEvaluationSection

Name	Type	Description
experience_level	null	Always null for screening interviews.
information_questions	Array<EvaluatedQuestion>	Subset of questions that were asked and recorded but never graded.
kind	string	Always 'screening_interview'.
overall_summary	null	Always null for screening interviews.
primary_tech_focus	null	Always null for screening interviews.
qualifying_questions	Array<EvaluatedQuestion>	Subset of questions whose answers were graded against explicit criteria.
questions	Array<EvaluatedQuestion>	Every question in original order, regardless of category.
summary		Roll-up counts including the qualifying/information/evaluated split.

ScreeningInterviewMediaProcessedPayload

Name	Type	Description
communication_analysis		Communication analysis (filler words, repetition, clarity). Null if the analysis failed.
evaluation	ScreeningInterviewEvaluationSection
event	string
event_id	string
interview	InterviewSection
media	MediaSection
metrics	MetricsSection
occurred_at	string
schema_version	string
transcript	Array<TranscriptEntry>

ScreeningQuestionSchema

Name	Type	Description
asking_order	integer	In which order this question must be asked
qualifying_criteria		if the question of qualifying type, simple text criteria of it's evaluation. Not required for information type questions
question_text	string	Question text
question_type	string	Information questions are not evaluated only recorded. qualifying questions are evaluated

SkillInterviewQuestion

Name	Type	Description
evaluation_criteria	Array<string>	list of key grading points.
question	string	Question text
sample_answer		A sample answer. Or the expected answer
type	string

TestEventPayload

Name	Type	Description
communication_analysis	null
evaluation	null
event	string
event_id	string
interview	null
media	null
metrics
occurred_at	string
schema_version	string
transcript	Array<>

TranscriptEntry

Name	Type	Description
content	string	The text of the utterance.
control_id		Identifier of the question this utterance belongs to, when applicable.
created_at		ISO-8601 timestamp of when the utterance was recorded.
role	string	Speaker: 'assistant' (the AI interviewer) or 'user' (the candidate).
video_time		Position of this utterance on the recording timeline.

ValidationError

Name	Type	Description
ctx
input
loc	Array<>
msg	string
type	string

VideoIntroductionMediaProcessedPayload

Name	Type	Description
communication_analysis	null	Always null for video introductions.
evaluation	null	Always null for video introductions.
event	string
event_id	string
interview	InterviewSection
media	MediaSection
metrics	MetricsSection
occurred_at	string
schema_version	string
transcript	Array<TranscriptEntry>

VideoTimeRange

Name	Type	Description
begin	integer	Start offset in seconds from the beginning of the recording.
end	integer	End offset in seconds from the beginning of the recording.
formatted	string	Human-readable 'MM:SS - MM:SS' rendering of the range.

WebhookCatalog

Name	Type	Description
events	Array<WebhookEventCatalogEntry>	Events that can be delivered to a registered endpoint.
interview_kinds	Array<string>	Every value that can appear in interview.kind.
interview_types		Mapping of interview kind name to numeric interview type code.
payload_contracts	Array<InterviewTypePayloadContract>	Per-interview-type description of which payload shape and fields are delivered. Every entry in this list maps to one example under sample_payloads.interview_media_processed.
sample_payloads	WebhookSamplePayloads	Example payloads grouped by event and, for interview.media_processed, by interview kind.
schema_version	string	Version of the payload contract; bumped on breaking changes.
signature_header	string	HTTP header carrying the HMAC-SHA256 signature.

WebhookDeliveryRead

Name	Type	Description
attempts	integer
created_at
delivered_at
endpoint_id
error
event	string
event_id	string
id	string
interview_id
max_attempts	integer
response_status
status	integer
status_name	string
target_url	string

WebhookEndpointCreate

Name	Type	Description
description		Free-form note for your own reference.
event_types		Restrict delivery to these events. Omit for all. Supported: ['interview.media_processed']
interview_type		Restrict delivery to one interview type. 0=job, 1=screening, 2=video introduction. Omit for all.
is_active	boolean	Inactive endpoints are skipped during dispatch.
name	string	Label to tell endpoints apart.
url	string	Absolute http(s) URL that will receive events.

WebhookEndpointCreated

Name	Type	Description
created_at
description
event_types
id	string
interview_type
is_active	boolean
last_failure_at
last_success_at
name	string
secret	string	HMAC-SHA256 signing secret. Store it securely; it is not shown again.
secret_masked	string	First 6 characters of the secret, for identification only.
updated_at
url	string

WebhookEndpointRead

Name	Type	Description
created_at
description
event_types
id	string
interview_type
is_active	boolean
last_failure_at
last_success_at
name	string
secret_masked	string	First 6 characters of the secret, for identification only.
updated_at
url	string

WebhookEndpointUpdate

Name	Type	Description
description
event_types
interview_type
is_active
name
url

WebhookEventCatalogEntry

Name	Type	Description
description	string
event	string

WebhookSamplePayloads

Name	Type	Description
interview_media_processed	MediaProcessedSamplePayloads	Payloads for interview.media_processed, one per interview kind.
webhook_test	TestEventPayload	Payload sent by POST /webhooks/endpoints/{id}/test.

WebhookTestResult

Name	Type	Description
delivery	WebhookDeliveryRead
detail
endpoint_id	string
success	boolean

Security schemes

Name	Type	Scheme	Description
APIKeyHeader	apiKey
OAuth2PasswordBearer	oauth2