Quickstart

This guide will get you all set up and ready to directly integrate your institution's CRM with the Semantikmatch API. We'll cover how to create programs, submit candidates, define evaluation criteria, setup automatic scoring, and receive evaluation results via webhooks.

Before you can make requests to the Semantikmatch API, you will need to grab your API key from your dashboard. You can find it under Settings » API.

Integration Overview

The integration between your systems and SemantikMatch follows this general flow:

┌─────────────────────┐     ┌─────────────────────┐
│                     │     │                     │
│   Your CRM System   │────▶│  SemantikMatch API  │
│                     │     │                     │
└─────────────────────┘     └─────────────────────┘
          ▲                            │
          │                            │
          │                            ▼
┌─────────────────────┐     ┌─────────────────────┐
│                     │     │                     │
│   Your Webhook      │◀────│  Evaluation Engine  │
│   Handler           │     │                     │
└─────────────────────┘     └─────────────────────┘

The integration process involves:

Creating programs on SemantikMatch that define the document requirements
Setting up evaluation criteria and scorecards
Submitting candidates with their documents to SemantikMatch
Retrieving evaluation results via API

Step 1: Create a Program

First, create a program that defines the structure of your applications and required documents.

Create a Form

Create a new form that defines the structure of your applications and required documents.

Code example

curl https://api.semantikmatch.com/api/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MBA Program",
    "steps": [
      {
        "name": "Apply Phase",
        "fields": [
          {
            "name": "CV",
            "type": "attachment"
          },

          {
            "name": "Transcript",
            "type": "attachment"
          },

          {
            "name": "ID",
            "type": "attachment"
          },

          {
            "name": "GMAT_OR_MANAGEMENT",
            "type": "attachment"
          },

          {
            "name": "TOEFL_OR_ENGLISH",
            "type": "attachment"
          }
        ]
      }
    ]
  }'

Response

{
  "id": "50b23f9a-1670-48f8-a666-e64011cb43e2",
  "title": "MBA Program",
  "created_at": "2025-05-05T12:00:00Z",
  "modified_at": "2025-05-05T12:00:00Z",
  "steps": [
    {
      "name": "Apply Phase",
      "description": null,
      "fields": [
        {
          "name": "CV",
          "type": "attachment"
        },
        {
          "name": "Transcript",
          "type": "attachment"
        },
        {
          "name": "ID",
          "type": "attachment"
        },
        {
          "name": "GMAT_OR_MANAGEMENT",
          "type": "attachment"
        },
        {
          "name": "TOEFL_OR_ENGLISH",
          "type": "attachment"
        }
      ]
    }
  ]
}

Key point: Store the job ID returned in the response. You'll need it when submitting candidates and creating criteria.

Step 2: Define Evaluation Criteria

After creating a program, you'll want to define criteria for evaluating candidate applications.

Create a Criteria

Create a new criteria for evaluating applications.

curl "https://api.semantikmatch.com/api/criteria" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "criteria_type": "evaluate",
  "query": "Check if the student has any failing grades (below 50%) in core subjects.",
  "metric": "Failing Grades",
  "value": "50",
  "operator": "lower",
  "custom_name": "Core Subject Performance",
  "mandatory": true,
  "agg_job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "custom_prompt": "Analyze the student's transcript and identify if there are any failing grades (below 50%) in core subjects (Math, Science, Languages).",
  "custom_model": "gpt-4",
  "tools_list": ["web_search"]
}'

Response

{
  "id": "75",
  "criteria_type": "evaluate",
  "query": "Check if the student has any failing grades (below 50%) in core subjects.",
  "input_1": null,
  "input_2": null,
  "metric": "Failing Grades",
  "value": "50",
  "operator": "lower",
  "custom_name": "Core Subject Performance",
  "mandatory": true,
  "agg_job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "status": null,
  "archived": false,
  "custom_prompt": "Analyze the student's transcript and identify if there are any failing grades (below 50%) in core subjects (Math, Science, Languages).",
  "custom_model": "gpt-4",
  "tools_list": ["web_search"],
  "created_at": "2025-05-07T15:30:00.000Z"
}

Available criteria types:

extract: Extract information from a document
evaluate: Evaluate a document against specific criteria
experience: Assess a candidate's professional experience
validity: Check if a document is valid
And many more

Step 3: Set Up Scorecards

Scorecards define how candidates are scored based on criteria results.

Create a Scorecard

Create a new scorecard for evaluating applications.

curl "https://api.semantikmatch.com/api/scorecards" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "criteria_id": "71",
  "description": "Value > 0 (+5 points)",
  "condition": "HigherThan",
  "value_to_compare": "0",
  "scoring": 5,
  "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "comparison_source": "payload"
}'

Response

