API Documentation

How to use the API

Specific users of this database are given the ability to create statements of reasons using an API endpoint. This greatly increases efficiency and allows for automation.

Requesting API access

To set up your statement of reasons submission process, please register here regarding your obligations under article 24(5) of the DSA. After receiving your registration form, the Digital Service Coordinator of your Member State will contact you providing the details on how to complete the onboarding of your online platform.

Once you are onboarded via your Digital Service Coordinator, you will gain access to a sandbox environment to test your submissions to the DSA Transparency Database, which you can perform either via an Application Programming Interface ( API) or a webform, according to the volume of your data and technical needs.

Once the testing phase is completed, you will be able to move to the production environment of the DSA Transparency Database, where you can start submitting your statement of reasons via an API or a webform.

Your API Token

When your account is given the ability to use the API then you are able to generate a private secure token that will allow you to use the API.

This token looks something like this:

    X|ybqkCFX7ZkIFoLxtI0VAk1JBzMR9jVk4c4EU

If you do not know your token or need to generate a new token you may do so in the user profile of this application. Simply click the button "Generate New Token"

This token will be shown one time, so it will need to be copied and stored safely.

Each time you generate a new token the old token becomes invalid!

Security Warning

This token identifies calls to the API as you! Do not share this token with other entities. They will be able to impersonate and act as you! If you believe that someone is using your token please generate a new token immediately to invalidate the old one.

Creating a Statement

To create a statement of reason using the API you will need to make a POST request to this endpoint.

    https://transparency.dsa.ec.europa.eu/api/v1/statement

For this request you will need to provide authorization, accept, and content type headers of the request:

    Authorization: Bearer YOUR_TOKEN
    Accept: application/json
    Content-Type: application/json

The body of your request needs to be a json encoded payload with the information of the statement

Example JSON payload body:

{
    "decision_visibility": ["DECISION_VISIBILITY_CONTENT_DISABLED"],
    "decision_monetary": "DECISION_MONETARY_TERMINATION",
    "end_date_monetary_restriction": "2023-08-08",
    "decision_provision": "DECISION_PROVISION_TOTAL_SUSPENSION",
    "decision_account": "DECISION_ACCOUNT_SUSPENDED",
    "account_type": "ACCOUNT_TYPE_BUSINESS",
    "decision_ground": "DECISION_GROUND_INCOMPATIBLE_CONTENT",
    "decision_ground_reference_url": "https://www.anurl.com",
    "content_type": ["CONTENT_TYPE_VIDEO","CONTENT_TYPE_AUDIO","CONTENT_TYPE_SYNTHETIC_MEDIA"],
    "category": "STATEMENT_CATEGORY_PORNOGRAPHY_OR_SEXUALIZED_CONTENT",
    "illegal_content_legal_ground": "illegal content legal grounds",
    "illegal_content_explanation": "illegal content explanation",
    "incompatible_content_ground": "incompatible content grounds",
    "incompatible_content_explanation": "incompatible content explanation",
    "incompatible_content_illegal": "Yes",
    "territorial_scope": [
        "PT",
        "ES",
        "DE"
    ],
    "content_language": "EN",
    "content_date": "2023-08-08",
    "application_date": "2023-08-08",
    "decision_facts": "facts about the decision",
    "source_type": "SOURCE_TRUSTED_FLAGGER",
    "automated_detection": "No",
    "automated_decision": "AUTOMATED_DECISION_PARTIALLY",
    "puid": "TK421"
}

The Response

When the request has been sent and it is correct, a response of 201 Created will be sent back.

You will also receive a payload with the statement as created in the database:

