Export profiles to applications

This type of pipeline exports profiles from the workspace's data warehouse to an applications. It is available only for destination application connections that support users.

Create pipeline

Create a destination pipeline that exports profiles to an application.

Request

  • name

    string Required

    The pipeline's name.

    Must be a non-empty string with a maximum of 60 characters.

  • connection

    int Required

    The ID of the connection to which the profiles will be written. It must be a destination application connection that exports profiles.

  • target

    string Required

    The entity on which the pipeline operates, which must be "User" in order to create a pipeline that exports profiles.

    Possible values: "User".

  • enabled

    boolean

    Indicates if the pipeline is enabled once created.

  • filter

    nullable object

    The filter applied to the profiles. If it's not null, only the profiles that match the filter will be included.

    See the filters documentation for more details.

    • filter.logical

      string Required Possible values: "and" or "or".

    • filter.conditions

      array of object Required

      A filter's condition.

      • property

        string Required

        The name or path of the property. If the property has a json type, it can include a json path.

      • operator

        string Required

        The condition's operator. The allowed values depend on the property's type.

        Possible values: "is", "is not", "is less than", "is less than or equal to", "is greater than", "is greater than or equal to", "is between", "is not between", "contains", "does not contain", "is one of", "is not one of", "starts with", "ends with", "is before", "is on or before", "is after", "is on or after", "is true", "is false", "is empty", "is not empty", "is null", "is not null", "exists" or "does not exist".

      • values

        array of string

        The values the operator applies to, if any. These depend on both the operator and the property's type, including whether they're present and how many there are.

  • matching

    object Required

    The properties that identify whether a profile in the workspace matches a user in the application, to decide which users to update and which to create.

    • matching.in

      string Required

      The matching input property. It cannot be empty.

      It represents the path of the property in the profile schema. Its definition must also be included in the pipeline's input schema.

    • matching.out

      string Required

      The matching output property. It cannot be empty.

      It represents the path of the property in the application's profile schema. Its definition must also be included in the pipeline's output schema.

  • exportMode

    string Required

    The mode in which profiles are exported:

    • "CreateOnly": Only new users are created in the application. No existing users are modified.
    • "UpdateOnly": Only existing users are updated in the application. No new users are created.
    • "CreateOrUpdate": If a user already exists in the application, they are updated; otherwise, they are created as a new user.

    It should not be set to "CreateOnly" and "CreateOrUpdate" if the matching output property is read-only; if it is, user creation will fail because the matching output property must be writable.

    Possible values: "CreateOnly", "UpdateOnly" or "CreateOrUpdate".

  • updateOnDuplicates

    boolean

    Specifies whether to update application users even when multiple matches are found for a single profile in the workspace's data warehouse.

    If set to true, the update will proceed regardless of duplicates, otherwise the duplicated users will not be updated, and an error will be logged. The default value is false.

    This field does not affect user creation.

  • transformation

    object Required

    Defines the mapping or function that transforms profiles into users for the application.

    One of either a mapping or a function must be provided, but not both. The one that is not provided can be either missing or set to null.

    • transformation.mapping

      nullable object with string values Conditionally Required

      The transformation mapping. A key represents a path of a property in the destination schema of the application, and its corresponding value is an expression. This expression can reference property paths from the profile schema.

    • transformation.function

      nullable object Conditionally Required

      The transformation function. A JavaScript or Python function that given a workspace's profile, returns an application user.

      • transformation.function.source

        string Required

        The source code of the JavaScript or Python function.

        Must be a non-empty string with a maximum of 50000 characters.

      • transformation.function.language

        string Required

        The language of the function.

        Possible values: "JavaScript" or "Python".

      • transformation.function.preserveJSON

        boolean

        Specifies whether JSON values are passed to and returned from the function as strings, keeping their original format without any encoding or decoding.

      • transformation.function.inPaths

        array of string Required

        The paths of the properties that will be passed to the function. At least one path must be present.

      • transformation.function.outPaths

        array of string Required

        The paths of the properties that may be returned by the function. At least one path must be present.

  • inSchema

    schema Required

    The schema of the input matching property, the properties used in the filter, and the input properties within the transformation.

    When exporting profiles to apps, it should be a subset of profile schema.

  • outSchema

    schema Required

    The schema of the output matching property and the output properties within the transformation.

    When exporting profiles to apps, it should be a subset of application's destination schema, also including the schema of the output matching property if it is not already present.

