# Candidate Mutation

{% hint style="warning" %}
Please keep in mind **GDPR**. Before you add a new candidate in EverReal, please make sure that he accepted your company terms and conditions.
{% endhint %}

### Introduction

A candidate represents a new prospect that is added to a listing. 

After a candidate was added a few things are happening in EverReal:

* One of 3 emails is sent to the candidate. There is no way to turn off emails as of now.
  * Request to submit more information, if necessary
  * Request to choose a time slot, if the listing is configure to auto-invite candidates and times slots are available
  * A thank you email, if none of the above
  * Please note that if the email address is invalid, EverReal will blacklist it for 3 months.
* A contact is also created in the system, that is unique based on the email address
* A message is attached to the candidate record, based on the message field
* If the candidate is added multiple times, his information is updated
* A webhook request is also sent, if you are using the candidate API webhook.

To create a new candidate you are required to have at least 4 **required** parameters:

* the `listingId` you are adding the candidate to
* `email`
* `firstName`
* `lastName`

Other **optional** parameters to the candidate mutation are:

```graphql
message: String
phoneNumber: String
desiredStartDate: Date
noTotalPeopleMovingIn: Int
netMonthlyIncomeRanges: IncomeRangeInput
currency: CURRENCY_TYPE
employmentType: CANDIDATE_EMPLOYMENT_TYPE
```

### Mutation types

{% hint style="info" %}
Mutations are responsible to update or perform changes in GraphQL. For more information please read the GraphQL documentation.
{% endhint %}

```graphql
type Mutation {
  upsertCandidateInitialApplication(
    listingId: String
    candidate: CandidateInitialApplicationRequest
  ): CandidateInitialApplicationResponse
}

input CandidateInitialApplicationRequest {
  firstName: String!
  lastName: String!
  email: String!
  message: String
  phoneNumber: String
  desiredStartDate: Date
  noTotalPeopleMovingIn: Int
  netMonthlyIncomeRanges: IncomeRangeInput
  currency: CURRENCY_TYPE
  employmentType: CANDIDATE_EMPLOYMENT_TYPE
  isFinancingReady: Boolean
  isAnyoneSmoking: Boolean
  hasPets: Boolean
  hasEligibilityCertificate: Boolean
}

type CandidateInitialApplicationResponse {
  success: Boolean
}

input IncomeRangeInput {
  from: Int!
  to: Int!
}

enum CURRENCY_TYPE {
  EUR
  USD
  GBP
  CHF
  DKK
  HRK
  HUF
  NOK
  SEK
  BGN
  CZK
  PLN
  RON
  AED
}

enum CANDIDATE_EMPLOYMENT_TYPE {
  EMPLOYED
  SELF_EMPLOYED
  STUDENT
  SEEKING_WORK
  CLERK
  RETIRED
  HOUSE_MAN_WIFE
  APPRENTICE
  POSTGRADUATE
  OTHER
}

```

Below we are providing a full example how to create or update a candidate using this mutation:

```graphql
# Write your query or mutation here
mutation {
  upsertCandidateInitialApplication(
    listingId:"1eb2ad05-e692-4439-9ee9-2f61f3ff64bb",
    candidate:{
      email:"liviu+candidateintegration3@ignat.email"
      firstName:"Liviu"
      lastName:"from integrations",
      message: "Hi, how are u mate",
      currency: EUR,
      phoneNumber: "+49123456",
      desiredStartDate: "2022-12-01",
      noTotalPeopleMovingIn: 3,
      netMonthlyIncomeRanges: {from: 3000, to: 4000},
      employmentType: CLERK
    }
  ){ success }
} 

```