{
    "decision_visibility": [
        "DECISION_VISIBILITY_CONTENT_DISABLED"
    ],
    "decision_monetary": "DECISION_MONETARY_TERMINATION",
    "decision_provision": "DECISION_PROVISION_TOTAL_SUSPENSION",
    "decision_account": "DECISION_ACCOUNT_SUSPENDED",
    "account_type": "ACCOUNT_TYPE_BUSINESS",
    "decision_ground": "DECISION_GROUND_INCOMPATIBLE_CONTENT",
    "decision_ground_reference_url": "https:\/\/www.anurl.com",
    "incompatible_content_ground": "incompatible content grounds",
    "incompatible_content_explanation": "incompatible content explanation",
    "incompatible_content_illegal": "Yes",
    "content_type": [
        "CONTENT_TYPE_AUDIO",
        "CONTENT_TYPE_SYNTHETIC_MEDIA",
        "CONTENT_TYPE_VIDEO"
    ],
    "category": "STATEMENT_CATEGORY_PORNOGRAPHY_OR_SEXUALIZED_CONTENT",
    "territorial_scope": [
        "DE",
        "ES",
        "PT"
    ],
    "content_language": "EN",
    "content_date": "2023-08-08",
    "application_date": "2023-08-08",
    "end_date_monetary_restriction": "2023-08-08",
    "decision_facts": "facts about the decision",
    "source_type": "SOURCE_TRUSTED_FLAGGER",
    "automated_detection": "No",
    "automated_decision": "AUTOMATED_DECISION_PARTIALLY",
    "end_date_visibility_restriction": null,
    "end_date_account_restriction": null,
    "end_date_service_restriction": null,
    "puid": "TK421",
    "uuid": "7d0d0f7c-3ba9-45ba-966a-ec621eb17225",
    "platform_name": "...",
    "created_at": "2023-08-08 08:08:08",
    "permalink": ".... statement/7d0d0f7c-3ba9-45ba-966a-ec621eb17225",
    "self": ".... api/v1/statement/7d0d0f7c-3ba9-45ba-966a-ec621eb17225"
}

Important

Anytime you make a call to an API you should always validate that you did receive the proper status, '201 Created'. If you did not receive a 201 Created, then the statement was not made, it is not in the database and you will need to retry at a later time.

UUID

Every statement created in the database receives an UUID which identifies the statement uniquely.

This UUID is then used in the urls for retrieving and viewing the statement online.

These urls are present in the response after creating as the "uuid", "permalink" and "self" attributes.

Creating Multiple Statements

We highly encourage all platforms to bundle and create multiple Statements of Reason in one API call using the multiple endpoint.

Please to make a POST request to this endpoint.

    https://transparency.dsa.ec.europa.eu/api/v1/statements

The payload of this request should contain one field called "statements" and that field needs to be an array of Statements of Reason.

Here is an example:

{
    "statements": [
        {
            "decision_visibility": [
                "DECISION_VISIBILITY_CONTENT_DISABLED"
            ],
            "decision_monetary": "DECISION_MONETARY_TERMINATION",
            "decision_provision": "DECISION_PROVISION_TOTAL_SUSPENSION",
            ...
            ...
        },
        {
            "decision_visibility": [
                "DECISION_VISIBILITY_CONTENT_DISABLED"
            ],
            "decision_monetary": "DECISION_MONETARY_TERMINATION",
            "decision_provision": "DECISION_PROVISION_TOTAL_SUSPENSION",
            ...
            ...
        },
        {
            "decision_visibility": [
                "DECISION_VISIBILITY_CONTENT_DISABLED"
            ],
            "decision_monetary": "DECISION_MONETARY_TERMINATION",
            "decision_provision": "DECISION_PROVISION_TOTAL_SUSPENSION",
            ...
            ...
        }
        ...
    ]
}

The multiple endpoint is capable of making 100 statements per call.

When the request has been sent and it is correct, a response of 201 Created will be sent back.

The response payload when calling the multiple endpoint will be an array of the Statements of Reason when successful. Each Statement of Reason will then have an uuid, created_at, self, and permalink attribute to reflect that it was created.

