Activations

Activations are encapsulations that represent the configuration for sending an audience output to a destination.

Note: The Activations API is currently not Publicly Available.

Add Activation to Audience

Defines how audience data is sent to a Destination. This step enables the data sync. You must establish a connection (Add Destination to Audience) for this audience before an Activation can be created.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Activation Created event in the audit trail.

The rate limit for this endpoint is 50 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS
connectionId required	string [ 1 .. 255 ] Example: ii_123456789

Request Body schema: application/vnd.segment.v1alpha+json
required

enabled	boolean (enabled) Determines whether an activation is enabled.
performResync required	boolean (performResync) Determines whether to perform a full resync upon creation. If true, the entire audience is resent to the Destination from scratch. If false, only future changes will be synced.
activationType required	string (activationType) Determines when an event is sent to the Destination. Possible values: Audience Entered: Sends an event when a profile or entity enters the audience. Audience Exited: Sends an event when a profile or entity exits the audience. Audience Membership Changed: Sends an event for both entries and exits. This does not apply to entities. Note that events are sent for the profile, unless the audience is a Linked Audience. In that case, events are sent for the target entity defined for that audience.
activationName required	string (activationName) Name of the activation.
required	object (personalization) The data points used to enrich the event. Defines which profile traits and/or entity properties are included in the event sent to the Destination. For Action Destinations, any traits or properties specified here must also be included in the destinationMapping to define which Destination fields should be populated.
	object (destinationMapping) Defines the specific action and data mapping for the Destination. Only applicable for Action Destinations. Action id: Specifies which action to perform on the Destination (for example: add contact, update list). Settings/Mapping: Defines how event data (including personalization traits) populates specific fields in the Destination. Use the List Supported Destinations from Audience endpoint to find available action ids and the specific Destination fields you can map.

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/spaces/{spaceId}/audiences/{audienceId}/destination-connections/{connectionId}/activations

Request samples

application/vnd.segment.v1alpha+json

{"activationType": "Audience Entered",
"activationName": "Test Activation",
"enabled": true,
"performResync": true,
"personalization": {"profile": {"properties": ["mountain_bikers_2023",
"game_boy_color_owners"
],
"mapping": {"mountain_bikers_2023": "bikers_segment",
"game_boy_color_owners": "retro_gamers"
}
},
"entities": [{"properties": ["ID",
"LAST_ACTIVITY_TIME",
"BALANCE"
],
"relationshipSlug": "owned-accounts-copy"
}
]
},
"destinationMapping": {"actionId": "action_123",
"settings": {"webhookUrl": "https://example.com/webhook",
"method": "POST"
}
}
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"activation": {"id": "act_987654321",
"enabled": true,
"workspaceId": "w_123",
"spaceId": "spa_9aQ1Lj62S4bomZKLF4DPqW",
"audienceId": "aud_0ujsszwN8NRY24YaXiTIE2VWDTS",
"connectionId": "ii_123456789",
"activationType": "Audience Entered",
"activationName": "Test Activation",
"personalization": {"profile": {"properties": [ ]
}
},
"destinationMapping": {"actionId": "action_123"
},
"performResync": true
}
}
}

Add Destination to Audience

Establishes a connection between an audience and a Destination. To start syncing data, you must create an Activation for the connection created here.

Note that the Destination must be added to Engage through the Engage Settings page within the App before creating the connection through the API.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Destination Added into Audience event in the audit trail.

The rate limit for this endpoint is 50 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS

Request Body schema: application/vnd.segment.v1alpha+json
required

required	object (destination) The Destination.
	Array of objects (idSyncConfiguration) Identifier sync configuration. Defines which external ids to sync and their selection strategies. Maximum 5 items allowed. If omitted, the default will be last email and last user_id, or all email and all user_id depending on the Destination.
connectionSettings	any (connectionSettings) The settings that a Destination requires to create audiences on a third-party platform. These settings are Destination-specific. Use the List Supported Destinations from Audience endpoint to find the required connection settings.

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/spaces/{spaceId}/audiences/{audienceId}/destination-connections

