Skip to main content

Documentation Index

Fetch the complete documentation index at: https://launchdarkly-preview.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This topic explains how to use the synced segments integration framework capability.

​
About synced segments

In LaunchDarkly, segments are lists of contexts that are used to manage flag targeting behavior in bulk. As a partner, you can use the synced segments integration framework capability to create and synchronize resources contained in external services, such as Amplitude cohorts or Segment Audiences, with LaunchDarkly segments. To learn more about segments, read Segments. The syncedSegment capability consists of a request parser. The properties of the parser describe the information about the segment to create or update. Many of the parser properties are required, for example, the properties that specify the name and ID of the cohort you are updating. Then, you have three options for how to send cohort information: The combination of the request parser’s memberArrayPath, addMemberArrayPath, removeMemberArrayPath, and memberArrayParser properties describe which option you are using and where the integration framework can expect to find the cohort information.

​
Request parser properties

The following properties specify the requestParser: | Property
Description
| --- | | environmentIdPath | (required) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains a valid LaunchDarkly client-side ID. | | contextKindPath
| (optional) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the segment’s context kind. If not specified, the context kind will default to user . To learn more about context kinds and where you can find a list of context kinds LaunchDarkly has observed, read Context kinds . | | cohortIdPath
| (required) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the external resource’s ID. This field has a recommended limit of 128 characters. | | cohortNamePath
| (required) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the external resource’s name. | | cohortUrlPath
| (optional) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the external resource’s URL. | | jsonResponseBody
| A template string used to represent the JSON response body required by the external service. | | arrayInclusion | (optional) If the request contains a single property that defines the type of message being sent, for example,add_members or remove_members, the arrayInclusion property is required. It has the following properties of its own: * path (required): The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the action to be performed. * matcher (required): A regex pattern LaunchDarkly uses to determine if it should consider the parsed path action value as an added member. If the value does not match the regex provided, the member will be removed. | | memberArrayPath
| (optional) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the list of members to be added or removed.
    Use this if you are using the boolean property or single action property to send cohort information. | | addMemberArrayPath
| (optional) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the list of members to be added or removed.
    Use this if you are using separate named arrays to send cohort information. Required if removeMemberArrayPath is specified. | | removeMemberArrayPath
| (optional) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the list of members to be added or removed.
    Use this if you are using separate named arrays to send cohort information. Required if addMemberArrayPath is specified. | | memberArrayParser
| (optional) An object describing how to interpret the information about each member. All paths are relative to the parent member array path, that is, either memberArrayPath or addMemberArrayPath and removeMemberArrayPath . | The following properties specify the embedded memberArrayParser: | Property
Description
| --- | | memberIdPath | (required) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the member’s ID, relative to the memberArrayPath . | | booleanMembershipPath
| (optional) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains a boolean property to indicate whether a member is to be added or removed. Required if memberArrayPath is specified. | | cohortIdPath
| (optional) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the external resource’s ID. This value will override the cohort name for a single member. | | cohortNamePath
| (optional) The [JSON pointer](https://datatracker.ietf.org/doc/html/rfc
  1. representation of a location in the HTTP request body that contains the external resource’s name. This value will override the cohort ID for a single member. |

​
Examples

The following sections contain examples of different types of request bodies and the manifest definitions of synced segment capabilities that would successfully parse them.

​
Boolean property

In the request body, use a boolean property to indicate whether a member is added or removed: 
        {
          "environmentId": "abcd123",
          "contextKind": "organization",
          "batch": [
            {
                "userId": "user-1234",
        		"cohortName": "Segment 1234",
            	"cohortId": "segment-1234",
            	"cohortUrl":  "https://example.com",
            	"value": true
            },
            {
                "userId": "user-5678",
                "cohortName": "Segment 1235",
                "cohortId": "segment-12345",
                "cohortUrl":  "https://example.com",
                "value": false
            }
          ]
        }

​
Separate named arrays

In the request body, use separate named arrays containing lists of members to add and remove. In the manifest, the memberArrayParser describes how to parse the addMemberArrayPath and removeMemberArrayPath arrays: 
        {
          "id_token": "CustomerIdToken",
          "action_type": "segment.users.sync",
          "customer_config": {
            "fields": [
              {
                "field_id": "workspace",
                "field_display_name": "Workspace",
                "value": {
                  "id": "abcd123",
                  "display_name": "Workspace 1"
                }
              }
            ]
          },
          "data": {
            "segment": {
              "id": "segment-1234",
              "name": "Segment 1234"
            },
            "add": [
              {
                "id": "user-123"
              },
              {
                "id": "user-456"
              }
            ],
            "remove": [
              {
                "id": "user-789"
              },
              {
                "id": "user-101112"
              }
            ]
          }
        }

​
Single property

In the request body, use a single action property for the entire batch to indicate whether the batch should be added or removed: 
    {
      "action": "add_members",
      "parameters": {
        "integration_project_id": "abcd123",
        "integration_cohort_name": "Segment 1234",
        "integration_cohort_id": "segment-1234",
        "integration_cohort_description": "description",
        "integration_session_id": "integration_session_id",
        "members": [
          {
            "email": "user-1234@customer.com",
            "integration_distinct_id": "user-1234",
            "first_name": "John",
            "last_name": "Doe",
            "phone_number": "xxx-xxx-xxxx"
          },
          {
            "email": "user-5678@customer.com",
            "integration_distinct_id": "user-5678",
            "first_name": "Jane",
            "last_name": "Doe",
            "phone_number": "xxx-xxx-xxxx"
          }
        ]
      }
    }

​
Response codes and custom responses

By default, LaunchDarkly returns one of the following response codes:
  • 204, success
  • 400, parsing problem
  • 403, unauthorized
  • 409, conflict
  • 429, rate limited, read Rate limiting for details on the X-Ratelimit-Reset header
  • 500, internal error
If you require a custom response, you can specify that with the jsonResponseBody in the syncedSegments object in your integration manifest. The jsonResponseBody supports Handlebars templating directly in the manifest. Here is an example manifest excerpt that specifies a jsonResponseBody: 
        "capabilities": {
            "syncedSegment": {
              "requestParser": {
                ...
              },
              "jsonResponseBody": "{ \"environmentId\": \"{{requestBody.environmentId}}\", \"projectKey\": \"{{projectKey}}\", \"envKey\": \"{{environmentKey}}\", \"segmentKey\": \"{{segmentKey}}\", \"segmentUrl\": \"{{segmentUrl}}\", {{#if errorMessage}}\"status\":\"failure\", \"error\": {\"message\": \"{{{errorMessage}}}\", \"code\": {{statusCode}} }{{else}}\"status\": \"success\"{{/if}} }"
            }
          }

​
Testing

After you have an initial implementation of your synced segments capability, you can test it using LaunchDarkly’s integration validation server. To learn more, read Validating an integration.