---
title: "Submit detected IOCs to the Collective Insights"
method: POST
path: "/detections"
tags: ["Detections"]
---

# Submit detected IOCs to the Collective Insights

`POST /detections`

## Request

- Base URL: `https://api.recordedfuture.com/collective-insights`
- URL: `https://api.recordedfuture.com/collective-insights/detections`
- Auth: one of:
  - API key in header `X-RFToken`
  - OAuth 2
    - Authorization code: `https://id.recordedfuture.com/authorize`
    - Token URL: `https://id.recordedfuture.com/token`

This operation sends a list of indicators of compromise (IOC) detections to Collective Insights.
Submissions are associated with the API key's enterprise and are used to provide enhanced intelligence
and analytics specific to your enterprise.

For each submitted detection the `ioc` data and a `detection.type` must be set. All other values are optional.

Note that __all submissions of test data__ (for example during development) __must__ use the `options.debug` property set to `true`.

## Request body

- SubmitDetectionsRequest
  - `data` object[], required: A list of detections that has been made and that should be added to Collective Insights.
    - `detection` object, required: Required information about the detection method.
      - `id` string: In the type=correlation case, this will be the id of the Correlation Use Case. Ex: p_default_ip_risklist. The p_ prefix indicates that it is a public use case available to all, a h_ prefix indicates that it is client specific use case. In the case of type=detection_rule, it will be the id of the Analyst note where the Detection rule was attached, for example doc:XYZ. In the case of a type=playbook, this field is the id of a playbook. This id is required in the case of type=detection_rule but optional in all other cases.
      - `name` string: The detection name.
      - `sub_type` 'sigma' | 'yara' | 'snort': The detection method sub type. Must be a value in the enumerated list if detection type is set to `detection_rule`. In all other cases it must be null.
      - `type` 'detection_rule' | 'correlation' | 'playbook' | 'sandbox', required: The detection method used by the security tool. More detection types may be added in the future.
    - `incident` object: Optional free-form incident data related to the detection. Can be used to group several detected IoCs into a shared context.
      - `id` string
      - `name` string
      - `type` string
    - `ioc` object, required: The IoC (indicator of compromise) associated with the event.
      - `action_category` 'detect' | 'prevent': Classification of the action taken by the security tool in response to the event activity. Allowed values are `detect` and `prevent`. If omitted, this field will be set to `detect` in the backend.
      - `field` string: The field in a log where the detection was made.
      - `source_type` string: The type of log source from which the detection was made.
      - `type` 'ip' | 'domain' | 'hash' | 'url' | 'vulnerability', required
      - `value` string, required
    - `malwares` string[]: Optional list of malware names related to the detection.
    - `mitre_codes` string[]: Optional list of MITRE ATT&CK codes related to the detection.
    - `timestamp` string, date-time: Timestamp of the detection in ISO 8601 format. If omitted, the time of the API request will be recorded instead.
    - `transient_id` string: ID that will not be saved, but used to identify any dropped data in the response
  - `options` object
    - `debug` boolean: If true, indicates that the request is for testing purposes and the data will not be used for analytical purposes. Input validation is always active.
    - `summary` boolean: If true, the response will include a summary of the submitted IOCs.
  - `organization_ids` string[]: A list of organizations to associate the submission with. The user making the request must be a member of every organization provided

## Response `200`

OK

- SubmitDetectionsResponse
  - `result` object, required
    - `debug` boolean, required
    - `object_ids` string[]: IDs of the created detections.
    - `status` string, required
    - `summary` object
      - `dropped` DroppedSummary[]
        - `index` integer, required
        - `ioc_value` string: IOC value received as input, but was dropped. Reason for dropping is in "message".
        - `message` string, required
        - `reason` 'INVALID_IOC' | 'STORAGE_AT_CAPACITY', required: Enums may be extended to include more reasons
        - `transient_id` string: If provided in the input, it will be used in the response to identify which entry was dropped
      - `processed` object, required
        - `domain` number, required
        - `hash` number, required
        - `ip` number, required
        - `url` number, required
        - `vulnerability` number, required

## Other responses

- `400`: Client error
- `401`: Client error
- `403`: Client error
- `429`: This may happen on too many concurrent requests, too many requests within a timespan or requests resulting in high resource consumption. Other undisclosed limits may result in this status code as well.
- `500`: Server error
- `502`: Server error
- `503`: Server error
- `504`: Server error

---

[API](https://skmtc.dev/recordedfuture/apis/collective-insights-api.md) - [All operations](https://skmtc.dev/recordedfuture/apis/collective-insights-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recordedfuture/apis/collective-insights-api/revisions/260c9863a7cf?raw)