> 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.

# Retrieve additional information fields for GP workers by country

GET https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/{country_code}

Retrieves the country-specific additional information fields required for GP workers to run payroll in compliance with local regulations.

 **Token scopes**: `forms:read`

Reference: https://developer.deel.com/api/reference/endpoints/global-payroll/retrieve-additional-information-fields-for-gp-workers-by-country-v-2026-01-01

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

## Request

### Path parameters

- `country_code` (string, required) — ISO 3166-1 alpha-2 country code for which to retrieve GP worker additional fields.

## Response

### 200

Use this response to render dynamic form fields for GP worker onboarding. Contains field configuration, validation rules, display metadata, and dependency logic needed to build country-specific additional information forms.

- `data` (list of FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItems, required) — Use this array to build the form UI. Each item defines one field with its type, validation, and display configuration. Items are pre-sorted by EDM display order. An empty array means no additional fields are configured for the requested country.

## Errors

### 400 Bad Request Error

Returned when the country_code path parameter is not a recognized ISO 3166-1 alpha-2 code.

- `errors` (list of FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaErrorsItems, required) — Use this array to identify each validation failure. Each item describes one parameter that failed validation.

### 401 Unauthorized Error

Authentication failed. The access token is missing, expired, or invalid.

- `errors` (list of FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaErrorsItems, required)

### 403 Forbidden Error

Access denied. The authenticated user does not have the required forms:read scope.

- `errors` (list of FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaErrorsItems, required)

### 404 Not Found Error

The country_code is a valid ISO code but no additional information template exists for it in the Employee Data Management system.

- `message` (string, required) — Use this message to understand why the request failed. Indicates the country does not have an additional info template configured.

### 429 Too Many Requests Error

Rate limit exceeded. The client has sent too many requests in a given time window.

- `errors` (list of FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaErrorsItems, required)

### 500 Internal Server Error

Internal server error. Returned when the Employee Data Management service is unreachable, or an unexpected error occurs during field retrieval.

- `message` (string, optional) — Use this message for logging and debugging purposes. Contains a general error description.

## Types

### FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItems

- `key` (string, required) — Use this value as the field identifier when submitting additional information. Represents the snake_case version of the internal field name, generated by the API naming convention service.
- `type` (enum, required) — Use this value to determine the data type expected when submitting field values. Mapped from the raw input type: 'date', 'text', 'select', 'textarea', 'tel', 'phone', and 'string' map to "string"; 'number' maps to "number"; 'checkbox' maps to "boolean". An empty string indicates an unrecognized input type.
  - Allowed values: `string`, `number`, `boolean`, ``
- `ui_guide` (FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsUiGuide, required) — Use this object to control how the field is rendered in the UI. Contains labels, input type, display order, and supplementary text.
- `validation` (list of FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsValidationItems, required) — Use this array to apply client-side validation before form submission. Contains zero or one validation rule per field. An empty array means no validation is configured.
- `is_required` (boolean, required) — Use this flag to determine whether the field must be provided when submitting additional information. For GP workers, the value considers the GP-specific optionality setting when available, falling back to the general optionality flag.
- `dependencies` (list of FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsDependenciesItems, required) — Use this array to implement conditional field visibility. When non-empty, this field should only be displayed and required when the referenced dependency conditions are met. An empty array means the field has no conditional dependencies.
- `required_by` (string, optional) — Use this value to determine at which stage in the payroll lifecycle this field must be collected. Known values: 'before_payroll' (required before payroll processing), 'after_payroll' (can be collected after initial payroll), 'contract_signing' (required at contract signing). Absent from the response when no lifecycle stage is configured.
- `values_allowed` (list of string, optional) — Use this array to populate dropdown or select options when field_type is 'select'. Only present when the field has predefined options. Absent from the response for free-text, date, number, and other non-select field types.

### FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaErrorsItems

- `message` (string, required) — Use this message to detect rate limiting. Implement exponential backoff before retrying.

### FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsUiGuide

Use this object to control how the field is rendered in the UI. Contains labels, input type, display order, and supplementary text.

- `label` (string, required) — Use this value as the primary English-language label when rendering the field in the UI.
- `order` (integer, required) — Use this value to determine the display position of the field in the form. Starts at 1 and reflects the position in the response array, which is pre-sorted by the configured display order.
- `field_type` (string, required) — Use this value to select the appropriate UI input component. Represents the raw input type from the field configuration. Known values include 'text', 'date', 'select', 'textarea', 'tel', 'phone', 'number', 'checkbox', and 'string'. Additional values may exist.
- `description` (string, required) — Use this value to display supplementary context about the field below or beside the input. HTML tags are stripped. Returns an empty string when no description is configured.
- `helper_text` (string, required) — Use this value to display footnote or instructional text near the field. HTML tags are stripped. Returns an empty string when no helper text is configured.
- `local_label` (string, required) — Use this value as the localized field label when rendering the form in the worker's local language.

### FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsValidationItems

- `type` (string, required) — Use this value to determine which validation strategy to apply. "REGEX" indicates the 'value' field contains a regular expression pattern. Any other value indicates a custom validation type identified by its uppercase name.
- `error_message` (string, required) — Use this message to display to the user when the field value fails validation. Defaults to 'Review the value entered' when no custom message is configured.
- `value` (string, optional) — Use this value as the validation parameter. For REGEX type, contains the regular expression pattern to validate the field input against. Absent when the validation type is a custom type that does not require a parameter.

### FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsDependenciesItems

- `key` (string, required) — Use this value to identify the field that this dependency refers to. Contains the snake_case key of the dependency field, matching another field's 'key' property in the same response.
- `value` (FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsDependenciesItemsValue, required) — Use this value to evaluate the dependency condition. When the value is a primitive (string, number, or boolean), the condition is satisfied when the referenced field equals this value. When the value is an object with 'op' and 'value' properties, apply the specified operator: 'eq' (equals), 'ne' (not equals), 'gt' (greater than), 'lt' (less than), 'notnull' (field is not null), 'contains' (field value contains the specified substring).

### FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsDependenciesItemsValue

Use this value to evaluate the dependency condition. When the value is a primitive (string, number, or boolean), the condition is satisfied when the referenced field equals this value. When the value is an object with 'op' and 'value' properties, apply the specified operator: 'eq' (equals), 'ne' (not equals), 'gt' (greater than), 'lt' (less than), 'notnull' (field is not null), 'contains' (field value contains the specified substring).

### FormsGpWorkerAdditionalFieldsCountryCodeGetResponsesContentApplicationJsonSchemaDataItemsDependenciesItemsValue3

- `op` (enum, required) — Use this operator to evaluate the dependency condition against the referenced field's submitted value.
  - Allowed values: `eq`, `ne`, `gt`, `lt`, `notnull`, `contains`
- `value` (any, required) — Use this value as the operand for the dependency condition evaluation.

## Examples

**Response**

```json
{
  "data": [
    {
      "key": "additional_name",
      "type": "string",
      "ui_guide": {
        "label": "Preferred Name / Additional Name",
        "order": 1,
        "field_type": "text",
        "description": "Preferred name / Additional name",
        "helper_text": "",
        "local_label": "Imie preferowane"
      },
      "validation": [
        {
          "type": "REGEX",
          "error_message": "Review the value entered",
          "value": "^.*$"
        }
      ],
      "is_required": false,
      "dependencies": [],
      "required_by": "before_payroll"
    },
    {
      "key": "dob",
      "type": "string",
      "ui_guide": {
        "label": "Date of Birth",
        "order": 2,
        "field_type": "date",
        "description": "Date of Birth",
        "helper_text": "",
        "local_label": "Data urodzenia"
      },
      "validation": [
        {
          "type": "REGEX",
          "error_message": "Review the value entered",
          "value": "^.*$"
        }
      ],
      "is_required": true,
      "dependencies": [
        {
          "key": "country",
          "value": "UK"
        }
      ],
      "required_by": "before_payroll"
    },
    {
      "key": "marital_status",
      "type": "string",
      "ui_guide": {
        "label": "Marital Status",
        "order": 3,
        "field_type": "select",
        "description": "Marital status of the worker",
        "helper_text": "Select the worker's current marital status",
        "local_label": "Stan cywilny"
      },
      "validation": [],
      "is_required": true,
      "dependencies": [],
      "required_by": "contract_signing",
      "values_allowed": [
        "Single",
        "Married",
        "Divorced",
        "Widowed"
      ]
    }
  ]
}
```

**SDK Code**

```python Global Payroll_retrieveAdditionalInformationFieldsForGpWorkersByCountry-v2026-01-01_example
import requests

url = "https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/ES"

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

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

print(response.json())
```

```javascript Global Payroll_retrieveAdditionalInformationFieldsForGpWorkersByCountry-v2026-01-01_example
const url = 'https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/ES';
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 Global Payroll_retrieveAdditionalInformationFieldsForGpWorkersByCountry-v2026-01-01_example
package main

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

func main() {

	url := "https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/ES"

	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 Global Payroll_retrieveAdditionalInformationFieldsForGpWorkersByCountry-v2026-01-01_example
require 'uri'
require 'net/http'

url = URI("https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/ES")

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 Global Payroll_retrieveAdditionalInformationFieldsForGpWorkersByCountry-v2026-01-01_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/ES")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Global Payroll_retrieveAdditionalInformationFieldsForGpWorkersByCountry-v2026-01-01_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/ES', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp Global Payroll_retrieveAdditionalInformationFieldsForGpWorkersByCountry-v2026-01-01_example
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/ES");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Global Payroll_retrieveAdditionalInformationFieldsForGpWorkersByCountry-v2026-01-01_example
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/forms/gp/worker-additional-fields/ES")! 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()
```