# 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 }
} 

```


---

# 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/candidate-mutation.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.