Response

  • id

    int

    The ID of the pipeline.
POST /v1/pipelines
curl https://example.com/v1/pipelines \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"name": "Export customers",
"connection": 230527183,
"target": "User",
"enabled": true,
"filter": {
"logical": "and",
"conditions": [
{
"property": "address.country",
"operator": "is",
"values": [
"US"
]
}
]
},
"matching": {
"in": "email",
"out": "contact.email"
},
"exportMode": "CreateOnly",
"updateOnDuplicates": false,
"transformation": {
"mapping": {
"contact.firstname": "first_name",
"contact.lastname": "last_name"
}
},
"inSchema": {
"kind": "object",
"properties": [
{
"name": "first_name",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "First name"
},
{
"name": "last_name",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "Last name"
},
{
"name": "email",
"type": {
"kind": "string",
"maxLength": 254
},
"readOptional": true,
"description": "Email"
},
{
"name": "address",
"type": {
"kind": "object",
"properties": [
{
"name": "country",
"type": {
"kind": "string",
"maxLength": 2
},
"readOptional": true,
"description": "Country"
}
]
},
"readOptional": true,
"description": "Address"
}
]
},
"outSchema": {
"kind": "object",
"properties": [
{
"name": "contact",
"type": {
"kind": "object",
"properties": [
{
"name": "email",
"type": {
"kind": "string"
},
"nullable": true,
"description": "Email"
},
{
"name": "firstname",
"type": {
"kind": "string"
},
"nullable": true,
"description": "First Name"
},
{
"name": "lastname",
"type": {
"kind": "string"
},
"nullable": true,
"description": "Last Name"
}
]
}
}
]
}
}'
Response
{
  "id": 705981339
}
Errors
404
workspace does not exist
422
connection does not exist
422
connector does not exist
422
transformation language is not supported

Update pipeline

Update a destination pipeline that exports profiles to an application.

