How to get the list of Candidates

There are two ways to fetch the list of candidates from your integrations:

1. Syncs (Webhook-based Bulk Reads)

Syncs provide an automated, push-based approach for bulk data retrieval. Once you set up a sync for an integration, Knit polls the source app for changes and sends updates straight to your webhook. This webhook-based model eliminates the need for you to continuously pull data.

Read more about syncs and webhooks here: https://developers.getknit.dev/docs/register-webhook-url#/

2. Read APIs (On-demand Individual Reads)

Read APIs provide on-demand access to specific data through request-response calls. These are standard GET/List operations that allow you to retrieve candidate information whenever needed.

You can refer to applicant tracking systems APIs here: https://developers.getknit.dev/reference/list-candidates#/

Data Model

Here are the different models you can subscribe to while doing a sync:

Model ID	Event Data Key	Description
`candidate_info`	`info`	Get basic candidate details such as name, contact information, current role, and associated tags.
`candidate_education`	`education`	Get education details including degree, institute, major, score, and duration.
`candidate_locations`	`locations`	Get the candidate’s location details such as address, city, state, country, and postal code.
`candidate_skills`	`skills`	Get the list of skills associated with the candidate and their proficiency level.
`candidate_experiences`	`experiences`	Get employment history and experience details for the candidate.
`candidate_attachments`	`attachments`	Get attachments such as resumes, cover letters, or certificates uploaded by the candidate.

📘
Use Model IDs for Sync
While invoking sync APIs, pass these Model IDs to retrieve the desired data.

Candidate Info

Model ID: candidate_info

Name	Type	Description
`id`	`String`	Unique identifier for the candidate in the ATS system
`firstName`	`String`	Candidate’s first name
`lastName`	`String`	Candidate’s last name
`phones`	`List[Phone]`	Please refer to Phone Model
`emails`	`List[Email]`	Please refer to Email Model
`links`	`List[String]`	List of links such as LinkedIn, portfolio, or personal website
`tags`	`List[String]`	List of tags associated with the candidate (e.g., “Java”, “Remote”)
`title`	`String`	Candidate’s current job title
`company`	`String`	Current company of the candidate
`createdAt`	`Date`	Date when the candidate record was created
`updatedAt`	`Date`	Date when the candidate record was last updated
`applications`	`List[String]`	List of application IDs associated with this candidate

Candidate Education

Model ID: candidate_education

Name	Type	Description
`education`	`List[Education]`

Education

Name	Type	Description
`id`	`String`	Unique identifier for the education record
`degree`	`String`	Name of the degree obtained
`institute`	`String`	Name of the educational institution
`fromDate`	`Date`	Start date of the education period
`toDate`	`Date`	End date of the education period
`major`	`String`	Major subject of study
`minor`	`String`	Minor subject of study (if applicable)
`description`	`String`	Additional notes or description of the education
`score`	`String`	Grade, GPA, or score achieved
`currentlyPursuing`	`Boolean`	Indicates if the education is still ongoing

Candidate Locations

Model ID: candidate_locations

Name	Type	Description
`locations`	`List[Address]`	Please refer to Address Model

Candidate Skills

Model ID: candidate_skills

Name	Type	Description
`skills`	`List[Skill]`

Skill

Name	Type	Description
`name`	`String`	Skill name (e.g., “Python”, “React”)
`level`	`String`	Skill proficiency level (e.g., “Expert”, “Beginner”)

Candidate Experiences

Model ID: candidate_experiences

Name	Type	Description
`experiences`	`List[Experience]`

Experience

Name	Type	Description
`company`	`String`	Name of the company
`jobTitle`	`String`	Job title or role held by the candidate
`startDate`	`Date`	Start date of employment
`endDate`	`Date`	End date of employment
`currentlyWorking`	`Boolean`	Indicates if the candidate is currently working here
`summary`	`String`	Summary of responsibilities or achievements in the role

Candidate Attachments

Model ID: candidate_attachments

Name	Type	Description
`attachments`	`List[Attachment]`

Attachment

