# Candidates Query

### Introduction

A candidate represents a new prospect that is added to a listing.  This candidate is unique to a listing, only based on email, if the same person uses 2 emails, they will be seen as 2 candidates and cannot be merged at the moment.

To understand what is necessary and how to use GraphQL, on master data page we explain what is necessary to do

### Query

{% hint style="info" %}
Queries are responsible to pull data from GraphQL. For more information please read the GraphQL documentation.
{% endhint %}

<pre class="language-graphql"><code class="lang-graphql">type Query {
  candidates(input: CandidatesFilterListPaging): [Candidate]
}

type Candidate {
  id: String
  email: String
  firstName: String
  lastName: String
  fullName: String
  companyContactId: String
  listingId: String
  rating: Float
  notes: String
  candidateSource: String
  isNewCandidate: Boolean
  isNewApplicant: Boolean
  isSharedApplicant: Boolean
  isToDo: Boolean
  isInvited: Boolean
  isScheduled: Boolean
  isApplicant: Boolean
  isDisabled: Boolean
  isPendingCandidate: Boolean
  isFromInvestment: Boolean
  hasSharedDataRoom: Boolean
  longExposeNoViews: Int
  longExposeLastView: DateTime
  hadAcceptedSellingCancelationNotice: Boolean
  sellingCancellationStatus: CandidateSellingCancellationStatusType
  viewingStartDate: DateTime
  disabledReason: CandidateDisabledReason
<strong>  scheduledStatus: CANDIDATE_SCHEDULED_STATUS
</strong>  scoring: CandidateScoreType
  statuses: CandidateStatuses
  notificationStatuses: CandidateNotificationStatuses
  createdAt: DateTime
  updatedAt: DateTime
  applications: [ListingCandidateApplication]
  listing: Listing
}

enum CANDIDATE_SCHEDULED_STATUS {
  NOT_INVITED
  INVITED
  ADMIN_CANCELLED
  CANDIDATE_CANCELLED
  SCHEDULED
  NEW_TIMESLOTS_REQUESTED
}

type ListingCandidateApplication {
  id: String
  candidateId: String
  email: String
  userId: String
  isMainCandidate: Boolean
  applicationDataString: String
  applicationData: ApplicationData
}

type ApplicationData {
  isFinancingReady: Boolean
  isAnyoneSmoking: Boolean
  hasPets: Boolean
  hasEligibilityCertificate: Boolean
  email: String
  firstName: String
  lastName: String
  eligibilityExpirationDate: String
  employmentType: String
  householdPersons: Int
}

type CandidateSellingCancellationStatusType {
  date: DateTime
  checkedSellingCancellation: Boolean
  checkedExplicitelyStartEarly: Boolean
  checkedAcceptFee: Boolean
  acceptedFeeDate: DateTime
}

type CandidateScoreType {
  totalScore: Float
}

type CandidateDisabledReason {
  reason: String
  message: String
}

type CandidateStatuses {
  scheduledStatus: String
  vettingStatus: String
  disabledStatus: String
}

type CandidateNotificationStatuses {
  hasReceivedStep2InviteEmail: DateTime
  hasReceivedStep2InvitationFromAdmin: DateTime
  hasReceivedGdprNotification: DateTime
  hasReceived24hrsBeforeViewingReminder: DateTime
  hasReceivedAfterViewingInviteReminder: DateTime
  hasReceived24hrAfterViewingStep2Reminder: DateTime
  hadReceivedSellingCancelationNotice: DateTime
}

input CandidatesFilter {
  id: String
  companyId: String
  ownerId: String
  propertyGroupId: String
  propertyId: String
  candidateSources: [String]
  disabledReasons: [String]
  isApplicant: Boolean
  isDisabled: Boolean
  from: Date
  to: Date
  external: Boolean
  updatedAt: IDateRange
}

input CandidatesFilterListPaging {
  filter: CandidatesFilter
  paging: GraphPaging
  sort: GraphSorting
}
</code></pre>

{% tabs %}
{% tab title="GraphQL" %}

```graphql
query candidates(
  $companyId: String
  $propertyId: String
  $isApplicant: Boolean
) {
  candidates(
    input: {
      paging: { take: 100, skip: 0 }
      filter: {
        companyId: $companyId
        propertyId: $propertyId
        isApplicant: $isApplicant
      }
    }
  ) {
    id
    email
    firstName
    lastName
    fullName
    rating
    candidateSource
    isApplicant
    isDisabled
    isPendingCandidate
    isFromInvestment
    hasSharedDataRoom
    hadAcceptedSellingCancelationNotice
    viewingStartDate
    disabledReason {
      reason
      message
    }
    statuses {
      scheduledStatus
      vettingStatus
      disabledStatus
    }
    notificationStatuses {
      hasReceivedStep2InviteEmail
      hasReceivedStep2InvitationFromAdmin
      hasReceivedGdprNotification
      hasReceived24hrsBeforeViewingReminder
      hasReceivedAfterViewingInviteReminder
      hasReceived24hrAfterViewingStep2Reminder
      hadReceivedSellingCancelationNotice
    }
    applications {
      id
      candidateId
      email
      userId
      isMainCandidate
      applicationDataString
    }
  }
}

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.everreal.co/endpoints/candidates/candidates-query.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.