Request

  • :id

    int Required

    The ID of the destination application pipeline that exports profiles.

  • name

    string Required

    The pipeline's name.

    Must be a non-empty string with a maximum of 60 characters.

  • enabled

    boolean

    Indicates if the pipeline is enabled. Use the Set status endpoint to change only the pipeline's status.

  • filter

    nullable object

    The filter applied to the profiles. If it's not null, only the profiles that match the filter will be included.

    See the filters documentation for more details.

    • filter.logical

      string Required Possible values: "and" or "or".

    • filter.conditions

      array of object Required

      A filter's condition.

      • property

        string Required

        The name or path of the property. If the property has a json type, it can include a json path.

      • operator

        string Required

        The condition's operator. The allowed values depend on the property's type.

        Possible values: "is", "is not", "is less than", "is less than or equal to", "is greater than", "is greater than or equal to", "is between", "is not between", "contains", "does not contain", "is one of", "is not one of", "starts with", "ends with", "is before", "is on or before", "is after", "is on or after", "is true", "is false", "is empty", "is not empty", "is null", "is not null", "exists" or "does not exist".

      • values

        array of string

        The values the operator applies to, if any. These depend on both the operator and the property's type, including whether they're present and how many there are.

  • matching

    object Required

    The properties that identify whether a profile in the workspace matches a user in the application, to decide which users to update and which to create.

    • matching.in

      string Required

      The matching input property. It cannot be empty.

      It represents the path of the property in the profile schema. Its definition must also be included in the pipeline's input schema.

    • matching.out

      string Required

      The matching output property. It cannot be empty.

      It represents the path of the property in the application's profile schema. Its definition must also be included in the pipeline's output schema.

  • exportMode

    string Required

    The mode in which profiles are exported:

    • "CreateOnly": Only new users are created in the application. No existing users are modified.
    • "UpdateOnly": Only existing users are updated in the application. No new users are created.
    • "CreateOrUpdate": If a user already exists in the application, they are updated; otherwise, they are created as a new user.

    It should not be set to "CreateOnly" and "CreateOrUpdate" if the matching output property is read-only; if it is, user creation will fail because the matching output property must be writable.

    Possible values: "CreateOnly", "UpdateOnly" or "CreateOrUpdate".

  • updateOnDuplicates

    boolean

    Specifies whether to update application users even when multiple matches are found for a single profile in the workspace's data warehouse.

    If set to true, the update will proceed regardless of duplicates, otherwise the duplicated users will not be updated, and an error will be logged. The default value is false.

    This field does not affect user creation.

  • transformation

    object Required

    Defines the mapping or function that transforms profiles into users for the application.

    One of either a mapping or a function must be provided, but not both. The one that is not provided can be either missing or set to null.

    • transformation.mapping

      nullable object with string values Conditionally Required

      The transformation mapping. A key represents a path of a property in the destination schema of the application, and its corresponding value is an expression. This expression can reference property paths from the profile schema.

    • transformation.function

      nullable object Conditionally Required

      The transformation function. A JavaScript or Python function that given a workspace's profile, returns an application user.

      • transformation.function.source

        string Required

        The source code of the JavaScript or Python function.

        Must be a non-empty string with a maximum of 50000 characters.

      • transformation.function.language

        string Required

        The language of the function.

        Possible values: "JavaScript" or "Python".

      • transformation.function.preserveJSON

        boolean

        Specifies whether JSON values are passed to and returned from the function as strings, keeping their original format without any encoding or decoding.

      • transformation.function.inPaths

        array of string Required

        The paths of the properties that will be passed to the function. At least one path must be present.

      • transformation.function.outPaths

        array of string Required

        The paths of the properties that may be returned by the function. At least one path must be present.

  • inSchema

    schema Required

    The schema of the input matching property, the properties used in the filter, and the input properties within the transformation.

    When exporting profiles to apps, it should be a subset of profile schema.

  • outSchema

    schema Required

    The schema of the output matching property and the output properties within the transformation.

    When exporting profiles to apps, it should be a subset of application's destination schema, also including the schema of the output matching property if it is not already present.

Response

No response.
PUT /v1/pipelines/:id
curl -X PUT https://example.com/v1/pipelines/705981339 \
-H "Authorization: Bearer api_xxxxxxx" \
--json '{
"name": "Export customers",
"enabled": true,
"filter": {
"logical": "and",
"conditions": [
{
"property": "address.country",
"operator": "is",
"values": [
"US"
]
}
]
},
"matching": {
"in": "email",
"out": "contact.email"
},
"exportMode": "CreateOnly",
"updateOnDuplicates": false,
"transformation": {
"mapping": {
"contact.firstname": "first_name",
"contact.lastname": "last_name"
}
},
"inSchema": {
"kind": "object",
"properties": [
{
"name": "first_name",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "First name"
},
{
"name": "last_name",
"type": {
"kind": "string",
"maxLength": 100
},
"readOptional": true,
"description": "Last name"
},
{
"name": "email",
"type": {
"kind": "string",
"maxLength": 254
},
"readOptional": true,
"description": "Email"
},
{
"name": "address",
"type": {
"kind": "object",
"properties": [
{
"name": "country",
"type": {
"kind": "string",
"maxLength": 2
},
"readOptional": true,
"description": "Country"
}
]
},
"readOptional": true,
"description": "Address"
}
]
},
"outSchema": {
"kind": "object",
"properties": [
{
"name": "contact",
"type": {
"kind": "object",
"properties": [
{
"name": "email",
"type": {
"kind": "string"
},
"nullable": true,
"description": "Email"
},
{
"name": "firstname",
"type": {
"kind": "string"
},
"nullable": true,
"description": "First Name"
},
{
"name": "lastname",
"type": {
"kind": "string"
},
"nullable": true,
"description": "Last Name"
}
]
}
}
]
}
}'
Errors
404
workspace does not exist
404
pipeline does not exist
422
transformation language is not supported