{
    "statements": [
        {
            "decision_visibility": [
                "DECISION_VISIBILITY_CONTENT_DEMOTED"
            ],
            "decision_monetary": "DECISION_MONETARY_OTHER",
            ...
            ...
            "uuid": "bf92a941-c77a-4b9d-a236-38956ae79cc5",
            "created_at": "2023-11-07 07:53:43",
            "platform_name": "DSA Team",
            "permalink": "https://.../statement/bf92a941-c77a-4b9d-a236-38956ae79cc5",
            "self": "https://.../api/v1/statement/bf92a941-c77a-4b9d-a236-38956ae79cc5",
            "puid": "b5ec958d-892a-4c11-a3f2-6a3ad597eeb1"
        },
        {
            "decision_visibility": [
                "DECISION_VISIBILITY_CONTENT_DEMOTED"
            ],
            ...
            ...
            ...
            "uuid": "174a1921-0d9e-4864-b095-6774fb0237da",
            "created_at": "2023-11-07 07:53:44",
            "platform_name": "DSA Team",
            "permalink": "https://.../statement/174a1921-0d9e-4864-b095-6774fb0237da",
            "self": "https://.../api/v1/statement/174a1921-0d9e-4864-b095-6774fb0237da",
            "puid": "a12b436a-33b1-4403-99b2-8c16e3c5502f"
        },
        {
            "decision_account": "DECISION_ACCOUNT_SUSPENDED",
            "account_type": "ACCOUNT_TYPE_PRIVATE",
            "decision_ground": "DECISION_GROUND_INCOMPATIBLE_CONTENT",
            ...
            ...
            ...
            "uuid": "b8f03bf5-b8fd-4987-ac56-6fe6ab155e9e",
            "created_at": "2023-11-07 07:53:45",
            "platform_name": "DSA Team",
            "permalink": "https://.../statement/b8f03bf5-b8fd-4987-ac56-6fe6ab155e9e",
            "self": "https://.../api/v1/statement/b8f03bf5-b8fd-4987-ac56-6fe6ab155e9e",
            "puid": "649c58f6-8412-4100-b10c-010b76f5a41a"
        },
        ...
    ]
}

Statement Attributes

The attributes of the statement take on two main forms.

free textual (max character limits apply, see below)
limited, the value provided needs to be one of the allowed options

When submitting statements please take care to not submit ANY personal data. On a regular basis we will do checks on the database to ensure that no personal data has been submitted. However, in accordance with Article 24(5), it is the obligation of providers of online platforms to ensure that the information submitted does not contain personal data.

Additional Explanation For Statement Attributes

Please refer to our Additional Explanation For Statement Attributes page for more information about the attributes.

Decision Visibility (decision_visibility)

This attribute tells us the visibility restriction of specific items of information provided by the recipient of the service.

This attribute is mandatory only if the following fields are empty: decision_monetary, decision_provision and decision_account

The value provided must be an array with at least one of the following:

DECISION_VISIBILITY_CONTENT_REMOVED
- Removal of content
DECISION_VISIBILITY_CONTENT_DISABLED
- Disabling access to content
DECISION_VISIBILITY_CONTENT_DEMOTED
- Demotion of content
DECISION_VISIBILITY_CONTENT_AGE_RESTRICTED
- Age restricted content
DECISION_VISIBILITY_CONTENT_INTERACTION_RESTRICTED
- Restricting interaction with content
DECISION_VISIBILITY_CONTENT_LABELLED
- Labelled content
DECISION_VISIBILITY_OTHER
- Other restriction (please specify)

Decision Visibility Other (decision_visibility_other)

This is required if DECISION_VISIBILITY_OTHER was the decision_visibility.

Limited to 500 characters.

Monetary payments suspension, termination or other restriction (decision_monetary)

This is an attribute that gives information about the Monetary payments suspension, termination or other restriction

This attribute is mandatory only if the following fields are empty: decision_visibility, decision_provision and decision_account

The value provided must be one of the following:

DECISION_MONETARY_SUSPENSION
- Suspension of monetary payments
DECISION_MONETARY_TERMINATION
- Termination of monetary payments
DECISION_MONETARY_OTHER
- Other restriction (please specify)

Decision Monetary Other (decision_monetary_other)

This is required if DECISION_MONETARY_OTHER was the decision_monetary.

Limited to 500 characters.

Decision about the provisioning of the service (decision_provision)

This is an attribute that tells us about the suspension or termination of the provision of the service.

This attribute is mandatory only if the following fields are empty: decision_visibility, decision_monetary and decision_account

The value provided must be one of the following:

DECISION_PROVISION_PARTIAL_SUSPENSION
- Partial suspension of the provision of the service
DECISION_PROVISION_TOTAL_SUSPENSION
- Total suspension of the provision of the service
DECISION_PROVISION_PARTIAL_TERMINATION
- Partial termination of the provision of the service
DECISION_PROVISION_TOTAL_TERMINATION
- Total termination of the provision of the service

