# Getting Started with the Marketing Campaigns V2 Segmentation API

The V2 Segmentation API allows you to create and manage segments using a subset of SQL that includes statements and operations necessary to define any segment. In addition, this version of the Segmentation API exposes the contact\_data and event\_data tables to enable SQL-compatible queries.

You can use this API to engage your contacts that meet specific criteria that you specify from a set of data. The segment can be based anything from a combination of criteria on a set of the contacts' attributes, as well as any contacts that have specific engagement events that also satisfy the aforementioned criteria.

## Benefits of This New API

The Segmentation V2 API uses SQL instead of the proprietary SendGrid Query Language (sgql) to specify segments, meaning you do not need to learn a new query language and can leverage skills in widely used SQL. Since this version of the API exposes the contact\_data and event\_data tables and gives you SQL access, any specification that is expressible via SQL that would result in a meaningful segment given the structure of the table is possible. Some segments that we can build now that we couldn't with V1 are:

* Segments built over multiple engagement events.
* Segments of contacts that have never been engaged.

## Limitations of This New API

* Not all of SQL is supported, meaning the Segmentation V2 API's query language is a SQL-compatible subset of SQL.
* You must select `contact_id`, and `updated_at` in the primary select clause. This in turn constrains the rest of the query in specific ways which is an effect of how SQL works. The examples in the reference will clarify these aspects of the V2 API.
* None of the data modification constructs of SQL are supported.

## Prerequisites

Before you can use the V2 Segmentation API you will need to do the following:

1. Create or log into your SendGrid account.
2. Navigate to **Settings** and create an [API Key](/docs/sendgrid/ui/account-and-settings/api-keys).
3. Upload contacts using the [UI](/docs/sendgrid/ui/managing-contacts/create-and-manage-contacts) or [API](/docs/sendgrid/api-reference/contacts/add-or-update-a-contact).

## Create a Segment

Below are some examples of segments you can create using the V2 Segmentation API. For more code samples and use cases, see the [Marketing Campaigns Segmentation V2 Query Reference](/docs/sendgrid/for-developers/sending-email/marketing-campaigns-v2-segmentation-query-reference).

**Example Body**

```json
{
"name":"string (required)",
"query_dsl":"SQL string (required)",
"parent_list_ids":"array[string] (optional)"
}
```

**Select all contacts**

```sql
SELECT contact_id, updated_at FROM contact_data
```

**Select all contacts who engaged with an email by clicking**

```sql
SELECT c.contact_id, c.updated_at
FROM contact_data as c
JOIN event_data as e ON c.contact_id= e.contact_id WHERE e.event_type = 'clicked'
```

## Upgrade a V1 Segment to V2

### Upgrade a Segment using the Marketing Campaigns user interface

You can manually migrate an existing segment from v1 to v2 from the [Marketing Campaigns user interface](https://mc.sendgrid.com/contacts) by duplicating the segment. The new duplicate will be created using the v2 API.

1. In the Twilio SendGrid app, select **Marketing > Contacts**.
2. Click the action menu to the right of the segment you want to duplicate. A menu will appear.
3. Click **Duplicate**. A detailed view will load where you can rename and modify the segment if needed.
4. Click **Save Segment** to finish the duplication.

You should also delete any segments created using the v1 API once the v2 replacement is created.

1. In the Twilio SendGrid App, select **Marketing > Contacts**.
2. Click the action menu to the right of the segment you want to delete. A menu will appear.
3. Click **Delete This Segment**. A confirmation menu will appear.
4. Click **Delete This Segment** to finish the deletion.

### Upgrade a Segment using the Segmentation v1 and v2 APIs

You can manually migrate an existing v1 segment to v2 using the Segmentation APIs by creating a new v2 segment with the same filtering criteria as an existing v1 segment. For code samples, see the API reference linked in the appropriate steps.

1. Retrieve the ID of the segment you want to duplicate using the [**`GET` List of Segments**](/docs/sendgrid/api-reference/segmenting-contacts/get-list-of-segments) v1 endpoint if you have not done so already.
2. Retrieve the segment you want to duplicate using the [**Get Segment by ID**](/docs/sendgrid/api-reference/segmenting-contacts/get-segment-by-id) v1 endpoint.
3. The segment's response body will include a `query_dsl` string containing a SQL query that will filter contacts to construct the segment. This query can be modified and used to create the same segment with the v2 API.
4. Modify the `query_dsl` string retrieved from your v1 segment to conform to v2 `query_dsl` format. See [**Marketing Campaigns V2 Segmentation Query Reference**](/docs/sendgrid/for-developers/sending-email/marketing-campaigns-v2-segmentation-query-reference), to modify and structure your query.
5. Once your `query_dsl` string is modified to work with the v2 query language, you can pass it to the [**Create Segment**](/docs/sendgrid/api-reference/segmenting-contacts-v2/create-segment) v2 API endpoint, which requires a `query_dsl` string.
6. You will now have a duplicate of your v1 segment.

You should also delete any segments created using the v1 API once the v2 replacement is created.

1. Retrieve the ID of the segment you want to delete using the [**`GET` List of Segments**](/docs/sendgrid/api-reference/segmenting-contacts/get-list-of-segments) v1 endpoint if you have not done so already.
2. Pass the ID of the segment you want to delete as a path parameter to the [**Delete Segment**](/docs/sendgrid/api-reference/segmenting-contacts/delete-segment) v1 endpoint.
3. Your segment will be deleted once the request is processed.