---
title: "Add/update candidate properties values"
method: PUT
path: "/candidates/{id}/jobs/{jobId}/properties"
tags: ["candidates"]
---

# Add/update candidate properties values

`PUT /candidates/{id}/jobs/{jobId}/properties`

## Request

- Base URL: `https://api.smartrecruiters.com`
- URL: `https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/properties`
- Auth: one of:
  - API key in header `x-smarttoken`
  - OAuth 2
    - Authorization code: `https://www.smartrecruiters.com/identity/oauth/allow`
    - Token URL: `https://api.smartrecruiters.com/identity/oauth/token` scopes: `candidates_manage`

Set candidate properties values for the candidate's job

Below you can find a list of value examples, dependent on different
candidate property types.

### BOOLEAN

```
[{ "id": "propertyId", "value": true }]
```

Value has to be `true` or `false`.

### COUNTRY

```
[{ "id": "propertyId", "value": "us" }]
```

Value has to be lowercase string in ISO 3166-1 alpha-2 format.

### CURRENCY

```
[{ "id": "propertyId",
   "value": {
     "code": "GBP",
     "value": 23232
   }
 }]
```

Code of value is a currency code in ISO 4217 format.

### DATE

```
[{ "id": "propertyId", "value": "2015-11-17T23:00:00.000Z" }]
```

### NUMBER, PERCENT

```
[{ "id": "propertyId", "value": 42 }]
```

### REGION

```
[{ "id": "propertyId", "value": "us-wa" }]
```

Value has to be lowercase string in ISO 3166-2 compatible format.

### SINGLE_SELECT

```
[{ "id": "propertyId", "value": "f6fe768f-b5e6-4794-9938-c2f42ab0a572" }]
```

Value has to be an id of candidate property value (provided by `GET
/configuration/candidate-properties/{propertyId}/values`).

### MULTI_SELECT

**[ALPHA]** `MULTI_SELECT` is available to a limited set of customers under early access.

```
[{ "id": "propertyId", "value": ["f6fe768f-b5e6-4794-9938-c2f42ab0a572", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"] }]
```

Value has to be an array of option ids (provided by `GET
/configuration/candidate-properties/{propertyId}/values`). Duplicate ids in the array are rejected.
Use an empty array or omit `value` to clear the field.

### TEXT

```
[{ "id": "propertyId", "value": "Example text" }]
```

### USER

```
[{ "id": "propertyId", "value": "50fe861de4b00265edec6775" }]
```

Value has to be a valid user id

### Resetting a value

To reset a value for any of the above types, please pass:

```
[{"id": "propertyId"}]
```

For MULTI_SELECT you may also pass `[{ "id": "propertyId", "value": [] }]`.

## Request body

- CandidatePropertyValue[]
  - `id` string, required: Candidate property id, it can be: - candidate property uuid (e.g. 123e4567-e89b-12d3-a456-426614174000) - candidate property key (arbitrary string, e.g. 'myCustomFieldKey')
  - `value` union: string, number, boolean, object, or array of option ids depending on property. For MULTI_SELECT use an array of option UUIDs; duplicate ids in the array are rejected. Omit value or send an empty array to clear a MULTI_SELECT field.
    - string
    - number
    - boolean
    - object
    - string[]

## Response `204`

Properties successfully updated.

## Other responses

- `400`: with codes * **COUNTRY_NOT_FOUND** when candidate property of COUNTRY type and country with provided code does not exist, * **REGION_NOT_FOUND** when candidate property of REGION type and region with provided code does not exist, * **USER_NOT_FOUND** when candidate property of USER type and user with provided id does not exist, * **CURRENCY_NOT_FOUND** when candidate property of CURRENCY type and currency with provided code does not exist, * **VALUE_NOT_FOUND** when candidate property of selection type (e.g. SINGLE_SELECT) and value with provided id does not exist, * **INVALID_TEXT_FORMAT** when candidate property of TEXT type and its value contains forbidden characters * **INVALID_EMAIL_FORMAT** when candidate property of TEXT type (with enabled email validation) and its value contains invalid email address * **INVALID_TEXT_PATTERN_FORMAT** when candidate property of TEXT type (with enabled custom text pattern validation) and its value contains value that does not match the pattern * **INVALID_NUMBER_RANGE** when candidate property of NUMBER type (with enabled application fields date and number range validation) and its value is not in the defined range * **INVALID_DATE_RANGE** when candidate property of DATE type (with enabled application fields date and number range validation) and its value is not in the defined range * **INACCESSIBLE_FIELD** when candidate property cannot be set due to its own configuration * **DUPLICATE_PROPERTIES** when request contains multiple candidate properties with the same id
- `403`: Candidate properties access denied
- `404`: with codes * **PROPERTY_NOT_FOUND** when one of the provided candidate properties does not exist * **JOB_NOT_FOUND** when candidate is not assigned to given job

---

[API](https://skmtc.dev/smartrecruiters/apis/candidates-api.md) - [All operations](https://skmtc.dev/smartrecruiters/apis/candidates-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartrecruiters/apis/candidates-api/revisions/8fde9b33d46d?raw)