Decision about the account's status (decision_account)

This is an attribute that tells us about the account's status.

This attribute is mandatory only if the following fields are empty: decision_visibility, decision_monetary and decision_provision

The value provided must be one of the following:

DECISION_ACCOUNT_SUSPENDED
- Suspension of the account
DECISION_ACCOUNT_TERMINATED
- Termination of the account

Account Type (account_type)

This is an attribute that tells us about the account's type.

This attribute is optional.

The value provided must be one of the following:

ACCOUNT_TYPE_BUSINESS
- Business
ACCOUNT_TYPE_PRIVATE
- Private

Facts and circumstances relied on in taking the decision (decision_facts)

This is a required textual field to describe the facts and circumstances relied on in taking the decision.

Limited to 5000 characters.

Decision Grounds (decision_ground)

This is a required field and tells us the basis on which the decision was taken.

DECISION_GROUND_ILLEGAL_CONTENT
- Illegal Content
DECISION_GROUND_INCOMPATIBLE_CONTENT
- Content incompatible with terms and conditions

Decision Ground Reference Url (decision_ground_reference_url)

This is an url to the TOS or Law relied upon in taking the decision.

This is an optional attribute.

Illegal Content Legal Grounds (illegal_content_legal_ground)

This is required if the DECISION_GROUND_ILLEGAL_CONTENT was the decision_ground. It is the legal grounds relied on.

Limited to 500 characters.

Illegal Content Explanation (illegal_content_explanation)

This is required if the DECISION_GROUND_ILLEGAL_CONTENT was the decision_ground. This is a text that explains why the content was illegal.

Limited to 2000 characters.

Incompatible Content Grounds (incompatible_content_ground)

This is required if DECISION_GROUND_INCOMPATIBLE_CONTENT was the decision_ground. It is the reference to contractual grounds.

Limited to 500 characters.

Incompatible Content Explanation (incompatible_content_explanation)

This is required if DECISION_GROUND_INCOMPATIBLE_CONTENT was the decision_ground. This is a text that explains why the content is considered as incompatible on that ground.

Limited to 2000 characters.

Incompatible Content Illegal (incompatible_content_illegal)

This is an optional attribute and it can be in the form "Yes" or "No". This is a possibility to indicate that the content was not only considered incompatible but also illegal.

Content Type (content_type)

This is a required attribute, and it tells us what type of content is targeted by the statement of reason.

The value provided must be an array with at least one of the following:

CONTENT_TYPE_APP
- App
CONTENT_TYPE_AUDIO
- Audio
CONTENT_TYPE_IMAGE
- Image
CONTENT_TYPE_PRODUCT
- Product
CONTENT_TYPE_SYNTHETIC_MEDIA
- Synthetic Media
CONTENT_TYPE_TEXT
- Text
CONTENT_TYPE_VIDEO
- Video
CONTENT_TYPE_OTHER
- Other

Content Type Other (content_type_other)

This is required if CONTENT_TYPE_OTHER was the content_type. It is a content type that is not part of provided content type list.

Limited to 500 characters.

Category (category)

This is a required attribute, and it tells us which category the statement belongs to.

The value provided must be one of the following:

STATEMENT_CATEGORY_ANIMAL_WELFARE
- Animal welfare
STATEMENT_CATEGORY_DATA_PROTECTION_AND_PRIVACY_VIOLATIONS
- Data protection and privacy violations
STATEMENT_CATEGORY_ILLEGAL_OR_HARMFUL_SPEECH
- Illegal or harmful speech
STATEMENT_CATEGORY_INTELLECTUAL_PROPERTY_INFRINGEMENTS
- Intellectual property infringements
STATEMENT_CATEGORY_NEGATIVE_EFFECTS_ON_CIVIC_DISCOURSE_OR_ELECTIONS
- Negative effects on civic discourse or elections
STATEMENT_CATEGORY_NON_CONSENSUAL_BEHAVIOUR
- Non-consensual behaviour
STATEMENT_CATEGORY_PORNOGRAPHY_OR_SEXUALIZED_CONTENT
- Pornography or sexualized content
STATEMENT_CATEGORY_PROTECTION_OF_MINORS
- Protection of minors
STATEMENT_CATEGORY_RISK_FOR_PUBLIC_SECURITY
- Risk for public security
STATEMENT_CATEGORY_SCAMS_AND_FRAUD
- Scams and/or fraud
STATEMENT_CATEGORY_SELF_HARM
- Self-harm
STATEMENT_CATEGORY_SCOPE_OF_PLATFORM_SERVICE
- Scope of platform service
STATEMENT_CATEGORY_UNSAFE_AND_ILLEGAL_PRODUCTS
- Unsafe and/or illegal products
STATEMENT_CATEGORY_VIOLENCE
- Violence

