Knowledge Hub API

The Knowledge Hub API returns country-specific content, such as employment rules, rates, and how local requirements apply. A single endpoint serves this content. Partner integrations typically use it to show a country reference in their own hiring or HR workflow. This guide covers the request shape, the response structure, and the rendering rules required to display the content correctly.

What the API provides

One endpoint serves the entire guide:

Everything you render comes from the fields array on each category. Fields carry plain text and rich HTML, and hold the substantive guide content, such as a tax rate, a notice period, or an explanation of how deductions work.

What the API does not provide

Before designing an integration with the Knowledge Hub API please note the following:

• Article bodies: The endpoint does not return the full Knowledge Hub article content.
• A browsable article list: Category payloads include an articles array, but it holds metadata only. There is no body and no URL, so entries cannot be opened or linked to.

Prerequisites

Three things are required before your first call:

• A Deel access token: Either an OAuth 2.0 token or a personal access token. See Authentication and OAuth 2.0.
• The knowledge-hub:read scope: OAuth 2.0 tokens must carry this scope.
• A country code: The endpoint requires an ISO 3166-1 alpha-2 code.

Make a request

The country_code path parameter is the only parameter defined in the API reference.

A request for the Brazilian guide, narrowed to employers using EOR, looks like this:

curl -G "https://api.letsdeel.com/rest/knowledge-hub/country-guide/BR" \
  -H "Authorization: Bearer $DEEL_ACCESS_TOKEN" \
  -H "X-Version: 2026-01-01" \
  --data-urlencode "audiences=client" \
  --data-urlencode "contract_types=eor"

It is important to apply a request filter. If no filter is applied, all results will be returned: all guides for all audiences and all products for all employers. To avoid large response payloads, make an unfiltered request to inspect the response shape, then apply filters to refine.

Filter the response

Two optional query parameters narrow what the endpoint returns. Omitting one returns every value for it.

Passing multiple values

To submit multiple values, repeat the parameter for each value, as shown below. Comma-separated values will be treated as a single unrecognized value.

# Correct
?audiences=client&audiences=eorEmployee
# Incorrect: silently returns every audience
?audiences=client,eorEmployee

Invalid filter values

A value the endpoint does not recognize is ignored rather than returning an error. If every value you send is invalid, the filter empties and defaults to returning everything.

Contract type scope

Contract types describe which Deel products an employer uses, so they carry no meaning for worker audiences and are ignored there. A request for audiences=eorEmployee&contract_types=gp returns the complete eorEmployee guide, unfiltered.

Audience values

Pass any of these values in audiences:

Contract type values

Pass any of these values in contract_types. They apply only alongside audiences=client:

This list grows as Deel adds products. Don’t treat it as a fixed enum; tolerate unknown values instead of failing on them.

Response structure

The response nests audiences, categories, and fields as follows:

data[]                        audience
 ├─ contract_types[]          present when value == "client"
 │   └─ categories[]
 └─ categories[]              every other audience
     ├─ fields[]              content to render
     └─ articles[]            metadata only

The client audience nests categories one level deeper than other audiences. Handle both shapes.

Envelope

The top-level object carries the audience array alongside pagination metadata:

A guide is currently returned complete in a single response, so has_more is false and next_cursor is null. These fields exist to introduce pagination without a breaking change.

Audience object

Each entry in data describes one audience:

Contract type object

Each entry in contract_types describes one Deel product an employer uses:

Category object

Each entry in categories groups the fields and articles for one topic:

Field object

Each entry in fields carries one piece of renderable guide content:

Article object

Metadata only; see What the API does not provide.

Example response

A request filtered to the eorEmployee audience returns a payload of this shape:

{
  "data": [
    {
      "name": "EOR Employee",
      "value": "eorEmployee",
      "categories": [
        {
          "id": "a3a9e1ce-7afb-40e2-a171-81ad2eec39ff",
          "name": "Wages and Working Hours",
          "icon": "MoreTime",
          "fields": [
            {
              "id": "b3a9e1ce-7afb-41d3-a171-81ad2eec39ff",
              "name": "EOR Minimum Wage",
              "type": "TEXT",
              "value": "ALL 40,000 per month"
            },
            {
              "id": "c4b8f2df-8bfc-42e4-b282-92be3ffd4a11",
              "name": "How deductions work",
              "type": "HTML",
              "value": "<p>Deductions are applied monthly.</p>"
            }
          ],
          "articles": []
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

Conventions

Three conventions hold across the whole response:

• Keys are snake_case throughout the response.
• Enumerated type values are uppercase. Compare case-sensitively against uppercase values, or normalize on input.
• Identifiers are stable UUIDs. You can store them as foreign keys and rely on them across requests.

Render the fields

Everything you display is a field. Branch on type and preserve the order in which fields arrive, because it reflects the order Deel intends for display.

A renderer for the three current field types looks like this:

import html
def render_field(field):
    field_type = field["type"]
    if field_type == "TEXT":
        return {"label": field["name"], "body": html.escape(field.get("value") or "")}
    if field_type == "HTML":
        return {"label": field["name"], "body": sanitize(field.get("value") or "")}
    if field_type == "LINK":
        return {
            "label": field["name"],
            "href": field.get("url"),
            "text": field.get("label"),
            "target": "_blank" if field.get("new_tab") else "_self",
        }
    # Skip unrecognized types to stay forward compatible
    return None

Four rules govern correct rendering:

• Sanitize HTML values before rendering them. Pass the fragment through a sanitizer such as DOMPurify rather than assigning it directly to dangerouslySetInnerHTML or v-html.
• Treat value as nullable. The schema permits a null value on any field type.
• Skip types you do not recognize. New field types may be introduced. A default branch that returns nothing keeps your integration working when that happens.
• Skip categories with no renderable fields. A category qualifies for inclusion on either fields or articles, so fields can arrive empty.

Handle empty categories

Filter out categories with no renderable fields before display; otherwise, they render as a heading with nothing beneath it.

def renderable_categories(categories):
    result = []
    for category in categories:
        fields = [f for f in (render_field(field) for field in category["fields"]) if f]
        if fields:
            result.append({**category, "fields": fields})
    return result
# The client audience nests categories one level deeper
def extract_categories(audience):
    if audience["value"] == "client":
        return [
            category
            for contract_type in audience.get("contract_types", [])
            for category in contract_type["categories"]
        ]
    return audience.get("categories", [])

Error handling

The endpoint returns the following status codes.

Errors for 400 and 500 return an errors array whose entries carry code, message, and, for validation failures, a field naming the parameter at fault:

{
  "errors": [
    {
      "code": "invalid_parameter",
      "field": "/data/country_code",
      "message": "Must have required property 'country_code'"
    }
  ]
}

Errors for 401, 403, and 404 return the shared Deel error envelope, which carries a request object alongside an errors array whose entries provide message and path:

{
  "request": {
    "method": "GET",
    "url": "/rest/knowledge-hub/country-guide/BR",
    "status": 401,
    "api_req_id": "00000000-0000-0000-0000-000000000000"
  },
  "errors": [
    {
      "message": "Unauthorized"
    }
  ]
}

Empty responses

A 200 response carrying "data": [] is valid. The country exists, but no guide is published for the audiences you requested. Treat it as an empty state.

The same applies per audience. A request for three audiences may return one if only one is published.

Best practices

The following practices keep an integration stable as guide content and the API change:

Next steps

Continue with the endpoint schema and the related guides: