Activations

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

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.

• 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.

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. Entity Added: Sends an event when an entity is added to the audience. Entity Removed: Sends an event when an entity is removed from the audience. Entity Values Changed: Sends an event when an entity's property values change. Restricted to freshness-enabled Destinations. All Events: Sends events for all trigger conditions (enters, exits, and entity value changes for freshness Destinations; enters and exits only for non-freshness Destinations). 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) Activation name. For Warehouse Destinations, this is used as the table name.
displayName	string (displayName) Optional human-readable label for the activation. Only supported for Warehouse Destinations. When omitted, the activationName is used as the label.
	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. May be omitted to create an activation without personalization, in which case the created activation is returned with no profile properties and no entities.
	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.

• 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.

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.

• 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.

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. For Warehouse Destinations, this is used as the table name. Omit this field to leave the name unchanged. An empty string is ignored rather than applied.
displayName	string or null (displayName) Optional human-readable label for the activation. Only supported for Warehouse Destinations. Send null to clear. When omitted, the activationName is used as the label.
	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. On update, profile and entities are evaluated separately. Omit either one to leave it unchanged. A value that is supplied replaces the stored value outright instead of being combined with it, so include every trait or property that should remain. Supplying an empty entities array removes all entities.
	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. On update, settings are applied one field at a time. A field that is not supplied keeps its stored value, and a field that is supplied has its value replaced outright.
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 the Destinations that have been reviewed and validated for activation with this audience type.

Use this endpoint to discover the available action ids and the Destination fields that can be mapped before creating an Activation.

Destinations returned with an empty actions array are audience Destinations that are configured through connection settings rather than action mappings, and do not use destinationMapping.

Destinations that are not returned here have not been reviewed for activation and are unsupported. To request a review for an additional Destination, contact your customer success manager.

• 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.

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.

• 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.

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.

• 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.

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. The supplied array replaces the entire stored configuration, so include every external id that should remain. Omitting mapTo on an entry clears any value stored for it. An empty array is treated the same as omitting the field and leaves the stored configuration unchanged.

connectionSettings

any (connectionSettings)

The settings that a Destination requires to create audiences on a third-party platform. The supplied object replaces the stored settings outright, so include every setting that should remain. Settings that are omitted are removed. An empty object is treated the same as omitting the field and leaves the stored settings unchanged.

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