How to render Wiki articles
The Wiki integration lets you display Deel’s knowledge base inside your own applications.
The Wiki API lets you display Deel’s knowledge base inside your application. It is front-end agnostic, so you can use it with any framework or tech stack.
Use the Wiki API to embed Deel content where your users work. For example, you can:
- Display country-specific onboarding guides directly in your platform.
- Surface compliance or payroll documentation inside your admin tool.
- Provide contextual help or policy details without redirecting users to Deel’s Help Center.
This guide shows you how to retrieve and render Wiki articles in your frontend.
- Retrieve a Wiki auth token.
- Include the Wiki initializer script.
- Fetch a list of articles.
- Retrieve a single article.
- Render the article.
Step 1. Retrieve a Wiki auth token
Curently, tokens can only be generated by Deel, contact [email protected] to get one. You will receive a valid JWT token recognized by the Wiki API. Use it in the Authorization header as a Bearer token.
Validate the token with the following query:
curl --location 'https://wiki.deel.network/graphql' \
--header 'accept: application/json' \
--header 'authorization: Bearer {{YOUR_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{"query":"{\n users{profile {\n id\n name\n }}\n}","variables":{}}'
Do not expose API tokens in front-end code
Exposing your API token on the front-end can lead to credential leaks. Always handle authentication and token management on a secure backend server.
Recommended request flows:
Step 2. Include the Wiki initializer script
<script src="https://wiki.deel.network/_assets/js/externals/wiki-initializer.js"></script>
Load the initializer in your project. This should be done as soon as possible in the app life cycle.
Choose the correct Wiki environment
You can update the Wiki domain according to the desired environment:
- https://wiki.deel.network/ -> PRODUCTION
- https://wiki.deel.training/ -> DEVELOPMENT
Step 3. Fetch a list of articles
You can fetch Wiki articles using the pages.list field in the GraphQL schema.
This field lets you search and paginate over articles. The example below returns the first 15 articles tagged with united states or onboarding, ordered by creation date.
Each article in the response includes an id. Save this value since you need it to retrieve the full content of a single article.
query ($offset: Int, $limit: Int, $search: String, $orderBy: PageOrderBy, $orderByDirection: PageOrderByDirection, $count: Boolean, $publicationState: Boolean, $tags: [String!]) {
pages {
list(offset: $offset, limit: $limit, orderBy: $orderBy, orderByDirection: $orderByDirection, count: $count, tags: $tags, search: $search, publicationState: $publicationState) {
items {
id
locale
path
title
description
contentType
privateNS
tags
createdAt
updatedAt
}
totalCount
}
}
}
variables {
"offset": 0,
"limit": 15,
"search": "",
"orderBy": "CREATED",
"orderByDirection": "DESC",
"count": true,
"tags": ["united states", "onboarding"],
"publicationState": true,
"isTagsLogicAnd": false
}
Response
{
"data": {
"pages": {
"list": {
"items": [
{
"id": 409,
"locale": "en",
"path": "internal/ckb/switzerland/onboarding/pension-onboarding",
"title": "Pension Onboarding: Switzerland",
"description": "Pension Onboarding information for Switzerland",
"contentType": "html",
"privateNS": null,
"tags": [
"country knowledge base",
"employer of record",
"internal",
"onboarding",
"pension",
"switzerland",
"x_user-client",
"x_user-eor-employee"
],
"createdAt": "2023-02-15T09:56:12.912Z",
"updatedAt": "2025-05-28T15:53:47.349Z"
},
{
"id": 507,
"locale": "en",
"path": "internal/ckb/brazil/onboarding/process",
"title": "🔍 Brazil: Onboarding Process",
"description": "information about the onboarding process for EOR employees in Brazil",
"contentType": "html",
"privateNS": null,
"tags": [
"brazil",
"country knowledge base",
"employer of record",
"internal",
"onboarding",
"x_user-client",
"x_user-eor-employee"
],
"createdAt": "2023-02-15T18:47:30.525Z",
"updatedAt": "2025-05-09T14:47:53.813Z"
},
{
"id": 508,
"locale": "en",
"path": "internal/ckb/brazil/onboarding/compliance-documents",
"title": "Onboarding Compliance Documents: Brazil",
"description": "Information about onboarding and compliance documents for EOR employees in Brazil",
"contentType": "html",
"privateNS": null,
"tags": [
"brazil",
"compliance documents",
"country knowledge base",
"employer of record",
"internal",
"onboarding",
"x_user-client",
"x_user-eor-employee"
],
"createdAt": "2023-02-15T18:48:19.902Z",
"updatedAt": "2025-05-09T14:47:53.813Z"
}
...
],
"totalCount": 259
}
}
}
}
Step 4. Retrieve a single article
You can fetch further detail of a Wiki article using the pages.single GraphQL endpoint. After retrieving a list of articles, take the id from the response and use it to load the article's details.
The response includes a render key. This contains the rendered HTML version of the article. You will use this value to display the article in your frontend.
Here's an example query to fetch the details of the article with ID 409:
query ($id: Int!, $optimizeMarkup: Boolean, $addWrapperStructure: Boolean) {
pages {
single(id: $id, optimizeMarkup: $optimizeMarkup, addWrapperStructure: $addWrapperStructure) {
id
locale
path
title
description
contentType
privateNS
tags {
id
tag
}
authorId
authorName
creatorName
render
createdAt
updatedAt
}
}
}
variables {
"id": 409,
"optimizeMarkup": true,
"addWrapperStructure": true
}
Response
{
"data": {
"pages": {
"single": {
"id": 409,
"locale": "en",
"path": "internal/ckb/switzerland/onboarding/pension-onboarding",
"title": "Pension Onboarding: Switzerland",
"description": "Pension Onboarding information for Switzerland",
"contentType": "html",
"privateNS": null,
"tags": [
{
"id": 2,
"tag": "internal"
},
{
"id": 17,
"tag": "onboarding"
}
],
"authorId": 14,
"render": "<div>HTML</div>",
"creatorName": "Camilla Marziani",
"createdAt": "2023-02-15T09:56:12.912Z",
"updatedAt": "2025-05-28T15:53:47.349Z"
}
}
}
}
Step 5. Render the article
When the Wiki initializer script loads, it attaches a WikiUtils object to window.wikiUtils. This object exposes the following API:
interface LinkHandlers {
onSystemWikiLinkClick?: (path: string, hash?: string) => void
onInternalWikiLinkClick?: (path: string) => void
onAssetWikiLinkClick?: (path: string) => void
}
interface ArticleMeta {
scriptCss?: string
scriptJs?: string
}
interface WikiUtils {
renderArticle(
ref: HTMLDivElement,
articleHtml: string,
wikiUrl: string,
articleMeta?: ArticleMeta | null,
theme?: string | null,
handlers?: LinkHandlers
): Promise<void>
closeArticle(): void
}
Once you have fetched the article data, call the renderArticle method to display it in your frontend:
window.wikiUtils.renderArticle(ref, wikiUrl, articleHtml, articleMeta, theme, handlers)
Where parameters are:
ref: Reference to the HTML container element where the article will be rendered.articleHtml: The HTML (render key) of the article.wikiUrl: The Wiki domain to use. Choose based on the [target environment]((#include-the-wiki-initializer-script).- (Optional)
articleMeta?: Object with custom CSS or required for the article, if available. - (Optional)
theme?: Display theme, either light (default) or dark. - (Optional)
handlers?: Callbacks for handling clicks on external, internal Wiki, or asset links.
Troubleshooting
Add these typings to your project to avoid lint errors related to window.wikiUtils.
declare global {
interface Window {
wikiUtils?: WikiUtils
}
}
interface LinkHandlers {
onSystemWikiLinkClick?: (path: string, hash?: string) => void
onInternalWikiLinkClick?: (path: string) => void
onAssetWikiLinkClick?: (path: string) => void
}
interface ArticleMeta {
scriptCss?: string
scriptJs?: string
}
interface WikiUtils {
renderArticle(
ref: HTMLDivElement,
articleHtml: string,
url: string,
articleMeta?: ArticleMeta | null,
theme?: string | null,
handlers?: LinkHandlers
): Promise<void>
closeArticle(): void
}
Updated about 4 hours ago