Name	Type	Description
`type`	`String`	One of `RESUME` `COVER_LETTER` `OFFER_LETTER` `NOT_SPECIFIED`
`name`	`String`	Name of the file
`link`	`String`	Downloadable link of the file. (Caution: Some ATS systems might only provide a short lived link)
`createdAt`	`Date`	Date when the attachment was uploaded/created
`attachmentContent`	`AttachmentContent`	Content of the attachment
`downloadLink`	`String`	Prefer using the `downloadLink` field over `link` if both are present. Content will be base64 encoded. Sample JSON Response of downloadLink: `{ "success": true, "data": { "content": "Base64 Encoded content" } }`

Attachment Content

Name	Type	Description
`content`	`String`
`encoding`	`Enum`	One of `BASE64` `NOT_SPECIFIED`

Example Event Data

{
  "info": {
    "id": "cand_001",
    "firstName": "Alice",
    "lastName": "Johnson",
    "phones": [
      {
        "type": "PERSONAL",
        "phoneNumber": "+1-202-555-0101"
      },
      {
        "type": "WORK",
        "phoneNumber": "+1-202-555-0199"
      }
    ],
    "emails": [
      {
        "type": "PERSONAL",
        "email": "alice.johnson@example.com"
      },
      {
        "type": "WORK",
        "email": "alice.j@company.com"
      }
    ],
    "links": [
      "https://linkedin.com/in/alicejohnson",
      "https://portfolio.alice.dev"
    ],
    "tags": [
      "Java",
      "Remote",
      "Backend Developer"
    ],
    "title": "Senior Software Engineer",
    "company": "Tech Solutions Ltd.",
    "createdAt": "2022-05-12T09:00:00Z",
    "updatedAt": "2023-08-20T14:00:00Z",
    "applications": [
      "app_12345",
      "app_98765"
    ]
  },
  "education": [
    {
      "id": "edu_101",
      "degree": "Bachelor of Technology",
      "institute": "Delhi Institute of Technology",
      "fromDate": "2015-07-01T00:00:00Z",
      "toDate": "2019-06-30T00:00:00Z",
      "major": "Computer Science",
      "minor": "Mathematics",
      "description": "Graduated with distinction. Led final year AI project.",
      "score": "8.9 CGPA",
      "currentlyPursuing": false
    }
  ],
  "locations": [
    {
      "addressType": "NOT_SPECIFIED",
      "addressLine1": "123 Tech Park",
      "addressLine2": "123 Tech Park",
      "city": "Bangalore",
      "state": "Karnataka",
      "country": "India",
      "zipCode": "560103"
    }
  ],
  "skills": [
    {
      "name": "Python",
      "level": "Expert"
    },
    {
      "name": "ReactJS",
      "level": "Intermediate"
    },
    {
      "name": "SQL",
      "level": "Advanced"
    }
  ],
  "experiences": [
    {
      "company": "Tech Solutions Ltd.",
      "jobTitle": "Senior Software Engineer",
      "startDate": "2020-02-01T00:00:00Z",
      "endDate": null,
      "currentlyWorking": true,
      "summary": "Leading backend development and API integration for enterprise clients."
    },
    {
      "company": "Innovate Labs",
      "jobTitle": "Software Engineer",
      "startDate": "2018-01-15T00:00:00Z",
      "endDate": "2019-12-31T00:00:00Z",
      "currentlyWorking": false,
      "summary": "Built microservices and internal automation tools."
    }
  ],
  "attachments": [
    {
      "type": "RESUME",
      "name": "Resume_Alice_Johnson.pdf",
      "link": "https://storage.getknit.dev/files/resume-alice.pdf",
      "createdAt": "2023-07-10T09:00:00Z",
      "attachmentContent": {
        "content": "b29fTVJrRWU5dW1CU2NQNUlTYkFkc3dJdTpzbGFjaw==",
        "encoding": "BASE64"
      },
      "downloadLink": "https://api.getknit.dev/files/resume-alice.pdf?token=XYZ123"
    }
  ]
}