# 3.5 Create a segment - API

In this exercise, you'll use Postman and Adobe I/O to create a segment and store the results of that segment as a dataset, by making use of Adobe Experience Platform's APIs.

## Story

In the Real-time Customer Profile, all profile data is shown alongside event data and existing segment memberships. The data that is shown can come from anywhere, from Adobe applications and external solutions. This is the most powerful view in Adobe Experience Platform, the experience system of record.

## Exercise 3.5.1 - Create a segment through the Platform API

Go to Postman.

Locate the collection: **\_Adobe Experience Platform Enablement**. In this collection, you'll see a folder **2. Segmentation**. We'll be using these requests in this exercise.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-6478e16a4d68b71c79850f2d77af95231efcf08a%2Fpmdtl.png?alt=media)

What we'll do next is follow all the required steps to create a segment through the API. We're going to build a simple segment: "**ldap** - All Female Customers".

### Step 1 - Create a Segment Definition

Click on the request named **Step 1 - Profile: Create A Segment Definition**.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-c8f3f3f50ae3969c2aa35927551933aefd7e50ac%2Fs1_call.png?alt=media)

Go the the **Body** section of this request.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-d136c34083cd79b38c645bcd194a5f8ee13bbdf6%2Fs1_body.png?alt=media)

In the **Body** of this request, you'll see the following:

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-fbbeaf8346cbca4a7a4890c24c8eb55babd7bbb3%2Fs1_bodydtl.png?alt=media)

The language used for this request is called Profile Query Language, or **PQL**.

You can find more info and documentation about PQL [here](https://experienceleague.adobe.com/docs/experience-platform/segmentation/pql/overview.html?lang=en).

Attention: please update the variable **name** in the below request by replacing **ldap** with your specific **ldap**.

```json
{
    "name" : "ldap - API - All Female Customer",
    "expression" : {"type":"PQL", "format":"pql/json", "value":"{\"nodeType\":\"fnApply\",\"fnName\":\"in\",\"params\":[{\"nodeType\":\"fieldLookup\",\"fieldName\":\"gender\",\"object\":{\"nodeType\":\"fieldLookup\",\"fieldName\":\"person\",\"object\":{\"nodeType\":\"literal\",\"literalType\":\"XDMObject\",\"value\":\"profile\"}}},{\"literalType\":\"List\",\"nodeType\":\"literal\",\"value\":[\"female\"]}]}"},
    "createdBy": "ldap",
    "schema" : { "name" : "_xdm.context.profile"},
    "ttlInDays" : 90
}
```

After adding your specific **ldap**, the Body should look similar to this:

```json
{
    "name" : "vangeluw - API - All Female Customer",
    "expression" : {"type":"PQL", "format":"pql/json", "value":"{\"nodeType\":\"fnApply\",\"fnName\":\"in\",\"params\":[{\"nodeType\":\"fieldLookup\",\"fieldName\":\"gender\",\"object\":{\"nodeType\":\"fieldLookup\",\"fieldName\":\"person\",\"object\":{\"nodeType\":\"literal\",\"literalType\":\"XDMObject\",\"value\":\"profile\"}}},{\"literalType\":\"List\",\"nodeType\":\"literal\",\"value\":[\"female\"]}]}"},
    "createdBy": "vangeluw",
    "schema" : { "name" : "_xdm.context.profile"},
    "ttlInDays" : 90
}
```

You should also verify the **Header** - fields of your request. Go to **Headers**. You'll then see this:

![Postman](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-ca53deb4d8932d1cf5d650a619eda237e9e7db77%2Fs1_h.png?alt=media)

| Key            | Value              |
| -------------- | ------------------ |
| x-sandbox-name | `--aepSandboxId--` |

> \[!NOTE]
>
> You need to specify the name of the Adobe Experience Platform sandbox you're using. Your x-sandbox-name should be `--aepSandboxId--`.

Now, click the blue **Send** button to create the segment and view the results of that.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-86af94636b2cf3ac66941fa58b0196b6db7732ee%2Fs1_bodydtl_results.png?alt=media)

After this step, you can view your segment definition in the Platform UI. To check this, log in to Adobe Experience Platform and go to **Segments**.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-7bf051d3e82db8861e93ef4c09d3cdcebe3c0552%2Fs1_segmentdef.png?alt=media)

### Step 2 - Create a Segment POST Job

In the previous exercise, you created a *streaming* segment. A streaming segment continuously evaluates qualifications in real-time. What you're doing here, is creating a *batch* segment. Batch segment gives you a preview of what the segment could look like in terms of qualifications, but *that don't mean that the segment has actually run*. Currently, *nobody qualifies for this segment*. To make people qualify, the batch segment needs to run, which is exactly what we'll do here.

Let's now POST a Segment Job.

Go to Postman.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-6478e16a4d68b71c79850f2d77af95231efcf08a%2Fpmdtl.png?alt=media)

In your Postman collection, click on the request named **Step 2 - POST Segment Job** to open it.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-3105fac8a06e823b439ec2280542b238fc2d266e%2Fs2_call.png?alt=media)

You should also verify the **Header** - fields of your request. Go to **Headers**. You'll then see this:

![Postman](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-beedcabefd6735cdcf6f579349a87a8592d71cb0%2Fs2headers.png?alt=media)

| Key            | Value              |
| -------------- | ------------------ |
| x-sandbox-name | `--aepSandboxId--` |

> \[!NOTE]
>
> You need to specify the name of the Adobe Experience Platform sandbox you're using. Your x-sandbox-name should be `--aepSandboxId--`.

Click on the blue **Send** button.

You should see a similar result:

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-0f6b3b2c4a5becb60cff3b160be487c5a565ae86%2Fs2_call_response.png?alt=media)

This Segment Job is now running, and this may take some time. In Step 3, you'll be able to check the status of this job.

### Step 3 - GET Segment Job status

Go to Postman.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-6478e16a4d68b71c79850f2d77af95231efcf08a%2Fpmdtl.png?alt=media)

In your Postman collection, click on the request named **Step 3 - GET Segment Job status**.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-99a3e00b7684c43a265f5a9afaa9765bb91b4458%2Fs3_call.png?alt=media)

You should also verify the **Header** - fields of your request. Go to **Headers**. You'll then see this:

![Postman](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-20341e593f6a654e164691168b22b3d6ecb2c1b0%2Fs3headers.png?alt=media)

| Key            | Value              |
| -------------- | ------------------ |
| x-sandbox-name | `--aepSandboxId--` |

> \[!NOTE]
>
> You need to specify the name of the Adobe Experience Platform sandbox you're using. Your x-sandbox-name should be `--aepSandboxId--`.

Click on the blue **Send** button.

You should see a similar result:

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-a635c714eb52446c2ac1be07a94370125cd04280%2Fs3_status.png?alt=media)

In this example, the **status** of the job is set to **QUEUED**.

Repeat this request by clicking the blue **Send** button every couple of minutes until the **status** is set to **SUCCEEDED**.

![Segmentation](https://858372621-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpBC8bA57il8Sj47B7QPJ%2Fuploads%2Fgit-blob-eaaf038e8e1b908cae1c0a930e77c41bc4a686e4%2Fs3_status_succeeded.png?alt=media)

Once the status is **SUCCEEDED**, your segment job has run and customers are now qualifying for the segment.

Congrats, you've successfully completed the Segmentation exercise. Let's now have a look how the Real-time Customer Profile can be activated across the enterprise. s


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.adobesandbox.com/comprehensive-technical-tutorial-archive/module3/ex5.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.