Get pipeline

Get a destination pipeline that exports profiles to an application.

Request

  • :id

    int Required

    The ID of the destination application pipeline that exports profiles.

Response

  • id

    int

    The ID of the destination application pipeline that exports profiles.

  • name

    string

    The pipeline's name.

    It is not longer than 60 characters.

  • connector

    string

    The code of the connection's connector.

  • connectorType

    string

    The type of the connection's connector. It is always "Application" when the pipeline exports profiles to an application.

    Possible values: "Application", "Database", "FileStorage", "MessageBroker", "SDK" or "Webhook".

  • connection

    int

    The ID of the connection to which the profiles will be exported. It is a destination application.

  • connectionRole

    string

    The role of the pipeline's connection. It is always "Destination" when the pipeline exports profiles to an application.

    Possible values: "Source" or "Destination".

  • target

    string

    The entity on which the pipeline operates. It is always "User" when the pipeline exports profiles to an application.

    Possible values: "User" or "Event".

  • enabled

    boolean

    Indicates if the pipeline is enabled.

  • filter

    nullable object

    The filter applied to the profiles. If it's not null, only the profiles that match the filter will be included.

    See the filters documentation for more details.

    • filter.logical

      string Possible values: "and" or "or".

    • filter.conditions

      array of object

      A filter's condition.

      • property

        string

        The name or path of the property. If the property has a json type, it can include a json path.

      • operator

        string

        The condition's operator. The allowed values depend on the property's type.

        Possible values: "is", "is not", "is less than", "is less than or equal to", "is greater than", "is greater than or equal to", "is between", "is not between", "contains", "does not contain", "is one of", "is not one of", "starts with", "ends with", "is before", "is on or before", "is after", "is on or after", "is true", "is false", "is empty", "is not empty", "is null", "is not null", "exists" or "does not exist".

      • values

        array of string

        The values the operator applies to, if any. These depend on both the operator and the property's type, including whether they're present and how many there are.

  • matching

    object

    The properties used to identify the match between a profile in the workspace and a user in the application. These properties determine which users should be updated and which should be created as new in the application.

    • matching.in

      string

      The matching input property.

      It represents the name of the property in the profile schema. Its definition is included in the pipeline's input schema.

    • matching.out

      string

      The matching output property.

      It represents the name of the property in the application's profile schema. Its definition is included in the pipeline's output schema.

  • exportMode

    string

    The mode in which profiles are exported:

    • "CreateOnly": Only new users are created in the application. No existing users are modified.
    • "UpdateOnly": Only existing users are updated in the application. No new users are created.
    • "CreateOrUpdate": If a user already exists in the application, they are updated; otherwise, they are created as a new user.
    Possible values: "CreateOnly", "UpdateOnly" or "CreateOrUpdate".

  • updateOnDuplicates

    boolean

    Determines whether, when multiple application users match a single profile in the workspace's data warehouse, they should still be updated.

    If set to true, the update will proceed regardless of duplicates, otherwise the duplicated users will not be updated, and an error will be logged.

    This field does not affect user creation.

  • transformation

    object

    The mapping or function responsible for transforming profiles into application users.

    One of either a mapping or a function is present, but not both. The one that is not present is null.

    • transformation.mapping

      nullable object with string values

      The transformation mapping. A key represents a path of a property in the destination schema of the application, and its corresponding value is an expression. This expression can reference property paths from the profile schema.

    • transformation.function

      nullable object

      The transformation function. A JavaScript or Python function that given a workspace's profile, returns an application user.

      • transformation.function.source

        string

        The source code of the JavaScript or Python function.

        It is not longer than 50000 characters.

      • transformation.function.language

        string

        The language of the function.

        Possible values: "JavaScript" or "Python".

      • transformation.function.preserveJSON

        boolean

        Specifies whether JSON values are passed to and returned from the function as strings, keeping their original format without any encoding or decoding.

      • transformation.function.inPaths

        array of string

        The paths of the properties that will be passed to the function. It contains at least one property path.

      • transformation.function.outPaths

        array of string

        The paths of the properties that may be returned by the function. It contains at least one property path.

  • inSchema

    schema

    The schema of the input matching property, the properties used in the filter, and the input properties within the transformation.

  • outSchema

    schema

    The schema of the output matching property and the output properties within the transformation.

  • running

    boolean

    Indicates if the pipeline is running.

  • scheduleStart

    nullable int

    The start time of the schedule in minutes, counting from 00:00. It specifies the minute when the first scheduled run of the day begins. Subsequent runs occur based on the interval defined by the scheduler period. If the scheduler is disabled, this value is null.

  • schedulePeriod

    nullable string

    The schedule period, which determines how often the export runs automatically. If it is null, the scheduler is disabled, and no automatic runs will occur.

    To change the schedule period, use the Set schedule period endpoint.

    Possible values: "5m", "15m", "30m", "1h", "2h", "3h", "6h", "8h", "12h" or "24h".
