API Reference  ·  v1

skilldeo Platform API

AI-powered video interview platform for modern hiring teams. Automate workflows, manage candidates, and retrieve rich evaluation data programmatically.

Base URL https://api.skilldeo.com
Format JSON
Version v1

Welcome to the official skilldeo API documentation. Whether you're scaling rapidly, building high-performing tech teams, or sourcing operational talent, the API lets you integrate your systems with our platform seamlessly.

Automate Hiring

Schedule interviews and manage candidate workflows without manual effort.

📊

Fetch Insights

Retrieve AI-driven evaluation metrics and performance scores for better decisions.

🔗

Integrate Anywhere

Manage candidates, roles, and data from any system via RESTful endpoints.

Authentication

All API requests (except auth endpoints) require a Bearer Token in the request header:

Header Authorization: Bearer YOUR_API_TOKEN

HTTP Status Codes

CodeMeaning
200OK — Request succeeded
400Bad Request — Invalid parameters
401Unauthorized — Missing or invalid token
404Not Found — Resource does not exist
500Internal Server Error
🔄

Call Flow Diagram

Typical integration flow from user registration through to retrieving interview results.

Signup OTP
POST /auth/signupOTP
Signup Verify
POST /auth/signupVerify
Login OTP + Verify
→ Bearer Token
Agent List / Details
POST or GET
Send Invites
POST /interview/invite
Get Results
GET /interview/getResult
🔐

Authentication API

Register new users and authenticate existing ones using OTP-based email verification. Authentication endpoints do not require a Bearer Token.

POST
/api/v1/auth/signupOTP
Signup OTP

Initiates user registration by sending a One-Time Password (OTP) to the provided email address. Collects personal and organizational information required to validate and create an account.

Body Parameters
NameTypeDescription
emailrequired string The email address of the user.
firstName string First name of the user.
lastName string Last name of the user.
organization string Name of the organization associated with the user.
org_type_id integer (int32) The ID of the organization type.
phoneNumber string The phone number provided during signup.
role_id integer (int32) Role ID associated with the user.
curl -X POST https://api.skilldeo.com/api/v1/auth/signupOTP \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "organization": "Acme Corp",
    "org_type_id": 1,
    "phoneNumber": "+919876543210",
    "role_id": 2
  }'
import requests

url = "https://api.skilldeo.com/api/v1/auth/signupOTP"
payload = {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "organization": "Acme Corp",
    "org_type_id": 1,
    "phoneNumber": "+919876543210",
    "role_id": 2
}

response = requests.post(url, json=payload)
print(response.json())
const response = await fetch("https://api.skilldeo.com/api/v1/auth/signupOTP", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    firstName: "Jane",
    lastName: "Doe",
    organization: "Acme Corp",
    org_type_id: 1,
    phoneNumber: "+919876543210",
    role_id: 2
  })
});

const data = await response.json();
console.log(data);
AuthenticationAPIApi api = new AuthenticationAPIApi();
UserRequest_copy body = new UserRequest_copy();
body.setEmail("[email protected]");
body.setFirstName("Jane");
body.setLastName("Doe");
body.setOrganization("Acme Corp");
body.setRoleId(2);

GenericAuthResponse result = api.signupOTP(body);
System.out.println(result);
Response
✓ 200 OK
{
  "message": "OTP sent successfully",
  "session_id": "abc123-session-id",
  "status_code": 200,
  "error": false
}
POST
/api/v1/auth/signupVerify
Signup Verify

Verifies a user's signup by validating the OTP sent to their email. Completes the registration process and creates the user account.

Body Parameters
NameTypeDescription
emailrequiredstringEmail address of the user.
session_idstringSession ID returned from the Signup OTP step.
verification_codestringThe OTP received by the user.
firstNamestringFirst name of the user.
lastNamestringLast name of the user.
organizationstringOrganization name.
org_type_idinteger (int32)Organization type ID.
phoneNumberstringPhone number provided during signup.
role_idinteger (int32)Role ID of the user.
recievedFromstringSource from which the verification code was received.
curl -X POST https://api.skilldeo.com/api/v1/auth/signupVerify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "session_id": "abc123-session-id",
    "verification_code": "482910",
    "firstName": "Jane",
    "lastName": "Doe",
    "organization": "Acme Corp",
    "role_id": 2
  }'
response = requests.post(
    "https://api.skilldeo.com/api/v1/auth/signupVerify",
    json={
        "email": "[email protected]",
        "session_id": "abc123-session-id",
        "verification_code": "482910",
        "firstName": "Jane",
        "role_id": 2
    }
)
print(response.json())
const response = await fetch("https://api.skilldeo.com/api/v1/auth/signupVerify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    session_id: "abc123-session-id",
    verification_code: "482910"
  })
});
Response
✓ 200 OK
{
  "message": "Account created successfully",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "status_code": 200,
  "error": false
}
POST
/api/v1/auth/loginOTP
Login OTP

Initiates the login process by sending a One-Time Password to the user's registered email address for identity verification.

Body Parameters
NameTypeDescription
emailrequiredstringThe registered email address of the user.
curl -X POST https://api.skilldeo.com/api/v1/auth/loginOTP \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
response = requests.post(
    "https://api.skilldeo.com/api/v1/auth/loginOTP",
    json={"email": "[email protected]"}
)
print(response.json())
const res = await fetch("https://api.skilldeo.com/api/v1/auth/loginOTP", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "[email protected]" })
});
Response
✓ 200 OK
{
  "message": "OTP sent to email",
  "session_id": "xyz789-session-id",
  "status_code": 200,
  "error": false
}
POST
/api/v1/auth/loginVerify
Login Verify

Validates user credentials before proceeding to token generation. Confirms the OTP and returns an access token for authenticated API calls.

Body Parameters
NameTypeDescription
emailstringEmail address of the user.
session_idstringSession ID returned from the Login OTP step.
verification_codestringThe OTP received by the user.
curl -X POST https://api.skilldeo.com/api/v1/auth/loginVerify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "session_id": "xyz789-session-id",
    "verification_code": "381024"
  }'
response = requests.post(
    "https://api.skilldeo.com/api/v1/auth/loginVerify",
    json={
        "email": "[email protected]",
        "session_id": "xyz789-session-id",
        "verification_code": "381024"
    }
)
token = response.json()["token"]
const res = await fetch("https://api.skilldeo.com/api/v1/auth/loginVerify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    session_id: "xyz789-session-id",
    verification_code: "381024"
  })
});
const { token } = await res.json();
Response
✓ 200 OK
{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user_id": 1042,
  "org_id": 88,
  "status_code": 200,
  "error": false
}
🤖

Agent API

Retrieve and manage AI interview agents (campaigns). All Agent API endpoints require a valid Bearer Token.

🔑 All Agent API requests require: Authorization: Bearer YOUR_TOKEN
POST
/api/v1/svc/campaign/list
Agent List

Retrieves a filtered list of agents (campaigns) based on organization-specific parameters. Supports keyword search, status filtering, and pagination.

Header Parameters
NameTypeDescription
AuthorizationrequiredstringBearer token for authentication.
Body Parameters
NameTypeDescription
org_idinteger (int32)The organization ID to filter campaigns.
user_idinteger (int32)The user ID for scoped access.
search_paramstringKeyword-based search filter.
statusstringFilter by agent status (e.g., active, inactive).
topinteger (int32)Number of records to return (pagination).
skipinteger (int32)Number of records to skip (pagination offset).
curl -X POST https://api.skilldeo.com/api/v1/svc/campaign/list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": 88,
    "user_id": 1042,
    "search_param": "",
    "status": "active",
    "top": 10,
    "skip": 0
  }'
headers = {"Authorization": "Bearer YOUR_TOKEN"}
response = requests.post(
    "https://api.skilldeo.com/api/v1/svc/campaign/list",
    headers=headers,
    json={
        "org_id": 88,
        "user_id": 1042,
        "status": "active",
        "top": 10,
        "skip": 0
    }
)
print(response.json())
const res = await fetch("https://api.skilldeo.com/api/v1/svc/campaign/list", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ org_id: 88, user_id: 1042, top: 10, skip: 0 })
});
Response
✓ 200 OK
{
  "message": "Success",
  "records": [
    { "id": 22554, "name": "Dotnet AI walk-in" },
    { "id": 22553, "name": "Angular AI walk-in" },
    { "id": 22552, "name": "Java AI walk-in" }
  ],
  "error": false,
  "status_code": 200
}
GET
/api/v1/svc/campaign/getDetails
Agent Details

Fetches detailed information about a specific agent based on the campaign ID and user ID. Includes agent name, type, status, configuration, and associated metadata.

Query Parameters
NameTypeDescription
campaignIdrequiredinteger (int32)The unique identifier of the agent.
userIdrequiredinteger (int32)The user ID associated with the agent.
Header Parameters
NameTypeDescription
AuthorizationrequiredstringBearer token.
curl -X GET \
  "https://api.skilldeo.com/api/v1/svc/campaign/getDetails?campaignId=22554&userId=1042" \
  -H "Authorization: Bearer YOUR_TOKEN"