{
  "id": "18",
  "criteria_id": "71",
  "description": "Value > 0 (+5 points)",
  "condition": "HigherThan",
  "value_to_compare": "0",
  "scoring": 5,
  "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "created_at": "2025-05-07T15:45:23.789Z",
  "comparison_source": "payload",
  "criteria": {
    "id": "71",
    "custom_name": "Strong Performance Count"
  }
}

Available conditions:

EQ: Equal to
GT: Greater than
LT: Less than
GTE: Greater than or equal to
LTE: Less than or equal to
CONTAINS: Contains substring (for text comparisons)
REGEX: Regular expression match

Comparison sources:

score: Compare to the criteria score (numeric)
payload: Compare to the criteria result payload (text)

Step 4: Submit a Candidate Application

Once you have created your program and set up your evaluation criteria, you can submit candidates with their documents.

Submit a Candidate

Submit a new candidate application along with their documents.

curl -X POST https://api.semantikmatch.com/v1/applications/submit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "firstname=John" \
  -F "lastname=Doe" \
  -F "email=john.doe@example.com" \
  -F "jobId=50b23f9a-1670-48f8-a666-e64011cb43e2" \
  -F "CV=@/path/to/cv.pdf" \
  -F "Transcript=@/path/to/transcript.pdf" \
  -F "ID=@/path/to/id.pdf" \
  -F "GMAT_OR_MANAGEMENT=@/path/to/gmat-or-management.pdf" \
  -F "TOEFL_OR_ENGLISH=@/path/to/toefl-or-english.pdf" \ \
  -F "client_data={\"candidate_id\":\"CRM-12345\",\"source\":\"internal_system\"}"

Response

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "john.doe@example.com",
  "applicationId": "501" // The ID of the created application
}

Key points:

Field names (CV, Transcript, etc.) must match the names defined in your program
The jobId parameter must be set to the job ID from program creation
The client_data field allows you to include any additional information that you want returned in API responses

Step 5: Retrieve Evaluation Results

After submitting a candidate application, you can retrieve evaluation results using the evaluations API endpoint.

Get Evaluations

Retrieve evaluation results for an application, or filter evaluations by various criteria.

curl https://gateway.semantikmatch.com/api/evaluations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "application_id=501"

Response

[
  {
    "id": "56917",
    "application_id": "c4501559-a55d-4457-99ac-64030879cf0c",
    "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
    "status": "finished",
    "total_score": 6,
    "created_at": "2025-05-05T08:12:47.505Z",
    "updated_at": "2025-05-05T08:14:01.070Z",
    "candidate": {
      "id": "9a27d6b5-e6c1-4af2-9d76-1ab85cb82f22",
      "firstname": "John",
      "lastname": "Doe",
      "email": "john.d@example.com"
    },
    "job_name": "Admissions Evaluation",
    "scorecard_details": [
      {
        "status": "success",
        "condition": "EQ",
        "criteria_id": "74",
        "description": "Value equals 100 (-2 points)",
        "processed_at": "2025-05-05T08:13:20.658Z",
        "scorecard_id": "12",
        "score_applied": -2,
        "value_compared": "100",
        "value_evaluated": "Des résultats en baisse, un devoir maison non rendu malgré un délai conséquent, aucun investissement dans la matière.",
        "criteria_result_id": "584"
      },
      {
        "status": "success",
        "condition": "HigherThan",
        "criteria_id": "71",
        "description": "Value > 0 (+2 points)",
        "processed_at": "2025-05-05T08:13:34.003Z",
        "scorecard_id": "14",
        "score_applied": 2,
        "value_compared": "0",
        "value_evaluated": "3",
        "criteria_result_id": "585"
      }
    ]
  }
]

Key points:

Use the application_id from the submission response to filter results for a specific candidate
You can also filter by job_id, criteria_type, and status
The response includes detailed evaluation results for each criteria

Integration Checklist

Before deploying your integration to production, make sure you've completed the following:

Initial Setup
- Obtained SemantikMatch API token
- Created program/form with required fields
- Mapped your CRM fields to SemantikMatch fields
Evaluation Setup
- Created relevant criteria for your program
- Set up appropriate scorecards
- Tested scoring with sample candidates
Candidate Submission
- Implemented candidate data extraction from your CRM
- Created document handling logic
- Added client_data with necessary identifiers
- Implemented error handling and retries
Evaluation Retrieval
- Implemented API calls to retrieve evaluation results
- Created logic to update your CRM with results
- Added caching mechanisms for results if needed
- Implemented error handling for API calls
Production Readiness
- Implemented appropriate security measures
- Added monitoring and alerting
- Created documentation for your team
- Established support processes

What's Next?

Now that you have set up your direct integration with SemantikMatch, you might want to explore more advanced features:

Creating custom scorecards for more sophisticated scoring
Setting up multiple programs for different application processes
Retrieving and managing evaluations programmatically
Implementing custom criteria for specialized evaluations

For any questions or support with your integration, contact our team at support@semantikmatch.com.