Text Library API

The Text Library API lets you find, create, change and delete the texts and folders of the Studio Text Library from your own system. This page is about the Text Library in Studio. It is not the standalone Text Library 2 service. The Studio Text Library is described in the overview.

Every host on this page follows the environment you pick here.

The calls are listed in the API reference of the Smartforms API, in the group TextLibrary. The reference is at https://smartforms.metaforce.net/documentation-api.

Before you start

• You need a client with the api.external scope for your company. See Authentication. The calls work on your company only. There is no company parameter: the company comes from the token.
• The API works on your company’s shared folders. A person’s private Home and the texts in it are not visible.
• Changes are made in Development. Publish the folders to the other environments in Studio, see Environments.
• Every call answers 401 Unauthorized without a valid token and 403 Forbidden when the client has no company or no access.

Find folders and texts

curl --location 'https://api.smartforms.metaforce.net/Integrations/textlibrary/search?q=sick&page=0&pageSize=20&sortBy=name' --header 'Authorization: Bearer <your_token>'

The answer has the texts in pages and all matching folders:

{
  "texts": {
    "items": [
      {
        "id": "6697afe9b039be06934828bc",
        "folderId": "6697afe9b039be06934828aa",
        "code": "sick-leave",
        "name": "Sick leave letter",
        "description": "Standard letter",
        "contentType": 1,
        "isPublic": true,
        "defaultLanguage": "en",
        "translations": {
          "en": { "content": "Dear employee", "source": 0 }
        }
      }
    ],
    "page": 0,
    "pageSize": 20,
    "totalCount": 1,
    "totalPages": 1
  },
  "folders": [
    { "id": "6697afe9b039be06934828aa", "name": "HR letters", "parentFolderId": null, "isDefault": false, "code": "HRDOCS" }
  ]
}

Other reads:

• GET /Integrations/textlibrary/folders lists the folders, each with its code. Start here to find the id of a folder.
• GET /Integrations/textlibrary/texts/{id} reads one text.

Create and change folders

curl --location 'https://api.smartforms.metaforce.net/Integrations/textlibrary/folders' --header 'Content-Type: application/json' --header 'Authorization: Bearer <your_token>' --data '{ "name": "HR letters", "code": "HRDOCS" }'

A code holds letters, digits, dots, dashes and underscores, and is used in references instead of the folder name, so the references keep working if you rename the folder.

Create and change texts

curl --location 'https://api.smartforms.metaforce.net/Integrations/textlibrary/texts' --header 'Content-Type: application/json' --header 'Authorization: Bearer <your_token>' --data '{
"folderId": "6697afe9b039be06934828aa",
"code": "sick-leave",
"name": "Sick leave letter",
"description": "Standard letter",
"contentType": 1,
"isPublic": true,
"defaultLanguage": "en",
"translations": {
  "en": { "content": "Dear employee" },
  "no": { "content": "Kjære medarbeider" }
}
}'

A reference to the text in a Smartform is [[ LIB : HRDOCS : sick-leave ]], with the folder code and the text code. See Using Texts.

Rules and errors

• A text code is unique in its folder and in the folders under the same top folder.
• A folder name is unique at its level, and a folder code is unique in your company.