response = requests.get(
    "https://api.skilldeo.com/api/v1/svc/campaign/getDetails",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    params={"campaignId": 22554, "userId": 1042}
)
print(response.json())
const res = await fetch(
  "https://api.skilldeo.com/api/v1/svc/campaign/getDetails?campaignId=22554&userId=1042",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
Response
✓ 200 OK
{
  "message": "Success",
  "records": {
    "id": 22554,
    "name": "Dotnet AI walk-in",
    "status": "active",
    "skill": "dotnet",
    "location": "Chennai",
    "job_expiry_date": "2025-12-31T00:00:00Z",
    "start_date": "2025-01-01T00:00:00Z",
    "end_date": "2025-12-31T00:00:00Z"
  },
  "error": false,
  "status_code": 200
}
🎥

Interview API

Send interview invitations, retrieve interview lists, and access evaluation results. All Interview API endpoints require a valid Bearer Token.

🔑 All Interview API requests require: Authorization: Bearer YOUR_TOKEN
POST
/api/v1/svc/interview/invite
Interview Invite

Sends interview invitations to one or more candidates for a specific agent. Includes the agent ID, list of recipient email addresses, and the source of the invite action.

Body Parameters
NameTypeDescription
emailsrequiredarray[string]Array of email addresses to send invites to.
campaign_idrequiredinteger (int32)The ID of the agent for which invites are being sent.
user_idrequiredinteger (int32)The ID of the user sending the invites.
invited_fromrequiredstringSource from which the invites are being sent (e.g., "dashboard", "api").
curl -X POST https://api.skilldeo.com/api/v1/svc/interview/invite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[email protected]", "[email protected]"],
    "campaign_id": 22554,
    "user_id": 1042,
    "invited_from": "api"
  }'
response = requests.post(
    "https://api.skilldeo.com/api/v1/svc/interview/invite",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "emails": ["[email protected]", "[email protected]"],
        "campaign_id": 22554,
        "user_id": 1042,
        "invited_from": "api"
    }
)
print(response.json())
const res = await fetch("https://api.skilldeo.com/api/v1/svc/interview/invite", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    emails: ["[email protected]"],
    campaign_id: 22554,
    user_id: 1042,
    invited_from: "api"
  })
});
InterviewAPIApi api = new InterviewAPIApi();
SendInvitesRequestDto body = new SendInvitesRequestDto();
body.setEmails(Arrays.asList("[email protected]"));
body.setCampaignId(22554);
body.setUserId(1042);
body.setInvitedFrom("api");

api.interviewInvite(body, "Bearer YOUR_TOKEN");
Response
✓ 200 OK
{
  "message": "Invites sent successfully",
  "invited_count": 2,
  "status_code": 200,
  "error": false
}
POST
/api/v1/svc/interview/list
Interview List

Retrieves a paginated list of interviews for a given campaign. Supports filtering by status and keyword search.

Body Parameters
NameTypeDescription
campaign_idinteger (int32)Filter interviews by agent/campaign ID.
org_idinteger (int32)Organization ID.
statusstringFilter by interview status.
search_paramstringKeyword search parameter.
topinteger (int32)Number of records to return.
skipinteger (int32)Number of records to skip.
curl -X POST https://api.skilldeo.com/api/v1/svc/interview/list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": 22554,
    "org_id": 88,
    "status": "completed",
    "top": 20,
    "skip": 0
  }'
response = requests.post(
    "https://api.skilldeo.com/api/v1/svc/interview/list",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "campaign_id": 22554,
        "org_id": 88,
        "status": "completed",
        "top": 20,
        "skip": 0
    }
)
print(response.json())
const res = await fetch("https://api.skilldeo.com/api/v1/svc/interview/list", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ campaign_id: 22554, top: 20, skip: 0 })
});
Response
✓ 200 OK
{
  "message": "Success",
  "records": [
    {
      "interview_id": 5012,
      "candidate_email": "[email protected]",
      "status": "completed",
      "campaign_name": "Dotnet AI walk-in"
    }
  ],
  "hasMore": false,
  "total_count": 1,
  "status_code": 200
}
GET
/api/v1/svc/interview/getResult
Interview Result

Retrieves the AI-evaluated result for a specific interview. Returns evaluation details including status, scores, role fitment, soft skills, technical skills, and overall decision.

Query Parameters
NameTypeDescription
interviewIdrequiredinteger (int32)The ID of the interview for which results are to be retrieved.
Header Parameters
NameTypeDescription
AuthorizationrequiredstringBearer token.
curl -X GET \
  "https://api.skilldeo.com/api/v1/svc/interview/getResult?interviewId=5012" \
  -H "Authorization: Bearer YOUR_TOKEN"
response = requests.get(
    "https://api.skilldeo.com/api/v1/svc/interview/getResult",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    params={"interviewId": 5012}
)
result = response.json()
print(result["records"]["scores"])
const res = await fetch(
  "https://api.skilldeo.com/api/v1/svc/interview/getResult?interviewId=5012",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const { records } = await res.json();
console.log(records.scores);
InterviewAPIApi api = new InterviewAPIApi();
CommonResponseDto result = api.interviewResult(
    5012,
    "Bearer YOUR_TOKEN"
);
System.out.println(result);
Response
✓ 200 OK
{
  "message": "Success",
  "records": {
    "interview_id": 5012,
    "candidate_email": "[email protected]",
    "status": "completed",
    "overall_decision": "shortlisted",
    "scores": {
      "job_stability_score": 78,
      "role_fitment": [
        { "role": "Dotnet Developer", "competency_level": 4 }
      ],
      "soft_skills": [
        { "skill": "Communication", "competency_level": 3, "skill_type": "interpersonal" }
      ],
      "tech_skills": [
        { "skill": "C#", "competency_level": 4, "skill_type": "programming" }
      ]
    }
  },
  "status_code": 200,
  "error": false
}