Twilio Segment logo

Transformations

With Transformations, you can change data as it flows through Segment to:

  • Correct bad data
  • Customize data for a specific destination
  • Align events with your tracking plan

With Segment's Public API, you can use Transformations for several use cases:

  1. Rename Track events
  • Use newEventName in the createTransformation or updateTransformation API call.
  1. Rename a property (Track events) or a trait (Identify or Group events)
  • Use propertyRenames in the createTransformation or updateTransformation API call.
  1. Update a property value to a different static value or add a new property and set a static value
  • Use propertyValueTransformations in the createTransformation or updateTransformation API call.
  • Segment currently supports setting static values for top-level fields with propertyValueTransformations. However, Segment doesn't support changing fields outside the properties or traits object with propertyRenames.

Visit Segment's Transformations docs to learn more.

Create Transformation

Creates a new Transformation.

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

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

Securitytoken
Request
Request Body schema:
required
name
required
string (name)

The name of the Transformation.

sourceId
required
string (sourceId)

The Source to be associated with the Transformation.

destinationMetadataId
string (destinationMetadataId)

The optional Destination metadata id to be associated with the Transformation.

enabled
required
boolean (enabled)

If the Transformation should be enabled.

if
required
string (if)

If statement (FQL) to match events.

For standard event matchers, use the following: Track -> "event='<eventName>'" Identify -> "type='identify'" Group -> "type='group'"

drop
boolean (drop)

Optional boolean value if the Transformation should drop the event entirely when the if statement matches, ignores all other transforms.

newEventName
string (newEventName)

Optional new event name for renaming events. Works only for 'track' event type.

Array of objects (propertyRenames)

Optional array for renaming properties collected by your events.

Array of objects (propertyValueTransformations)

Optional array for transforming properties and values collected by your events. Limited to 10 properties.

Array of objects (fqlDefinedProperties)

Optional array for defining new properties in FQL. Currently limited to 1 property.

allowProperties
Array of strings (allowProperties)

Optional array for allowing properties from your events.

object (hashPropertiesConfiguration)

Optional object for hashing properties within an event.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/transformations
Request samples
{
  • "name": "Name of the new transformation",
  • "sourceId": "qQEHquLrjRDN9j1ByrChyn",
  • "enabled": true,
  • "newEventName": "new-event-name",
  • "propertyRenames": [
    ],
  • "propertyValueTransformations": [
    ],
  • "if": "event = 'Example Event V1'"
}
Response samples
{
  • "data": {
    }
}

List Transformations

Lists all Transformations in the Workspace.

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

Securitytoken
Request
query Parameters
object (PaginationInput)

Pagination options.

This parameter exists in v1.

Example: pagination=pagination.count=20
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

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

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

try {
  const result = await unwrap(api.transformations.listTransformations())
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Delete Transformation

Deletes a Transformation.

• When called, this endpoint may generate the Transformation Deleted event in the audit trail.

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

Securitytoken
Request
path Parameters
transformationId
required
string [ 1 .. 255 ]
Example: 2c0vVuRdDmJ3UQkVjd5WxaA3dar
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/transformations/{transformationId}
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

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

try {
  const result = await unwrap(api.transformations.deleteTransformation('2c0vVuRdDmJ3UQkVjd5WxaA3dar'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Get Transformation

Gets a Transformation.

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

Securitytoken
Request
path Parameters
transformationId
required
string [ 1 .. 255 ]
Example: pHrD51Ds35Zjfka84yXQE6
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/transformations/{transformationId}
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

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

try {
  const result = await unwrap(api.transformations.getTransformation('pHrD51Ds35Zjfka84yXQE6'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Update Transformation

Updates an existing Transformation.

• When called, this endpoint may generate the Transformation Updated event in the audit trail.

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

Securitytoken
Request
path Parameters
transformationId
required
string [ 1 .. 255 ]
Example: pHrD51Ds35Zjfka84yXQE6
Request Body schema:
required
name
string (name)

The name of the Transformation.

sourceId
string (sourceId)

The optional Source to be associated with the Transformation.

destinationMetadataId
string (destinationMetadataId)

The optional Destination metadata to be associated with the Transformation.

enabled
boolean (enabled)

If the Transformation should be enabled.

if
string (if)

If statement (FQL) to match events.

For standard event matchers, use the following: Track -> "event='<eventName>'" Identify -> "type='identify'" Group -> "type='group'"

drop
boolean (drop)

Optional boolean value if the Transformation should drop the event entirely when the if statement matches, ignores all other transforms.

newEventName
string (newEventName)

Optional new event name for renaming events. Works only for 'track' event type.

Array of objects (propertyRenames)

Optional array for renaming properties collected by your events.

Array of objects (propertyValueTransformations)

Optional array for transforming properties and values collected by your events. Limited to 10 properties.

Array of objects (fqlDefinedProperties)

Optional array for updating properties defined in FQL. Currently limited to 1 property.

allowProperties
Array of strings (allowProperties)

Optional array for allowing properties from your events.

object (hashPropertiesConfiguration)

Optional object for hashing properties within an event.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/transformations/{transformationId}
Request samples
{
  • "name": "updated-name",
  • "sourceId": "rh5BDZp6QDHvXFCkibm1pR",
  • "enabled": true,
  • "destinationMetadataId": "547610a5db31d978f14a5c4e",
  • "if": "event=\"my-event\"",
  • "newEventName": "my-updated-event",
  • "propertyRenames": [
    ],
  • "propertyValueTransformations": [
    ]
}
Response samples
{
  • "data": {
    }
}
➔ Next to Spaces