importFilters.add

Add resources to the current allowlist or denylist for an SCM or Jira connection.

Facts


Method	`POST https://yourinstance.getdx.net/api/connections/` `:connection_id/importFilters.add`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`connection_id`	`Integer`	The connection ID. Substitute this value for `:connection_id` in the URL path. Example: `123`
`identifier_type`	`String`	The identifier used by every value in `resources`: `dx_id`, `source_id`, or `name`.
`resources`	`Array<String or Integer>`	One to 1000 resource identifiers. The array must be flat, and all values must use `identifier_type`.

Optional arguments

Name	Type	Description
`force`	`Boolean`	Defaults to `false`. When `true`, apply resources that resolve successfully even if other identifiers are unmatched or ambiguous.

Usage info

The current mode determines the effect:

In allowlist mode, adding a resource enables its import. Previously excluded resources are backfilled asynchronously.
In denylist mode, adding a resource disables its import and purges its imported data.

This method cannot be used in allow_all mode because no filter list is configured. Call importFilters.setMode first.

Use one identifier type per request:

dx_id: the integer DX ID returned by importFilters.list.
source_id: the identifier assigned by the source system.
name: the canonical qualified name, such as organization/repository for an SCM repository or a project key for Jira.

By default, the request fails without making changes if any identifier is unmatched or ambiguous. Set force to true to apply resolved resources and receive status: "partial_success". If no identifier resolves, the request fails even when force is true.

The response separates resolved resources into applied and unchanged. Each item includes the submitted identifier, dx_id, source_id, canonical name, and resulting import_enabled state. Unmatched identifiers include a reason. Ambiguous identifiers include candidate resource objects.

destructive is true when the operation purges data. Destructive responses also include purged_count.

Example request

curl -X POST "https://yourinstance.getdx.net/api/connections/123/importFilters.add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  --data '{
    "identifier_type": "source_id",
    "resources": ["869749458", "1058869669"]
  }'

Success response

This example shows resources added to a denylist:

{
  "ok": true,
  "status": "success",
  "mode": "denylist",
  "operation": "add",
  "identifier_type": "source_id",
  "destructive": true,
  "applied": [
    {
      "identifier": "869749458",
      "dx_id": 101,
      "source_id": "869749458",
      "name": "acme/api",
      "import_enabled": false
    }
  ],
  "applied_count": 1,
  "unchanged": [
    {
      "identifier": "1058869669",
      "dx_id": 102,
      "source_id": "1058869669",
      "name": "acme/web",
      "import_enabled": false
    }
  ],
  "unchanged_count": 1,
  "unmatched": [],
  "ambiguous": [],
  "purged_count": 1
}

Errors

Error	Description
`not_authed`	The request did not include a valid API key.
`connection_not_found`	No connection exists for the given `connection_id`.
`unsupported_connection_type`	The connection does not support selective import filters.
`resources_required`	`resources` is missing or empty.
`invalid_resources`	`resources` is not a flat array of non-blank strings or numbers.
`too_many_resources`	More than 1000 identifiers were provided.
`invalid_identifier_type`	`identifier_type` is not `dx_id`, `source_id`, or `name`.
`filter_mode_not_configured`	The connection is in `allow_all` mode.
`no_resources_resolved`	None of the supplied identifiers resolved to a resource.
`unresolved_resources`	At least one identifier was unmatched or ambiguous and `force` was not `true`. No changes were made.
`import_filter_configuration_in_progress`	Another selective import configuration request holds the connection lock. This response uses HTTP status 409.