Additional Categories (category_addition)

This is an optional attribute, and it tells us which additional categories the statement belongs to.

The value provided must be an array with one of the following:

STATEMENT_CATEGORY_ANIMAL_WELFARE
- Animal welfare
STATEMENT_CATEGORY_DATA_PROTECTION_AND_PRIVACY_VIOLATIONS
- Data protection and privacy violations
STATEMENT_CATEGORY_ILLEGAL_OR_HARMFUL_SPEECH
- Illegal or harmful speech
STATEMENT_CATEGORY_INTELLECTUAL_PROPERTY_INFRINGEMENTS
- Intellectual property infringements
STATEMENT_CATEGORY_NEGATIVE_EFFECTS_ON_CIVIC_DISCOURSE_OR_ELECTIONS
- Negative effects on civic discourse or elections
STATEMENT_CATEGORY_NON_CONSENSUAL_BEHAVIOUR
- Non-consensual behaviour
STATEMENT_CATEGORY_PORNOGRAPHY_OR_SEXUALIZED_CONTENT
- Pornography or sexualized content
STATEMENT_CATEGORY_PROTECTION_OF_MINORS
- Protection of minors
STATEMENT_CATEGORY_RISK_FOR_PUBLIC_SECURITY
- Risk for public security
STATEMENT_CATEGORY_SCAMS_AND_FRAUD
- Scams and/or fraud
STATEMENT_CATEGORY_SELF_HARM
- Self-harm
STATEMENT_CATEGORY_SCOPE_OF_PLATFORM_SERVICE
- Scope of platform service
STATEMENT_CATEGORY_UNSAFE_AND_ILLEGAL_PRODUCTS
- Unsafe and/or illegal products
STATEMENT_CATEGORY_VIOLENCE
- Violence

Category Specification (category_specification)

This is an optional attribute, and it tells us which additional keywords the statement belongs to.

The value provided must be an array with one of the following:

