> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# List all custom fields

GET https://api.letsdeel.com/rest/contracts/custom_fields

Returns the list of custom field definitions configured for contracts within the organization. The response includes field metadata, not specific contract field values. It provides definitions with contract placement for supported types such as text, list, multiselect, number, percentage, currency, date, and hyperlink.

 **Token scopes**: `contracts:read`

Reference: https://developer.deel.com/api/hris-endpoints/custom-fields-contracts/list-contract-custom-fields

## Authentication

- `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
- `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

## Servers

- `https://api.letsdeel.com/rest` (Production, default)
- `https://api-staging.letsdeel.com/rest` (Demo)

## Response

### 200

Successful response

- `data` (list of ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItems, required)

## Errors

### 400 Bad Request Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 401 Unauthorized Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 403 Forbidden Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 404 Not Found Error

Operation failed.

- `request` (ApiErrorRequest, optional)
- `errors` (list of ApiError, optional)

### 500 Internal Server Error

Internal server error

- `errors` (list of ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaErrorsItems, optional)

## Types

### ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItems

- `id` (string, required) — Unique identifier of the custom field
- `name` (string, required) — Name of the custom field
- `type` (ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsType, required) — Type configuration of the custom field including its data type and type-specific properties
- `settings` (ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsSettings, required) — Configuration settings for the custom field including requirements, visibility, and access controls
- `created_at` (string, required) — Creation date of the custom field
- `placement` (enum, optional, nullable) — Valid placements for custom field
  - Allowed values: `profile`, `contract`
- `description` (string, optional, nullable) — Description of the custom field

### ApiErrorRequest

- `method` (string, optional) — The HTTP method of the failed request
- `url` (string, optional) — The relative URL of the failed request
- `status` (double, optional) — The status code of the response
- `api_req_id` (string, optional) — The request ID of the failed request
- `docs` (string, optional) — A link to the official documentation for the requested endpoint resource
- `source` (string, optional) — The source handler which produced the returned error
- `code` (double, optional) — The code of the source handler which produced the returned error

### ApiError

- `message` (string, optional) — A description of the returned error
- `path` (string, optional) — The JSON path where input validation failed

### ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaErrorsItems

- `code` (string, required) — Machine-readable error code
- `message` (string, required) — Human-readable explanation of the error

### ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsType

Type configuration of the custom field including its data type and type-specific properties

### ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsSettings

Configuration settings for the custom field including requirements, visibility, and access controls

- `access` (ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsSettingsAccess, required) — Access settings for the custom field
- `required` (boolean, required) — Whether the custom field is required
- `is_enabled` (boolean, required) — Whether the custom field is enabled
- `countries` (list of string, optional) — Countries for which the custom field is applicable. Omitted when applicable to all.
- `worker_types` (list of enum, optional) — Worker types for which the custom field is applicable. Omitted when applicable to all.
  - Allowed values: `eor`, `contractor`, `hris_direct_employee`, `direct_employee`

### ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsType0

- `name` (enum, required) — Simple types
  - Allowed values: `text`, `number`, `date`, `percentage`, `hyperlink`

### ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsType1

- `name` (enum, required) — Currency type
  - Allowed values: `currency`
- `is_fixed` (boolean, required) — When currency is fixed, only the amount can be edited by the users
- `currency` (string, optional, nullable) — Currency code (null when is_fixed is false)

### ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsType2

- `name` (enum, required) — List types
  - Allowed values: `list`, `multiselect`
- `options` (list of string, required) — List of options for the custom field

### ContractsCustomFieldsGetResponsesContentApplicationJsonSchemaDataItemsSettingsAccess

Access settings for the custom field

- `is_sensitive` (boolean, required) — Whether the custom field is sensitive
- `provided_by` (enum, optional, nullable) — Entity providing access to the custom field
  - Allowed values: `organization`, `worker`
- `group_permission_set` (string, optional, nullable) — Permission set identifier for the custom field

## Examples

**Response**

```json
{
  "data": [
    {
      "id": "7015d676-6e53-47a1-8b01-2f0b2c550790",
      "name": "Employment Status",
      "type": {
        "name": "text"
      },
      "settings": {
        "access": {
          "is_sensitive": false,
          "provided_by": "organization",
          "group_permission_set": "custom_fields_set1"
        },
        "required": true,
        "is_enabled": true,
        "countries": [
          "CO",
          "PH"
        ],
        "worker_types": [
          "direct_employee",
          "hris_direct_employee"
        ]
      },
      "created_at": "2025-10-14T13:47:22.851Z",
      "placement": "contract",
      "description": "Custom Field Description"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/contracts/custom_fields"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/contracts/custom_fields';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.letsdeel.com/rest/contracts/custom_fields"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.letsdeel.com/rest/contracts/custom_fields")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.letsdeel.com/rest/contracts/custom_fields")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.letsdeel.com/rest/contracts/custom_fields', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/contracts/custom_fields");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/contracts/custom_fields")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```