Company Legal Documents

These texts must be agreed to by candidates during the registration process.

List of languages in which legal texts are available

/companies/{{companyId}}/legal/

API clients need to request this endpoint first and find the appropriate language code in the response keys. Depending on the company, different languages may be enabled (see languages). Clients should then request the URL in the value to retrieve a list of legal documents in that language.

POST support is currently under development. Please contact viasto support before using it.

When POSTing a new legal text, the request goes to this .../legal/ endpoint and the language is specified in the payload.

POSTing a new legal text will replace any existing legal text with the same language and doc_type. This is the only way to make changes (no PATCH support).

DELETEing a legal document is impossible; it is, however, possible to POST a legal document with an empty text value.

Methods

• GET (no authentication required)
• POST (authentication required)

Example response

{
  "en-GB": "https://company.interview-suite.com/api/v3/companies/123/legal/en-gb/",
  "en-US": "https://company.interview-suite.com/api/v3/companies/123/legal/en-us/",
  "de-DE": "https://company.interview-suite.com/api/v3/companies/123/legal/de-de/",
  "es-ES": "https://company.interview-suite.com/api/v3/companies/123/legal/es-es/"
}

List of legal texts available for a language

/companies/{{companyId}}/legal/en-us/

When retrieving documents, it’s usually necessary to filter by language and doc_type on the client. Some legacy clients filter by type.

Methods

• GET (no authentication required)
  • requests without authentication or with authentication from a candidate will only return active documents. That means that DPPs will always be returned, while DOCs will only be returned iff the DOC_required flag is set to true for the company (see company basic settings)
  • requests with authentication from a customer-level or above account will always return all recent documents, i.e. the latest available one for every combination of doc_type and language
• POST (authentication required)
  • when POSTing documents of the 'site_notice' doc_type, the backend will only accept new objects with the 'en' language. This does not have to represent the actual language (or languages) of the site notice; it is simply because site notices are language-agnostic in the system

Response attributes

Name	Type	Description
title	string	Document title (use for document header and links to the document). Clients displaying a document should include a fallback title in case this is ommitted.
text	string	Document body as HTML. Unsupported/unsafe tags will be silently removed.
type	array read only	0 or more strings that can be used to identify the intended audience/purpose for the document eg ‘candidate’, ‘registration’
doc_type	string	one of ‘DOC’ (Declaration of Consent) or ‘DPP’ (Data Protection Policy) or ‘mail_footer’ (Email footer) or ‘site_notice’ (Site notice / Impressum)
language	string	one of the enabled languages for candidates in the company
active_projects	integer	available only to authenticated customers indicates number of active projects in legal document’s language; read only
resource_uri	reference	this is used to record which version of a legal document a user agreed to

Example response

[
  {
    "title": "Declaration of Consent",
    "text": "...",
    "type": [
        "candidate",
        "registration",
        "footer"
    ],
    "doc_type": "DOC",
    "language": "en",
    "resource_uri": "..."
  }, {
    "title": "Privacy Agreement",
    "text": "...",
    "type": [
        "candidate",
        "footer"
    ],
    "doc_type": "DPP",
    "language": "en",
    "resource_uri": "..."
  }
]