Destinations API reference

The Destinations API lets you create, manage, test, and delete outbound destinations. All endpoints use the same workspace API key authentication as the rest of the customer API on api.nimriz.com.

Destination read routes require connections:read. Create, update, delete, and test-send routes require connections:write.

Connector availability follows the public integrations catalog and plan access. A documented destination type may remain coming soon until the catalog marks it available. Pipedrive, Attio, Discord, and Snowflake are in beta and require a successful test of your own provider configuration before enablement.

Create a Destination

POST /api/integrations/destinations

Creates a new destination with one or more actions.

Request body

{
  "account_id": "workspace_uuid",
  "name": "Segment events",
  "type": "segment",
  "enabled": true,
  "credentials": {
    "write_key": "seg_..."
  },
  "actions": [
    {
      "name": "Send event",
      "action_type": "send_event",
      "enabled": true,
      "property_mapping": {
        "base": "default",
        "overrides": []
      },
      "event_filter": {
        "include": {
          "event_types": ["link.clicked", "link.qr_scanned"]
        },
        "exclude": {
          "bot_traffic": true
        },
        "conditions": []
      }
    }
  ]
}

List Destinations

GET /api/integrations/destinations?account_id=<WORKSPACE_UUID>

Returns configured destinations for the workspace given in the required account_id query parameter. Read responses include non-secret connector configuration in credentials plus configured_secret_keys, which lists the names of encrypted fields that are present. Raw secret values are never returned.

Get a Destination

GET /api/integrations/destinations/:id

Returns one destination and its actions. Stored provider credentials are omitted from the response. For example, an S3 response can include:

{
  "credentials": {
    "access_key_id": "AKIAEXAMPLE",
    "region": "us-east-1",
    "bucket": "analytics-events",
    "prefix": "nimriz"
  },
  "configured_secret_keys": ["secret_access_key"]
}

Update a Destination

PUT /api/integrations/destinations/:id

Updates destination settings and replaces the destination's action list with the submitted actions.

Credential updates are partial. Omitted secret fields keep their current encrypted values. Blank or null secret values are ignored and do not replace or clear the stored value. Send a non-empty value to replace a secret, or list an optional secret in clear_credential_keys to remove it explicitly:

{
  "credentials": {
    "project_token": "replacement-project-token"
  },
  "clear_credential_keys": ["api_secret"]
}

Only secret names supported by the destination type are accepted in clear_credential_keys. A tested connector's credential, configuration, mapping, or managed-authorization change disables the destination and requires another successful provider test before it can be enabled.

Delete a Destination

DELETE /api/integrations/destinations/:id

Deletes the destination and its actions.

Send a Test Event

POST /api/integrations/destinations/:id/test-send

Sends a real provider test for one action on the destination. Tested destinations remain disabled until the current credentials and configuration pass.

Request body for non-CRM destinations

{
  "action_id": "action_uuid"
}

If action_id is omitted, Nimriz uses the first enabled action on the destination.

HubSpot, Customer.io, Klaviyo, Salesforce, Pipedrive, and Attio test sends also require a transient sample customer identifier:

{
  "action_id": "action_uuid",
  "sample_external_id": "test-customer-123"
}

sample_external_id is used only to construct that provider test request. Nimriz never stores it on the destination, in the canonical integration event, or as an identity alias.

The test creates the connector's real provider-side artifact. Test deliveries do not consume live destination volume.

Managed Provider Authorization

Google Ads, LinkedIn, Google Sheets, HubSpot, Salesforce, Airtable, and Notion destinations use managed provider authorization for new dashboard setup. Create the destination with credentials.auth_mode set to managed_oauth, then finish authorization from the destination detail page.

Google Ads managed credentials include:

{
  "auth_mode": "managed_oauth",
  "customer_id": "1234567890",
  "conversion_id": "123456789",
  "conversion_label": "optional-label",
  "login_customer_id": "optional-manager-account-id"
}

LinkedIn managed credentials include:

{
  "auth_mode": "managed_oauth",
  "pixel_id": "urn:li:conversionRule:123",
  "account_urn": "urn:li:sponsoredAccount:456"
}

Existing manual-token Google Ads and LinkedIn destinations continue to run when their saved credentials include auth_mode: "manual_token" or legacy access-token fields. New dashboard setup does not ask for pasted provider access tokens.

Google Sheets setup depends on the current capability returned by the Worker. Complete the fields shown in the dashboard rather than assuming one credential shape across authorization modes. When picker_enabled is true, a per-file Google Sheets draft includes:

{
  "auth_mode": "managed_oauth",
  "sheet_name": "Events",
  "columns": [
    "event_id",
    "event_type",
    "timestamp",
    "short_url",
    "conversion_type",
    "conversion_value",
    "conversion_currency",
    "country",
    "utm_source",
    "utm_campaign"
  ]
}

In that mode, the dashboard offers Google Picker after managed authorization and sends the selected file ID to a dedicated server endpoint. Nimriz verifies the file with Google Drive and then stores these server-managed fields:

{
  "spreadsheet_id": "server-verified-file-id",
  "spreadsheet_title": "Campaign events",
  "selection_contract": "drive_file_picker_v1",
  "spreadsheet_selected_at": "2026-07-16T12:00:00.000Z"
}

In per-file mode, generic destination create and update requests cannot set or replace those four fields. Google Sheets authorization requests the drive.file scope. Selecting a different Sheet, reconnecting Google, or changing the tab or columns disables the destination and requires another successful provider test.

Existing configured connections created under the earlier authorization contract continue using their saved spreadsheet until reconnect or revoke. Read the capabilities endpoint before presenting per-file selection.

HubSpot managed credentials include:

{
  "auth_mode": "managed_oauth",
  "custom_event_name": "pe1234567_nimriz_conversion",
  "custom_matching_id_property": "customer_external_id"
}

HubSpot is managed-OAuth only. The destination does not accept manual or private-app access tokens.

Salesforce is managed-OAuth only. Set login_environment to production, sandbox, or my_domain; My Domain setup also requires my_domain_host.

Airtable managed credentials include:

{
  "auth_mode": "managed_oauth",
  "base_id": "app123",
  "table_id": "tbl123",
  "delivery_id_field": "Nimriz Delivery ID"
}

Notion managed credentials include:

{
  "auth_mode": "managed_oauth",
  "data_source_id": "data-source-id",
  "title_property": "Name",
  "delivery_id_property": "Nimriz Delivery ID"
}

Airtable and Notion are managed-OAuth only. Nimriz does not ask customers for Airtable personal access tokens or Notion internal integration tokens.

Additional destination types

CRM and lifecycle destinations accept only conversions with a customer-supplied user_data.external_id. That value is resolved only for the provider request and is not part of the canonical integration event. A missing value produces the safe suppression code missing_external_id and does not consume live destination volume.

The dashboard uses these session-protected routes to manage provider grants:

When Picker is enabled, Picker-token responses include only the short-lived access token, its expiry, the restricted Picker developer key, the Google Cloud project number, and the selection contract. Refresh tokens are never returned to the browser.

Action types

Mapping actions

Each action can use these mapping override types:

• rename
• exclude
• include
• static
• template

Filters

Each action can filter on:

• include.event_types
• include.touch_types
• include.domain_ids
• include.tag_ids
• include.space_ids
• include.countries
• exclude.event_types
• exclude.touch_types
• exclude.domain_ids
• exclude.tag_ids
• exclude.space_ids
• exclude.countries
• exclude.bot_traffic
• conditions[]