KEYWORD_ANIMAL_HARM
- Animal Harm
KEYWORD_ADULT_SEXUAL_MATERIAL
- Adult Sexual Material
KEYWORD_AGE_SPECIFIC_RESTRICTIONS_MINORS
- Age-Specific Restrictions Concerning Minors
KEYWORD_AGE_SPECIFIC_RESTRICTIONS
- Age-Specific Restrictions
KEYWORD_BIOMETRIC_DATA_BREACH
- Biometric Data Breach
KEYWORD_CHILD_SEXUAL_ABUSE_MATERIAL
- Child Sexual Abuse Material
KEYWORD_CONTENT_PROMOTING_EATING_DISORDERS
- Content Promoting Eating Disorders
KEYWORD_COORDINATED_HARM
- Coordinated Harm
KEYWORD_COPYRIGHT_INFRINGEMENT
- Copyright Infringement
KEYWORD_DANGEROUS_TOYS
- Dangerous Toys
KEYWORD_DATA_FALSIFICATION
- Data Falsification
KEYWORD_DEFAMATION
- Defamation
KEYWORD_DESIGN_INFRINGEMENT
- Design Infringement
KEYWORD_DISCRIMINATION
- Discrimination
KEYWORD_DISINFORMATION
- Disinformation
KEYWORD_FOREIGN_INFORMATION_MANIPULATION
- Foreign Information Manipulation and Interference
KEYWORD_GENDER_BASED_VIOLENCE
- Gender-Based Violence
KEYWORD_GEOGRAPHIC_INDICATIONS_INFRINGEMENT
- Geographic Indications Infringements
KEYWORD_GEOGRAPHICAL_REQUIREMENTS
- Geographical Requirements
KEYWORD_GOODS_SERVICES_NOT_PERMITTED
- Goods/Services Not Permitted to Be Offered on the Platform
KEYWORD_GROOMING_SEXUAL_ENTICEMENT_MINORS
- Grooming/Sexual Enticement of Minors
KEYWORD_HATE_SPEECH
- Hate Speech
KEYWORD_HUMAN_EXPLOITATION
- Human Exploitation
KEYWORD_HUMAN_TRAFFICKING
- Human Trafficking
KEYWORD_ILLEGAL_ORGANIZATIONS
- Illegal Organizations
KEYWORD_IMAGE_BASED_SEXUAL_ABUSE
- Image-Based Sexual Abuse (excluding content depicting minors)
KEYWORD_IMPERSONATION_ACCOUNT_HIJACKING
- Impersonation or Account Hijacking
KEYWORD_INAUTHENTIC_ACCOUNTS
- Inauthentic Accounts
KEYWORD_INAUTHENTIC_LISTINGS
- Inauthentic Listings
KEYWORD_INAUTHENTIC_USER_REVIEWS
- Inauthentic User Reviews
KEYWORD_INCITEMENT_VIOLENCE_HATRED
- Incitement to Violence and/or Hatred
KEYWORD_INSUFFICIENT_INFORMATION_TRADERS
- Insufficient Information on Traders
KEYWORD_LANGUAGE_REQUIREMENTS
- Language Requirements
KEYWORD_MISINFORMATION
- Misinformation
KEYWORD_MISSING_PROCESSING_GROUND
- Missing Processing Ground for Data
KEYWORD_NON_CONSENSUAL_IMAGE_SHARING
- Non-Consensual Image Sharing
KEYWORD_NON_CONSENSUAL_ITEMS_DEEPFAKE
- Non-Consensual Items Containing Deepfake or Similar Technology Using a Third Party’s Features
KEYWORD_NUDITY
- Nudity
KEYWORD_ONLINE_BULLYING_INTIMIDATION
- Online Bullying/Intimidation
KEYWORD_PATENT_INFRINGEMENT
- Patent Infringement
KEYWORD_PHISHING
- Phishing
KEYWORD_PYRAMID_SCHEMES
- Pyramid Schemes
KEYWORD_REGULATED_GOODS_SERVICES
- Regulated Goods and Services
KEYWORD_RIGHT_TO_BE_FORGOTTEN
- Right to Be Forgotten
KEYWORD_RISK_ENVIRONMENTAL_DAMAGE
- Risk for Environmental Damage
KEYWORD_RISK_PUBLIC_HEALTH
- Risk for Public Health
KEYWORD_SELF_MUTILATION
- Self-Mutilation
KEYWORD_STALKING
- Stalking
KEYWORD_SUICIDE
- Suicide
KEYWORD_TERRORIST_CONTENT
- Terrorist Content
KEYWORD_TRADE_SECRET_INFRINGEMENT
- Trade Secret Infringement
KEYWORD_TRADEMARK_INFRINGEMENT
- Trademark Infringement
KEYWORD_UNLAWFUL_SALE_ANIMALS
- Unlawful Sale of Animals
KEYWORD_UNSAFE_CHALLENGES
- Unsafe Challenges
KEYWORD_OTHER
- Other

Other Keyword (category_specification_other)

This field can be provided if KEYWORD_OTHER is part of the category_specification.

Limited to 500 characters.

Territorial Scope (territorial_scope)

This is a required attribute that defines territorial scope of the restriction. Each value must be the 2-letter iso code for the country and the countries must be (EU/EEA) countries.

The value provided must be an array.

Allowed values are:

AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK

For European Union (EU) use:

["AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GR", "HR", "HU", "IE", "IT", "LT", "LU", "LV", "MT", "NL", "PL", "PT", "RO", "SE", "SI", "SK"]

For European Economic Area (EEA) use:

["AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GR", "HR", "HU", "IE", "IS", "IT", "LI", "LT", "LU", "LV", "MT", "NL", "NO", "PL", "PT", "RO", "SE", "SI", "SK"]

Content Language (content_language)