Request samples

application/vnd.segment.v1alpha+json

{"destination": {"id": "684758860892086596310ac",
"type": "destination"
}
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"connection": {"id": "ii_123456789"
},
"idSyncConfiguration": [ ]
}
}

List Destinations from Audience

Lists all Destinations from an Audience.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Destinations Listed from Audience event in the audit trail.

The rate limit for this endpoint is 50 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS

query Parameters

object (PaginationInput)

Optional pagination.

This parameter exists in alpha.

Example: pagination=pagination.count=2

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/spaces/{spaceId}/audiences/{audienceId}/destination-connections

Request samples

TypeScript
Java
Python
Go
curl

import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.activations.listDestinationsFromAudience('spa_9aQ1Lj62S4bomZKLF4DPqW', 'aud_0ujsszwN8NRY24YaXiTIE2VWDTS'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"connections": [{"id": "ii_123456789",
"name": "Test Connection 1",
"enabled": true,
"updatedAt": "2023-01-02T00:00:00Z",
"settings": { },
"destinationId": "684758860892086596310ac_1",
"metadata": {"id": "1234567890abcdef1234567",
"name": "Test Destination",
"slug": "test-destination"
},
"idSyncConfiguration": [{"externalId": "email",
"strategy": "first"
},
{"externalId": "phone",
"strategy": "all"
}
],
"sourceId": "proj_123",
"createdAt": "2023-01-01T00:00:00Z"
},
{"id": "ii_another456",
"name": "Test Connection 2",
"enabled": false,
"updatedAt": "2023-01-04T00:00:00Z",
"settings": { },
"destinationId": "684758860892086596310ac_2",
"metadata": {"id": "684758860892086596310ad",
"name": "Another Destination",
"slug": "another-destination"
},
"sourceId": "proj_123",
"createdAt": "2023-01-03T00:00:00Z"
}
],
"pagination": {"next": null,
"current": "first_page"
}
}
}

Get Activation from Audience

Gets a single Activation by id.

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS
id required	string [ 1 .. 255 ] Example: act_987654321

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/spaces/{spaceId}/audiences/{audienceId}/activations/{id}

Request samples

TypeScript
Java
Python
Go
curl

import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(
    api.activations.getActivationFromAudience('spa_9aQ1Lj62S4bomZKLF4DPqW', 'aud_0ujsszwN8NRY24YaXiTIE2VWDTS', 'act_987654321')
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"activation": {"id": "act_987654321",
"enabled": true,
"workspaceId": "w_123",
"spaceId": "spa_9aQ1Lj62S4bomZKLF4DPqW",
"audienceId": "aud_0ujsszwN8NRY24YaXiTIE2VWDTS",
"connectionId": "ii_123456789",
"activationType": "Audience Entered",
"activationName": "Test Activation",
"personalization": {"profile": {"properties": [ ]
}
},
"destinationMapping": {"actionId": "action_123"
},
"performResync": true
}
}
}

Remove Activation from Audience

Deletes an Activation.

The rate limit for this endpoint is 50 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS
id required	string [ 1 .. 255 ] Example: act_987654321

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/spaces/{spaceId}/audiences/{audienceId}/activations/{id}

Request samples

TypeScript
Java
Python
Go
curl

import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(
    api.activations.removeActivationFromAudience('spa_9aQ1Lj62S4bomZKLF4DPqW', 'aud_0ujsszwN8NRY24YaXiTIE2VWDTS', 'act_987654321')
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"status": "SUCCESS"
}
}

Update Activation for Audience

Updates an Activation.

The rate limit for this endpoint is 50 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS
id required	string [ 1 .. 255 ] Example: act_987654321

Request Body schema: application/vnd.segment.v1alpha+json
required

