Bulk Reporting

18 min

The Bulk Reporting API allows you to submit multiple cases to Nima in a single request, enabling efficient processing of large volumes of reports.

Overview

The Bulk Reporting API enables you to:

Submit multiple reports in a single API call

Process reports more efficiently with reduced API overhead

Maintain transactional integrity across multiple submissions

Scale your integration for high-volume reporting scenarios

API Endpoint:POST {endpoint-moderation}

How it works

The bulk action API:

Accepts an array of items in the request body

Processes multiple reports in a single transaction

Returns a summary response indicating the number of cases created

Example request

Below is an example payload showing how to submit multiple cases:

{
    "items": [
        {
            "priority": "severe",
            "channel": "user report",
            "reason_for_request": "Lorem Abuse reason_for_request",
            "customerSpecific": {
            },
            "content": {
                "content_id": "{{$randomPassword}}",
                "title": "Dangerous customisation of characters - {{$randomPassword}}",
                "body": "CaseyLegacy",
                "rawText": "CaseyLegacy",
                "token": "",
                "type": {
                    "id": "TXT",
                    "name": "TEXT"
                },
                "status": "published",
                "customerSpecific": {}
            },
            "reporter": {
                "id": "{{$randomPassword}}",
                "name": "Reporter James",
                "lang": "en",
                "phoneNumber": "070-123456",
                "emailAddress": "[email protected]",
                "customerSpecific": {}
            },
            "reportee": {
                "id": "{{$randomPassword}}",
                "name": "Reportee John",
                "lang": "en",
                "phoneNumber": "070-564123",
                "emailAddress": "[email protected]",
                "customerSpecific": {}
            },
            "location": {
                "city": "Stockholm",
                "postalCode": "111 57",
                "region": "Stockholm",
                "countryCode": "SE",
                "ipAddress": "192.168.0.1",
                "customerSpecific": {}
            },
            "label": [
                "Terrorist Propaganda"
            ]
        },
        {
            "priority": "severe",
            "channel": "user report",
            "reason_for_request": "Lorem Abuse reason_for_request",
            "customerSpecific": {
            },
            "content": {
                "content_id": "{{$randomPassword}}",
                "title": "Dangerous customisation of characters - {{$randomPassword}}",
                "body": "CaseySupporter01",
                "rawText": "CaseySupporter01",
                "token": "",
                "type": {
                    "id": "TXT",
                    "name": "TEXT"
                },
                "status": "published",
                "customerSpecific": {}
            },
            "reporter": {
                "id": "{{$randomPassword}}",
                "name": "Reporter James",
                "lang": "en",
                "phoneNumber": "070-123456",
                "emailAddress": "[email protected]",
                "customerSpecific": {}
            },
            "reportee": {
                "id": "{{$randomPassword}}",
                "name": "Reportee John",
                "lang": "en",
                "phoneNumber": "070-564123",
                "emailAddress": "[email protected]",
                "customerSpecific": {}
            },
            "location": {
                "city": "Stockholm",
                "postalCode": "111 57",
                "region": "Stockholm",
                "countryCode": "SE",
                "ipAddress": "192.168.0.1",
                "customerSpecific": {}
            },
            "label": [
                "Terrorist Propaganda"
            ]
        }
    ]
}

API response

Success response

The API returns a summary indicating the number of cases successfully scheduled for moderation:

{
    "message": "2 cases scheduled for moderation"
}

Request structure

While Proactive Detection in Nima and automated moderation will moderate the majority of harmful content and check all content posted, it may be the case that your users will report content.

In Nima, you can integrate your existing and current user reporting flow to make sure user reports are promptly reviewed by human moderators.

Note: This reporting flow is separate from the DSA reporting flow, which is instead detailed Illegal Content Report FormIllegal Content Report Form

Overview

The User Reports API of Nima allows you to connect your reporting flows to Nima. This enables your moderation team to review user-generated content reports from your platform and take action on flagged content through a centralized console.

API Endpoint: POST {endpoint-moderation} - the Tremau team will provide the precise endpoint

The review workflow

To integrate user reports from your platform into Nima, use the User Reports API. The workflow is as follows:

A user flags content on your platform

Your system sends the report to Nima via the User Reports API

Nima routes the report into a dedicated moderation queue

Your moderators review the report in the Nima console and take appropriate action

API integration

Making a request

Submit user reports by making a POST request to the provided endpoint. The request must include the required headers and a JSON payload containing the report details.

curl --location -g '{{url}}/queues/process-file' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "priority": "severe",
    "channel": "user report",
    "reason_for_request": "Lorem Abuse reason_for_request",
    "customerSpecific": {},
    "content": {
        "content_id": "098765434567",
        "title": "Content Title",
        "body": "An optional text description of the submitted content.",
        "url": "https://images.unsplash.com/photo-1585589266882-2cb137ba7db6?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=725&q=80",
        "token": "A livestreaming Video Token when Content Type is LiveStream",
        "type": {
            "id": "IMG"
        },
        "status": "published",
        "customerSpecific": {
        	"post_likes" : "12",
          "post_views" : "12"  
        }
    },
    "reporter": {
        "id": "321",
        "name": "Reporter James",
        "phoneNumber": "070-123456",
        "emailAddress": "[email protected]",
        "customerSpecific": {
       		"reporter_account_creation_date" : "2023-04-03",
          "reporter_account_verified" : "true"
        }
    },
    "reportee": {
        "id": "123",
        "name": "Reportee John",
        "phoneNumber": "070-564123",
        "emailAddress": "[email protected]",
        "customerSpecific": {
        	"reportee_account_creation_date" : "2023-04-03",
          "reportee_account_verified" : "true"
        }
    },
    "location": {
        "city": "Stockholm",
        "postalCode": "111 57",
        "region": "Stockholm",
        "countryCode": "SE",
        "ipAddress": "192.168.0.1",
        "customerSpecific": {}
    },
    "label": [
        "nudity"
    ]
}'