This is the language that the content was in.

This attribute is optional.

The value though must be one of the uppercase two letter ISO 639-1 codes.

Ex,

"EN", "BG", "HR", "CS", "DA", "NL", "ET", "FI", "FR", "DE", "EL", "HU", "GA", "IT", "LV", "LT", "MT", "PL", "PT", "RO", "SK", "SL", "ES", "SV"

Content Date (content_date)

This is a required date field that indicates the upload or posting date of the content. The date should follow this format:

YYYY-MM-DD

The day and the month have leading zeroes.

The date must be after or equal to 2000-01-01.

Application Date (application_date)

This is the date that this decision starts from. The date needs to take the form of:

YYYY-MM-DD

The day and the month have leading zeroes.

The date must be after or equal to 2020-01-01.

End Date of account restriction (end_date_account_restriction)

This is the date that the decision on the account ends. Leave blank for indefinite.

The date needs to take the form of:

YYYY-MM-DD

The day and the month have leading zeroes.

The date must be after or equal to the application date.

End Date of monetary restriction (end_date_monetary_restriction)

This is the date that the monetary decision ends. Leave blank for indefinite.

The date needs to take the form of:

YYYY-MM-DD

The day and the month have leading zeroes.

The date must be after or equal to the application date.

End Date of service restriction (end_date_service_restriction)

This is the date that the provision decision ends. Leave blank for indefinite.

The date needs to take the form of:

YYYY-MM-DD

The day and the month have leading zeroes.

The date must be after or equal to the application date.

End Date of visibility restriction (end_date_visibility_restriction)

This is the date that the visibility decision ends. Leave blank for indefinite.

The date needs to take the form of:

YYYY-MM-DD

The day and the month have leading zeroes.

The date must be after or equal to the application date.

Information source (source_type)

This is a required field and tells us the facts and circumstances relied upon in taking the decision.

The value provided must be one of the following:

SOURCE_ARTICLE_16
- Notice submitted in accordance with Article 16 DSA
SOURCE_TRUSTED_FLAGGER
- Notice submitted by a trusted flagger
SOURCE_TYPE_OTHER_NOTIFICATION
- Other type of notification
SOURCE_VOLUNTARY
- Own voluntary initiative

Source Identity (source_identity)

This is an optional field to describe the source/notifier if needed. Will not be taken into account if the 'source_type' is set to 'SOURCE_VOLUNTARY'

Limited to 500 characters.

Automated Detection (automated_detection)

This is a required attribute and it must be in the form "Yes" or "No". This indicates to us that decision taken in respect of automatically detected means.

Automated Decision (automated_decision)

This is a required attribute and it must be one of the following:

AUTOMATED_DECISION_FULLY
- Fully automated
AUTOMATED_DECISION_PARTIALLY
- Partially automated
AUTOMATED_DECISION_NOT_AUTOMATED
- Not Automated

Platform Unique Identifier (puid)

This is a string that uniquely identifies this statement within the platform. This attribute is required and it must be unique within your platform.

Limited to 500 characters and must contain alphanumeric characters (a-z, A-Z, 0-9), hyphens "-" and underscores "_" only. No spaces, new-line or any other special characters are accepted.

Existing PUID

There is an end point that will allow you to check if a PUID value is already used.

To check if an existing PUID is alread used in a statement of reason using the API you will need to make a GET request to this endpoint.

    https://transparency.dsa.ec.europa.eu/api/v1/statement/existing-puid/<PUID>

Where <PUID> is the puid that you would like to check if it is existing already in the database.

For this request you will need to provide authorization, accept, and content type headers of the request:

    Authorization: Bearer YOUR_TOKEN
    Accept: application/json
    Content-Type: application/json

The response will either be 404 Not Found or 302 Found.

When there is no statement found the body will contain the message.

{
    "message": "statement of reason not found"
}

When there is a statement found the existing statement will be returned in the body.