enabled	boolean (enabled) Determines whether an activation is enabled.
activationName	string (activationName) Activation name.
	object (personalization) The data points used to enrich the event. Defines which profile traits and/or entity properties are included in the event sent to the Destination. For Action Destinations, any traits or properties specified here must also be included in the destinationMapping to define which Destination fields should be populated.
	object (destinationMapping) Defines the specific action and data mapping for the Destination. Only applicable for Action Destinations. Action id: Specifies which action to perform on the Destination (for example: add contact, update list). Settings/Mapping: Defines how event data (including personalization traits) populates specific fields in the Destination. Use the List Supported Destinations from Audience endpoint to find available action ids and the specific Destination fields you can map.
performResync	boolean (performResync) Determines whether to perform a full resync after the update. If true, the entire audience is resent to the Destination using the updated configuration. If false, the update applies only to future syncs.

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/spaces/{spaceId}/audiences/{audienceId}/activations/{id}

Request samples

application/vnd.segment.v1alpha+json

{"activationName": "Updated Test Activation",
"enabled": false,
"performResync": false,
"personalization": {"profile": {"properties": ["updated_mountain_bikers_2023",
"updated_game_boy_color_owners"
],
"mapping": {"updated_mountain_bikers_2023": "updated_bikers",
"updated_game_boy_color_owners": "updated_gamers"
}
},
"entities": [{"properties": ["ID",
"UPDATED_BALANCE"
],
"relationshipSlug": "owned-accounts-updated"
}
]
},
"destinationMapping": {"actionId": "action_456",
"settings": {"webhookUrl": "https://example.com/updated-webhook",
"method": "PUT"
}
}
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"activation": {"id": "act_987654321",
"enabled": false,
"workspaceId": "w_123",
"spaceId": "spa_9aQ1Lj62S4bomZKLF4DPqW",
"audienceId": "aud_0ujsszwN8NRY24YaXiTIE2VWDTS",
"connectionId": "ii_123456789",
"activationType": "Audience Entered",
"activationName": "Updated Test Activation",
"personalization": {"profile": {"properties": [ ]
}
},
"destinationMapping": {"actionId": "action_123"
},
"performResync": false
}
}
}

List Activations from Audience

Lists all Activations.

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS

query Parameters

object (PaginationInput)

Optional pagination.

This parameter exists in alpha.

Example: pagination=pagination.count=10

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/spaces/{spaceId}/audiences/{audienceId}/activations

Request samples

TypeScript
Java
Python
Go
curl

import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.activations.listActivationsFromAudience('spa_9aQ1Lj62S4bomZKLF4DPqW', 'aud_0ujsszwN8NRY24YaXiTIE2VWDTS'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"activations": [{"id": "act_987654321",
"enabled": true,
"workspaceId": "w_123",
"spaceId": "spa_9aQ1Lj62S4bomZKLF4DPqW",
"audienceId": "aud_0ujsszwN8NRY24YaXiTIE2VWDTS",
"connectionId": "ii_123456789",
"activationType": "Audience Entered",
"activationName": "Test Activation 1",
"personalization": {"profile": {"properties": [ ]
}
},
"destinationMapping": {"actionId": "action_1"
},
"performResync": true
},
{"id": "act_another123",
"enabled": false,
"workspaceId": "w_123",
"spaceId": "spa_9aQ1Lj62S4bomZKLF4DPqW",
"audienceId": "aud_0ujsszwN8NRY24YaXiTIE2VWDTS",
"connectionId": "ii_another123",
"activationType": "Audience Exited",
"activationName": "Test Activation 2",
"personalization": {"profile": {"properties": [ ]
}
},
"destinationMapping": {"actionId": "action_2"
},
"performResync": false
}
]
}
}

List Supported Destinations from Audience

Lists all Supported Destinations for this audience type that can be activated.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Supported Destinations Listed For Audience event in the audit trail.

The rate limit for this endpoint is 60 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceType required	string [ 1 .. 255 ] Example: USERS

query Parameters

slug	string (slug) Optional destination slug to filter results. This parameter exists in alpha.
actionId	string (actionId) Optional destination action id to filter results. This parameter exists in alpha.

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/spaces/{spaceId}/audienceType/{audienceType}/supported-destinations

Request samples

TypeScript
Java
Python
Go
curl

