Connectors

List common fields

List the common dimensions and metrics, and which connectors fill each one.

GET /teams/{teamId}/connectors/common/fields

Returns the common fields: dimensions and metrics that work across connectors and have no connector prefix, such as date, campaign_name, clicks and reach. The shape is the same as list connector fields: dimensions and metrics, each an array of field groups. Each field also has supportedConnectors, the connectors that fill it.

Not every connector fills every common field. For example, reach is filled by fads and ttads, but not by gadw. If you query reach for a connector that does not fill it, run query refuses the query with a 400 error. Use this endpoint to check before you send the query.

Authentication: Bearer token · Permission:connectors:read · Rate limit: default (120 / 60s)

This endpoint needs no team permission. The key holder must be a member of the team.

Path parameters

teamId

string · uuid v7 required

The team making the request.

Query parameters

connectorIds

string[]

Optional, repeatable. Connector IDs to check, for example ?connectorIds=gadw&connectorIds=fads. A single ?connectorIds=fads also works. Up to 100 IDs. Send one parameter per connector: a comma-separated value such as fads,ttads is not a connector ID and returns 400 BAD_REQUEST. A value that is not a recognized connector also returns 400 BAD_REQUEST.

With connectorIds, supportedConnectors lists only the connectors you named, and a field that none of them fills is left out. Without connectorIds, the list covers every connector.

supportedConnectors is always a list. A field that has no per-connector mapping, such as data_source, applies to every listed connector.

Request

curl "https://api.twominutereports.com/v1/teams/0190f8b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f/connectors/common/fields?connectorIds=gadw&connectorIds=fads" \
  -H "Authorization: Bearer tmrc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

Here clicks is filled by both connectors, and reach only by fads.

{
  "success": true,
  "data": {
    "dimensions": [
      {
        "groupId": "time",
        "groupName": "Time",
        "fields": [
          { "id": "date", "queryId": "date", "name": "Date", "description": "The date of the event", "supportedConnectors": ["gadw", "fads"] }
        ]
      },
      {
        "groupId": "data_source",
        "groupName": "Connection",
        "fields": [
          { "id": "data_source", "queryId": "data_source", "name": "Connector", "description": "The type of the data source", "supportedConnectors": ["gadw", "fads"] }
        ]
      }
    ],
    "metrics": [
      {
        "groupId": "ad_performance_metrics",
        "groupName": "Ad performance metrics",
        "fields": [
          { "id": "clicks", "queryId": "clicks", "name": "Clicks", "description": "The number of clicks on your ads, including taps for Apple Ads", "supportedConnectors": ["gadw", "fads"] },
          { "id": "reach", "queryId": "reach", "name": "Reach", "description": "The number of people who saw your ads", "supportedConnectors": ["fads"] }
        ]
      }
    ]
  }
}

Returned when a connectorIds value is not a recognized connector ID. The message lists the allowed IDs, and the list is shortened in the real response.

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Validation error: Expected value to be one of \"appstore\", \"cfs\", \"fads\", \"ga\", \"gadw\", ... at \"connectorIds\""
  }
}

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid or expired session" }
}

Returned when the key holder is not a member of the team.

{
  "success": false,
  "error": { "code": "FORBIDDEN", "message": "Access denied" }
}

The common field object

string

The field ID.

queryId

string

The ID to send to run query. For a common field it is the same as id: no connector prefix.

name

string

The display label.

description

string

An optional field description.

supportedConnectors

string[]

The connector IDs that fill this field, from the connectors you asked about, or from all connectors when you sent no connectorIds.

Check before you query

List the connectors you plan to query in connectorIds.
Look up each common field you want to use. If it is missing from the response, none of those connectors fills it, and run query refuses it.
If supportedConnectors names only some of your connectors, the rows from the other connectors have no value for that field.
To use a field that a connector has under its own name, take it from list connector fields and send its queryId.

Disable account

Disable a connector account so it is no longer available for reporting.

Clients

Manage a team's clients (the brands or businesses you report on), their contacts, and the accounts assigned to each.