{
    "uuid": "4b449e79-a41f-4934-aa9a-9c442899951e",
    "decision_visibility": [
        "DECISION_VISIBILITY_CONTENT_REMOVED"
    ],
    "decision_visibility_other": null,
    ...

Errors

When a call to the API has been made AND there was an error in the call you may expect the following to occur:

You will NOT receive a HTTP Status Code 201 Created.
The statement of reason has NOT been created.
You receive back a payload that has more information in it.

For Ex,

You made an API with a blank JSON payload or an invalid JSON payload.

{}

The HTTP Status code coming back will be 422 Unproccessable Content

The payload body will be a JSON object containing more information and the errors in the API call.

{
    "message": "The decision visibility field is required when none of decision monetary / decision provision / decision account are present. (and 13 more errors)",
    "errors": {
        "decision_visibility": [
            "The decision visibility field is required when none of decision monetary / decision provision / decision account are present."
        ],
        "decision_monetary": [
            "The decision monetary field is required when none of decision visibility / decision provision / decision account are present."
        ],
        "decision_provision": [
            "The decision provision field is required when none of decision visibility / decision monetary / decision account are present."
        ],
        "decision_account": [
            "The decision account field is required when none of decision visibility / decision monetary / decision provision are present."
        ],
        "decision_ground": [
            "The decision ground field is required."
        ],
        "content_type": [
            "The content type field is required."
        ],
        "category": [
            "The category field is required."
        ],
        "application_date": [
            "The application date field is required."
        ],
        "decision_facts": [
            "The decision facts field is required."
        ],
        "source_type": [
            "The source type field is required."
        ],
        "automated_detection": [
            "The automated detection field is required."
        ],
        "automated_decision": [
            "The automated decision field is required."
        ],
        "puid": [
            "The puid field is required."
        ]
    }
}

The error messages for the individual fields will vary depending on what was attempted.

Such as the following:

If you sent

{
    ...
    "automated_decision":"maybe"
    ...
}

"Maybe" is not a valid value for automated_decision. (only "Yes" or "No")

{
    "message": "The selected automated decision is invalid.",
    "errors": {
        "automated_decision": [
            "The selected automated decision is invalid."
        ]
    }
}

Errors when Creating Multiple Statements of Reason

When you are you calling the multiple endpoint you will encounter the same errors as the single endpoint. However, the errors will be indexed to the Statement of Reason that you are trying to create.

ex,

{
    "errors": {
        "statement_0": {
            "decision_monetary": [
                "The selected decision monetary is invalid."
            ],
                "decision_ground": [
                "The selected decision ground is invalid."
            ],
                "automated_detection": [
                "The automated detection field is required."
            ]
        },
        "statement_2": {
            "decision_provision": [
                "The selected decision provision is invalid."
            ]
        }
    }
}

This means that the decision monetary, the decision ground and the automated detection fields were invalid in the statement of reason at position 0 in the array. This means that the decision provision is invalid in the statement of reason at position 2 in the array.

In this case, NONE of the statements where created, the request needs to be fixed and resent.

Token Error

Another common error that may occur when calling the API is that the authorization token is not valid.

This will result in a HTTP status code of 401 Unauthorized

The API authorization token needs to be double checked or a new API authorization token needs to be generated. See again the section above: Your API Token

In addition to the common 422 and 401 errors, Any of the standard 4XX HTTP can be encountered. 4XX statuses generally indicate that there is an issue with your request. Please try to troubleshoot and resolve the problem.

When there is an error of 5XX we are immediately notified and there is no need to report the issue.

PUID Error

When you attempt to create a statement for your platform and there exists a statement with the same puid, the response will still be 422 Unproccessable Content and the error returned will contain the existing the statement. This will look like the following:

{
  "message": "The identifier given is not unique within this platform.",
  "errors": {
    "puid": [
      "The identifier given is not unique within this platform."
    ]
  },
  "existing": {
    "uuid": "6bf8beb0-765c-4e79-8cb1-dc93fc7478bb",
    "decision_visibility": [
      ...
    ],
    ...
    "permalink": "... /statement/6bf8beb0-765c-4e79-8cb1-dc93fc7478bb",
    "self": "... /api/v1/statement/6bf8beb0-765c-4e79-8cb1-dc93fc7478bb"
  }
}

Source Code

The source code for this application can be viewed here:

DSA Transparency Database Source - GitHub

Using the repository code you can even setup and run a local replica development testing area.

Within the github environment you are also more than welcome to give feedback, pull requests and reviews concerning the source code.