Connectors

Connectors

The Connectors API allows configuration of authentication mechanisms for connectors, including API keys, OAuth web flow etc. The account_id query parameter is mandatory for the connectors APIs as the connectors can only be managed in sub-accounts and not in the organization account.

Get Connector

This API can be used to fetch information about an individual connector. 

GET /es/v2/connectors/<connector_id>

Query parameters

&accountId=<sub_account_id> // Required for managing connectors in sub-accounts

Response:

{
  "statusCode": 0,
  "statusMessage": "string",
  "response": {
    "dataType": "string",
    "dataTypeCategory": "string",
    "docUrl": "string",
    "platformId": "string",
    "connectorId": "string",
    "integrated": true,
    "logo": "string",
    "name": "string",
    "overviewUrl": "string",
    "platformType": "string",
    "status": 0,
    "supportedType": "string"
  }}

Attributes:

Attribute	Description	Possible Values
dataType	Data type of the connector	Custom Audiences, identity management, reporting, data store, Campaign, customer match, offline conversions, analytics, campaign posting, Audiences - Data API, audiences, custom file audiences, geo events, events, ads management, raw real-time conversion events, Conversions, audience DMP segments, Insights, transcoding, click conversions, ads analytics, ID match, raw offline conversion events, raw events data stream, Audiences - CRM API
dataTypeCategory	Data type category of the connector	audience activation, identity management, reporting, data store, campaign management, events
docUrl	Url for document if any	URL (e.g., https://example.com/doc)
platformId	Platform identifier of connector	UUID (16-character identifier)
connectorId	Unique identifier for the connector	UUID (16-character identifier)
logo	Logo of the connector	URL (e.g., https://example.com/logo.png)
name	Name of the connector	String (e.g., connector name)
overviewUrl	Overview page Url for connector if any	URL (e.g., https://example.com/overview)
platformType	Platform type of the connector	Social Media Platform, CRM Platform, Demand-Side Platform (DSP), Cloud Storage Provider, Media Management System, Identity Management, Supply-Side Platform (SSP), Customer Data Platform (CDP), E-Commerce Platform, Data Provider
supportedType	Type of connector supported at	Source, Destination

Sample Curl::

curl --location '<host>/es/v2/connectors/STzkunJCh3EvKZi0?accountId=a3ba4fbd9d51df11' \
--header 'Authorization: Bearer c076dc2e-d0c2-4d4d-ab13-e4e3dd555fc0'

List Connectors

This API can be used to get a list of available connectors.

GET /es/v2/connectors/all

Query parameters

&accountId=<sub_account_id> // Required for managing connectors in sub-accounts
&q=keyword
&size=10
&offset=0

Response:

{
  "statusCode": 0,
  "statusMessage": "string",
  "response": [
    {
      "dataType": "string",
      "dataTypeCategory": "string",
      "docUrl": "string",
      "platformId": "string",
      "connectorId": "string",
      "integrated": true,
      "logo": "string",
      "name": "string",
      "overviewUrl": "string",
      "platformType": "string",
      "status": 0,
      "supportedType": "string"
    }
  ]
}

Attributes:

Attribute	Description	Possible Values
connectorId	Unique identifier for the connector	UUID (16-character identifier)
dataType	Data type of the connector	Custom Audiences, identity management, reporting, data store, Campaign, customer match, offline conversions, analytics, campaign posting, Audiences - Data API, audiences, custom file audiences, geo events, events, ads management, raw real-time conversion events, Conversions, audience DMP segments, Insights, transcoding, click conversions, ads analytics, ID match, raw offline conversion events, raw events data stream, Audiences - CRM API
dataTypeCategory	Data type category of the connector	audience activation, identity management, reporting, data store, campaign management, events
docUrl	Url for document if any	URL (e.g., https://example.com/doc)
platformId	Platform identifier of connector	UUID (16-character identifier)
logo	Logo of the connector	URL (e.g., https://example.com/logo.png)
name	Name of the connector	String (e.g., connector name)
overviewUrl	Overview page Url for connector if any	URL (e.g., https://example.com/overview)
platformType	Platform type of the connector	Social Media Platform, CRM Platform, Demand-Side Platform (DSP), Cloud Storage Provider, Media Management System, Identity Management, Supply-Side Platform (SSP), Customer Data Platform (CDP), E-Commerce Platform, Data Provider
supportedType	Type of connector supported at	Source, Destination
transfer	Indicates whether initiating transfer is applicable or not	true or false

Sample Curl::

curl --location '<host>/es/v2/connectors/all?accountId=a3ba4fbd9d51df11&q=&size=2&offset=0' \
--header 'Authorization: Bearer c076dc2e-d0c2-4d4d-ab13-e4e3dd555fc0'

Add Connector

This API can be used to add a connector from the list of available connectors to a sub-account. Then connector has to be added first to a sub-account before it can be configured and be used in any connection.

POST /es/v2/connectors

Query parameters

&accountId=<sub_account_id> // Required for managing connectors in sub-accounts

Request Body:

{
  "connectorIds": []
}

Response:

{
  "statusCode": 0,
  "statusMessage": "string",
  "response": {}
}

Attributes:

Attribute	Description	Possible Values
connectorIds	List of connector IDs to be added	List of string IDs, e.g., ["id1", "id2", "id3"]

Sample Curl::

curl --location '<host>/es/v2/connectors?accountId=a3ba4fbd9d51df40' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer c076dc2e-d0c2-4d4d-ab13-e4e3dd555fc0' \
--data '{
  "connectorIds": ["STWkG5hhS3EvG5D0"]
}'

List Added Connectors

This API can be used to get a list of added connectors in a sub-account.

GET /es/v2/connectors

Query parameters

&accountId=<sub_account_id> // Required for managing connectors in sub-accounts
&q=keyword
&size=10
&offset=0

Response:

{
  "statusCode": 0,
  "statusMessage": "string",
  "response": [
      {
        "configured": true,
        "connectorId": "string",
        "dataType": "string",
        "dataTypeCategory": "string",
        "description": "string",
        "destConnections": 0,
        "editable": true,
        "env": "string",
        "platformId": "string",
        "logo": "string",
        "name": "string",
        "platformType": "string",
        "srcConnections": 0,
        "supportedType": "string",
        "transfer": true
      }
    ]
}

Attributes:

Attribute	Description	Possible Values
configured	Indicates whether connector is configured or not	true or false
connectorId	Unique identifier for the connector	UUID (16-character identifier)
dataType	Data type of the connector	Custom Audiences, identity management, reporting, data store, Campaign, customer match, offline conversions, analytics, campaign posting, Audiences - Data API, audiences, custom file audiences, geo events, events, ads management, raw real-time conversion events, Conversions, audience DMP segments, Insights, transcoding, click conversions, ads analytics, ID match, raw offline conversion events, raw events data stream, Audiences - CRM API
dataTypeCategory	Data type category of the connector	audience activation, identity management, reporting, data store, campaign management, events
description	Description about connector	String (e.g., connector description)
destConnections	No of connections used this connector in destination	Integer (e.g., 0, 1, 2, etc.)
editable	Indicates whether connector is editable or not	true or false
env	Name of the environment from where connector added from	String (e.g., environment name)
platformId	Platform identifier of connector	UUID (16-character identifier)
logo	Logo of the connector	URL (e.g., https://example.com/logo.png)
name	Name of the connector	String (e.g., connector name)
platformType	Platform type of the connector	Social Media Platform, CRM Platform, Demand-Side Platform (DSP), Cloud Storage Provider, Media Management System, Identity Management, Supply-Side Platform (SSP), Customer Data Platform (CDP), E-Commerce Platform, Data Provider
srcConnections	No of connections used this connector in source	Integer (e.g., 0, 1, 2, etc.)
supportedType	Type of connector supported at	Source, Destination
transfer	Indicates whether initiating transfer is applicable or not	true or false

Sample Curl::

curl --location '<host>/es/v2/connectors?accountId=a3ba4fbd9d51d11c&q=&size=10&offset=0' \
--header 'Authorization: Bearer c076dc2e-d0c2-4d4d-ab13-e4e3dd555fc0'

List Supported Connectors

This API can be used to get a list of supported connectors for a given source or destination connector. If a source connector is provided, then this API returns a list of supported destination connectors and vice-versa.

GET /es/v2/connectors/supported/<connector_id>/<type> 
// type: source or destination

Query parameters

&accountId=<sub_account_id> // Required for managing connectors in sub-accounts

Response:

{
  "statusCode": 0,
  "statusMessage": "string",
  "response": [
    {
      "configured": true,
      "connectorId": "string",
      "dataType": "string",
      "dataTypeCategory": "string",
      "description": "string",
      "destConnections": 0,
      "platformId": "string",
      "logo": "string",
      "name": "string",
      "platformType": "string",
      "srcConnections": 0,
      "supportedType": "string",
      "transfer": true
    }
  ]
}

Attributes:

Attribute	Description	Possible Values
configured	Indicates whether connector is configured or not	true or false
connectorId	Unique identifier for the connector	UUID (16-character identifier)
dataType	Data type of the connector	Custom Audiences, identity management, reporting, data store, Campaign, customer match, offline conversions, analytics, campaign posting, Audiences - Data API, audiences, custom file audiences, geo events, events, ads management, raw real-time conversion events, Conversions, audience DMP segments, Insights, transcoding, click conversions, ads analytics, ID match, raw offline conversion events, raw events data stream, Audiences - CRM API
dataTypeCategory	Data type category of the connector	audience activation, identity management, reporting, data store, campaign management, events
description	Description about connector	String (e.g., connector description)
destConnections	No of connections used this connector in destination	Integer (e.g., 0, 1, 2, etc.)
platformId	Platform identifier of connector	UUID (16-character identifier)
logo	Logo of the connector	URL (e.g., https://example.com/logo.png)
name	Name of the connector	String (e.g., connector name)
platformType	Platform type of the connector	Social Media Platform, CRM Platform, Demand-Side Platform (DSP), Cloud Storage Provider, Media Management System, Identity Management, Supply-Side Platform (SSP), Customer Data Platform (CDP), E-Commerce Platform, Data Provider
srcConnections	No of connections used this connector in source	Integer (e.g., 0, 1, 2, etc.)
supportedType	Type of connector supported at	Source, Destination
transfer	Indicates whether initiating transfer is applicable or not	true or false

Sample Curl::

curl --location '<host>/es/v2/connectors/supported/STzkunJCh3EvKZi0/DESTINATION?accountId=a3ba4fbd9d51df11' \
--header 'Authorization: Bearer c076dc2e-d0c2-4d4d-ab13-e4e3dd555fc0'

Get Connector Configuration

This API can be used to fetch connector configuration which includes both connector secret configuration and connection level configuration.

GET /es/v2/connectors/configuration/<connector_id>

Query parameters

&accountId=<sub_account_id> // Required for managing connectors in sub-accounts

Response:

{
  "statusCode": 0,
  "statusMessage": "string",
  "response": {
    "secretConfig": {
        "configured": false,
        "lastUpdated": 0,
        "secretName": "string",
        "configuration": [
          {
            "max": 0,
            "description": "string",
            "label": "string",
            "type": "string",
            "required": false,
            "min": 0,
            "readonly": false,
            "name": "string",
            "limit": 0,
            "id": "string",
            "value": ""
          }
        ],
    },
    "env": "string",
    "editable": false,
    "connectionConfig" : [
          {
            "max": 0,
            "description": "string",
            "label": "string",
            "type": "string",
            "required": false,
            "min": 0,
            "readonly": false,
            "name": "string",
            "limit": 0,
            "id": "string",
            "value": ""
          }
    ]
  }
}

Attributes:

Attribute	Description	Possible Values
secretConfig	List for configurations fields with meta data	List of configuration, e.g., [{configuration1}, {configuration2}, {configuration3}] Note: Currently, only one configuration i.e configuration1 can be fetched and saved.
connectionConfig	List for connection configurations fields with meta data	List of configuration, e.g., [{connectionConfig1}, {connectionConfig2}, {connectionConfig3}]
editable	Indicates whether connector is editable or not	true or false
env	Name of the environment from where connector added from	String (e.g., environment name)
configured	Indicates whether connector is configured or not	true or false
lastUpdated	Last updated time for configuration	Unix timestamp (seconds)
secretName	Secret key name for secret manager	String (e.g., Secret Key)
configuration	List for configuration fields with meta data	List of configuration, e.g., [{sub-configuration1}, {sub-configuration2}, {sub-configuration3}].
max	Maximum number value for accepted field in case for type=”number”	Integer (e.g., 1, 2, etc.)
description	Description about configuration if any	String (e.g., configuration description)
label	Label for configurations	String (e.g., configuration label)
type	Type of the configuration field	Text, Number,Date, Select,Multi-Select etc
required	Indicates whether field is required or not	true or false
min	Minimum number value for accepted field in case for type=”number”	Integer (e.g., 1, 2, etc.)
readonly	Indicates whether field is read only or not	true or false
value	Value of configuration field if any	String (e.g., configuration field value)

Sample Curl::

curl --location '<host>/es/v2/connectors/configuration/STzkunJCh3EvKZi0?accountId=a3ba4fbd9d51df11' \
--header 'Authorization: Bearer c076dc2e-d0c2-4d4d-ab13-e4e3dd555fc0'

Configure Connector

The API allows configuration of secrets for a source or destination connector.

POST /es/v2/connectors/configure/<connector_id>

Query parameters

&accountId=<sub_account_id> // Required for managing connectors in sub-accounts

Request Body:

{
  "secretConfig": {
    "key1": "value1",
    "key2": "value2"
  }
}

Response:

{
  "statusCode": 0,
  "statusMessage": "string",
  "response": {
    "configurationId": "string",
    "secretName": "string"
  }
}

Attributes:

Attribute	Description	Possible Values
name	Name of the configuration field	String (e.g., configuration name)
secretConfig	List for configurations fields with id and value pair	List of configurations, e.g., {"key1": "value1", …}
configurationId	Unique identifier for the configuration	UUID (16-character identifier)
secretName	Secret key name for secret manager	String (e.g., Secret Key)

Sample Curl::

curl --location '<host>/es/v2/connectors/configure/STzkunJCh3EvKZi0?accountId=a3ba4fbd9d51df11' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer c076dc2e-d0c2-4d4d-ab13-e4e3dd555fc0' \
--data '{
    "name": "Sample Configuration",
    "configurations": {
        "clientId": "12345678",
        "clientSecret": "Asrc37Fhs5tyfhgfgfcydd65tFGDTrd"
    }
}'

Remove Connector

This API allows deletion of a connector from a sub-account. A connector can only be deleted when it is not being used in any connection.

DELETE /es/v2/connectors/<connector_id>

Query parameters

&accountId=<sub_account_id> // Required for managing connectors in sub-accounts

Request Body:

NA

Response:

{
  "statusCode": 0,
  "statusMessage": "string",
  "response": {}
}

Sample Curl::

curl --location --request DELETE '<host>/es/v2/connectors/STzkunJCh3EvKZi0?accountId=a3ba4fbd9d51df11' \
--header 'Authorization: Bearer c076dc2e-d0c2-4d4d-ab13-e4e3dd555fc0'