import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.activations.listSupportedDestinationsFromAudience('spa_9aQ1Lj62S4bomZKLF4DPqW', 'USERS'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"destinations": {"facebook-custom-audiences": {"name": "Facebook Custom Audiences",
"slug": "facebook-custom-audiences",
"actions": [{"actionId": "action_abc123",
"actionName": "Sync Audience",
"settings": [{"fieldKey": "audienceId",
"description": "The Facebook Audience ID",
"required": true
},
{"fieldKey": "adAccountId",
"description": "The Facebook Ad Account ID",
"required": true
}
]
}
]
},
"google-ads": {"name": "Google Ads",
"slug": "google-ads",
"actions": [{"actionId": "action_xyz789",
"actionName": "Update Customer List",
"settings": [{"fieldKey": "customerId",
"description": "The Google Ads Customer ID",
"required": true
},
{"fieldKey": "listId",
"description": "The Customer List ID",
"required": false
}
]
}
]
}
}
}
}

Remove Destination from Audience

Removes a Destination from an Audience. If there are activations associated with the Destination, the request will return a 409 Conflict error.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Destination Removed from Audience event in the audit trail.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS
destinationId required	string [ 1 .. 255 ] Example: ii_123456789

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/spaces/{spaceId}/audiences/{audienceId}/destination-connections/{destinationId}

Request samples

TypeScript
Java
Python
Go
curl

import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(
    api.activations.removeDestinationFromAudience('spa_9aQ1Lj62S4bomZKLF4DPqW', 'aud_0ujsszwN8NRY24YaXiTIE2VWDTS', 'ii_123456789')
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"status": "SUCCESS"
}
}

Update Destination for Audience

Updates a Destination for an Audience.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Destination Updated for Audience event in the audit trail.

Securitytoken

Request

path Parameters

spaceId required	string [ 1 .. 255 ] Example: spa_9aQ1Lj62S4bomZKLF4DPqW
audienceId required	string [ 1 .. 255 ] Example: aud_0ujsszwN8NRY24YaXiTIE2VWDTS
destinationId required	string [ 1 .. 255 ] Example: ii_123456789

Request Body schema: application/vnd.segment.v1alpha+json
required

	Array of objects (idSyncConfiguration) Identifier sync configuration - array of external IDs to sync with their strategies. Maximum 5 items allowed.
connectionSettings	any (connectionSettings) The settings that a Destination requires to create audiences on a third-party platform.

Responses

200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/spaces/{spaceId}/audiences/{audienceId}/destination-connections/{destinationId}

Request samples

application/vnd.segment.v1alpha+json

{"idSyncConfiguration": [{"externalId": "user_id",
"strategy": "first"
},
{"externalId": "email",
"strategy": "all"
}
]
}

Response samples

200
404
422
429

application/vnd.segment.v1alpha+json

{"data": {"destination": {"id": "ii_123456789"
},
"idSyncConfiguration": [{"externalId": "user_id",
"strategy": "first"
},
{"externalId": "email",
"strategy": "all"
}
]
}
}

Activations

Add Activation to Audience

path Parameters

Request Body schema: application/vnd.segment.v1alpha+jsonrequired

Add Destination to Audience

path Parameters

Request Body schema: application/vnd.segment.v1alpha+jsonrequired

List Destinations from Audience

path Parameters

query Parameters

Get Activation from Audience

path Parameters

Remove Activation from Audience

path Parameters

Update Activation for Audience

path Parameters

Request Body schema: application/vnd.segment.v1alpha+jsonrequired

List Activations from Audience

path Parameters

query Parameters

List Supported Destinations from Audience

path Parameters

query Parameters

Remove Destination from Audience

path Parameters

Update Destination for Audience

path Parameters

Request Body schema: application/vnd.segment.v1alpha+jsonrequired

Request Body schema: application/vnd.segment.v1alpha+json
required

Request Body schema: application/vnd.segment.v1alpha+json
required

Request Body schema: application/vnd.segment.v1alpha+json
required

Request Body schema: application/vnd.segment.v1alpha+json
required