GET /v1/pipelines/:id
curl https://example.com/v1/pipelines/705981339 \
-H "Authorization: Bearer api_xxxxxxx"
Response
{
  "id": 705981339,
  "name": "Export customers",
  "connector": "mailchimp",
  "connectorType": "Application",
  "connection": 1371036433,
  "connectionRole": "Destination",
  "target": "User",
  "enabled": true,
  "filter": {
    "logical": "and",
    "conditions": [
      {
        "property": "address.country",
        "operator": "is",
        "values": [
          "US"
        ]
      }
    ]
  },
  "matching": {
    "in": "email",
    "out": "email"
  },
  "exportMode": "CreateOnly",
  "updateOnDuplicates": false,
  "transformation": {
    "mapping": {
      "contact.firstname": "first_name",
      "contact.lastname": "last_name"
    }
  },
  "inSchema": {
    "kind": "object",
    "properties": [
      {
        "name": "first_name",
        "type": {
          "kind": "string",
          "maxLength": 100
        },
        "readOptional": true,
        "description": "First name"
      },
      {
        "name": "last_name",
        "type": {
          "kind": "string",
          "maxLength": 100
        },
        "readOptional": true,
        "description": "Last name"
      },
      {
        "name": "email",
        "type": {
          "kind": "string",
          "maxLength": 254
        },
        "readOptional": true,
        "description": "Email"
      },
      {
        "name": "address",
        "type": {
          "kind": "object",
          "properties": [
            {
              "name": "country",
              "type": {
                "kind": "string",
                "maxLength": 2
              },
              "readOptional": true,
              "description": "Country"
            }
          ]
        },
        "readOptional": true,
        "description": "Address"
      }
    ]
  },
  "outSchema": {
    "kind": "object",
    "properties": [
      {
        "name": "contact",
        "type": {
          "kind": "object",
          "properties": [
            {
              "name": "email",
              "type": {
                "kind": "string"
              },
              "nullable": true,
              "description": "Email"
            },
            {
              "name": "firstname",
              "type": {
                "kind": "string"
              },
              "nullable": true,
              "description": "First Name"
            },
            {
              "name": "lastname",
              "type": {
                "kind": "string"
              },
              "nullable": true,
              "description": "Last Name"
            }
          ]
        }
      }
    ]
  },
  "running": false,
  "scheduleStart": 15,
  "schedulePeriod": "1h"
}
Errors
404
workspace does not exist
404
pipeline does not exist