> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Synced segments capability

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

> For the complete documentation index, see [llms.txt](/llms.txt). For the full documentation snapshot, see [llms-full.txt](/llms-full.txt).

## 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](/home/flags/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:

* Use a [boolean property](#boolean-property) to indicate whether a member should be added or removed
* Use [separate named arrays](#separate-named-arrays), one for members being added and one for members being removed
* Use a [single `action` property](#single-property) to indicate whether the set of members should be added or removed

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

\| --- |
\| <code>environmentIdPath</code>

\| (required) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. representation of a location in the HTTP request body that contains a valid LaunchDarkly client-side ID. |
      \| <code>contextKindPath</code>

\| (optional) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. 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 <code>user</code> . To learn more about context kinds and where you can find a list of context kinds LaunchDarkly has observed, read [Context kinds](/home/flags/context-kinds) . |
      \| <code>cohortIdPath</code>

\| (required) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. 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. |
      \| <code>cohortNamePath</code>

\| (required) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. representation of a location in the HTTP request body that contains the external resource's name. |
      \| <code>cohortUrlPath</code>

\| (optional) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. representation of a location in the HTTP request body that contains the external resource's URL. |
      \| <code>jsonResponseBody</code>

\| A template string used to represent the JSON response body required by the external service. |
\| <code>arrayInclusion</code>

\| (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: \* <code>path</code> (required): The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. representation of a location in the HTTP request body that contains the action to be performed. \* <code>matcher</code> (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. |
      \| <code>memberArrayPath</code>

\| (optional) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. representation of a location in the HTTP request body that contains the list of members to be added or removed. <br /> Use this if you are using the [boolean property](#boolean-property) or [single `action` property](#single-property) to send cohort information. |
      \| <code>addMemberArrayPath</code>

\| (optional) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. representation of a location in the HTTP request body that contains the list of members to be added or removed. <br /> Use this if you are using [separate named arrays](#separate-named-arrays) to send cohort information. Required if `removeMemberArrayPath` is specified. |
      \| <code>removeMemberArrayPath</code>

\| (optional) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. representation of a location in the HTTP request body that contains the list of members to be added or removed. <br /> Use this if you are using [separate named arrays](#separate-named-arrays) to send cohort information. Required if `addMemberArrayPath` is specified. |
      \| <code>memberArrayParser</code>

\| (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 <code>memberArrayPath</code> or <code>addMemberArrayPath</code> and <code>removeMemberArrayPath</code> . |

The following properties specify the embedded `memberArrayParser`:

\| Property

| Description |
| - |

\| --- |
\| <code>memberIdPath</code>

\| (required) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. representation of a location in the HTTP request body that contains the member's ID, relative to the <code>memberArrayPath</code> . |
      \| <code>booleanMembershipPath</code>

\| (optional) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. 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 <code>memberArrayPath</code> is specified. |
      \| <code>cohortIdPath</code>

\| (optional) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. 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. |
      \| <code>cohortNamePath</code>

\| (optional) The \[JSON pointer]\([https://datatracker.ietf.org/doc/html/rfc](https://datatracker.ietf.org/doc/html/rfc)

6901. 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:

<CodeGroup>
  ```json title="Example request body" theme={null}
          {
            "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
              }
            ]
          }
  ```

  ```json title="Example manifest (excerpt)" theme={null}
          "capabilities": {
              "syncedSegment": {
                "requestParser": {
                  "environmentIdPath": "/environmentId",
                  "contextKindPath": "/contextKind",
                  "cohortIdPath": "/batch/0/cohortId",
                  "cohortNamePath": "/batch/0/cohortName",
                  "cohortUrlPath": "/batch/0/cohortUrl",
                  "memberArrayPath": "/batch",
                  "memberArrayParser": {
                    "memberIdPath": "/userId",
                    "booleanMembershipPath": "/value",
                    "cohortNamePath": "/cohortName",
                    "cohortIdPath": "/cohortId"
                  }
                }
              }
            }
  ```
</CodeGroup>

### 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:

<CodeGroup>
  ```json title="Example request body" theme={null}
          {
            "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"
                }
              ]
            }
          }
  ```

  ```json title="Example manifest (excerpt)" theme={null}
          "capabilities": {
              "syncedSegment": {
                "requestParser": {
                  "environmentIdPath": "/customer_config/fields/0/value/id",
                  "cohortIdPath": "/data/segment/id",
                  "cohortNamePath": "/data/segment/name",
                  "addMemberArrayPath": "/data/add",
                  "removeMemberArrayPath": "/data/remove",
                  "memberArrayParser": {
                    "memberIdPath": "/id"
                  }
                }
              }
            }
  ```
</CodeGroup>

### 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:

<CodeGroup>
  ```json title="Example request body" theme={null}
      {
        "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"
            }
          ]
        }
      }
  ```

  ```json title="Example manifest (excerpt)" theme={null}
          "capabilities": {
              "syncedSegment": {
                "requestParser": {
                  "environmentIdPath": "/parameters/integration_project_id",
                  "cohortIdPath": "/parameters/integration_cohort_id",
                  "cohortNamePath": "/parameters/integration_cohort_name",
                  "arrayInclusion": {
                    "path": "/action",
                    "matcher": "^(members|add_members)$"
                  },
                  "memberArrayPath": "/parameters/members",
                  "memberArrayParser": {
                    "memberIdPath": "/integration_distinct_id"
                  }
                }
              }
            }
  ```
</CodeGroup>

### 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](/api#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`:

<CodeGroup>
  ```json title="Example manifest (excerpt)" theme={null}
          "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}} }"
              }
            }
  ```
</CodeGroup>

## 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](/integrations/partner-integrations/validating).