Request parameters

Global parameters

Parameter	Type	Required	Description
reason_for_request	String	Yes	User explains why he or she is reporting content or profile
priority	String	Yes	Priority of the incoming request. ['severe','high','medium','low']
channel	String	Yes	Channel specifies means by which report was made, in this case "user report". Takes from the following values: ['email', 'trusted flagger', 'automated detection', 'lea', 'user report']. In order to use automated detection features, channel must be set to 'automated detection'
customerSpecific	Object	No	Global customerSpecific attributes. AI detection providers will inject moderation results here before the case is placed into Nima
label	String[]	No	Main reason and policy infringement content is being reported for (example: "Hateful Content", "Terrorism", "Child Abuse", etc.)

Content

Parameter	Type	Required	Description
content.title	String	Yes	A title for the piece of content
content.content_id	String	Yes	ID corresponding to content that has been uploaded and reported by a user
content.url	String	Yes	Publicly available URL of reported content
content.type	Object	Yes	content.type sits as an object like this: "type": {"id": "TXT"}. Content type can have the following values: const VIDEO_STREAM = "Video Stream"; const VIDEO_STATIC = "Video Static"; const IMG = "Image"; const AUDIO = "Audio"; const TXT = "Text"; const IFRAME = "Iframe"; const PDF = "Pdf"; const FILE = 'File' where the id is the enum in caps
content.rawText	String	No	Raw text is used when the content type is 'TXT' and is used for automated text moderation via AI detection providers. If rawText is supplied, then language is required.
content.language	String	No	Necessary if rawText is supplied
content.token	String	No	Used for livestreaming
content.status	String	No	Status of the content on client platform
content.customerSpecific	Object	No	Customer-specific key-value attributes that will be passed back in webhook responses upon receipt of moderation action being applied specifically for the content

Reporter

Parameter	Type	Required	Description
reporter.name	String	Yes	Name of the reporter
reporter.id	String	Yes	User ID of the reporter as it appears in your database. Fallback to the reporter emailAddress when id equals 0, Anonymous or unknown
reporter.phoneNumber	String	No	Reporter phone number
reporter.lang	String	No	Language the reporter's set to
reporter.emailAddress	String	Yes	User email of the reporter for communication purposes (statement of reasons sent by email, appeals, etc.)
reporter.customerSpecific	Object	No	Customer-specific key-value attributes that will be passed back in webhook responses upon receipt of moderation action being applied specifically for the reporter

Reportee

Parameter	Type	Required	Description
reportee.name	String	Yes	The name of the individual who is being reported
reportee.id	String	Yes	User ID of the reportee (content uploader) as it appears in your database. Fallback to the reportee emailAddress when id equals 0, Anonymous or unknown
reportee.lang	String	No	The language of the individual being reported
reportee.phoneNumber	String	No	Phone number of reportee
reportee.emailAddress	String	Yes	User email of the reportee for communication purposes (statement of reasons sent by email, appeals, etc.)
reportee.customerSpecific	Object	No	Reportee customer-specific attributes

Location

The location attribute is optional. If provided, it can contain any of the following location data points:

Parameter	Type	Required	Examples
location.postalCode	String	No	"PT12 ZPE"
location.city	String	No	"London"
location.region	String	No	"Middlesex"
location.countryCode	String (Use ISO codes, i.e. GB)	No	"GB","FR"
location.ipAddress	String	No	"192.168.2.1"
location.customerSpecific	Object	No	{"key" : "value"}

A note on customerSpecific

The global, content, reportee and reporter attributes all possess an optional field which accepts an object: customerSpecific.

Key-value pairs will always be accepted; however, to observe these customerSpecific attributes in the metadata on the moderation dashboard, you must configure these custom attributes in the "Configure > API & Integration > Custom Attributes" configuration page.

API response

The API returns a structured response to confirm successful processing or indicate validation errors.

Success response

A successful call to the single endpoint returns the following response:

{
    "message": "Success",
    "ok": true
}

Error response

If mandatory fields are missing or contain invalid data, the API will return a validation error detailing the specific failures:

{
    "statusCode": 400,
    "message": [
        "content.title must be a string",
        "content.title should not be empty"
    ],
    "error": "Bad Request"
}

Error handling

The following error may occur when submitting user reports:

Exception	Reason	Output Response	Status
BadRequestException	Missing mandatory fields in the request body	Object with missing fields will be provided	400

Key points

Array Format: Wrap all reports in an items array

Individual Structure: Each item must contain all required fields (content, reporter, reportee, etc.)

Validation: All items are validated before processing. If any item fails validation, the entire request may be rejected

Transaction: The bulk submission is processed as a single transaction