---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/flex/developer/create-a-flex-instance#article
headline: Create a Flex instance programmatically
description: Learn more about authenticating and using the Flex Instances APIs.
url: https://www.twilio.com/docs/flex/developer/create-a-flex-instance
inLanguage: en
dateModified: 2026-08-20T18:09:16.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Create a Flex instance programmatically

This page outlines how to authenticate and get started with the Flex Instances APIs. The Instances API lets you programmatically install Flex for existing Twilio accounts.

## Authentication

Twilio supports HTTP Basic authentication. Include the **Basic Authentication** header, using your API key SID as the username and your API key secret as the password. If a key is compromised or no longer used, revoke it to prevent unauthorized access.

For more information, see [Twilio API requests](/docs/usage/requests-to-twilio).

## Base URL

```bash
https://flex-api.twilio.com
```

## Create a Flex instance

Create a Flex instance by sending a `POST` request to the following endpoint:

```bash
POST "https://flex-api.twilio.com/v2/Instances"
```

### Request body

The following example shows a request to create a Flex instance:

```json
{
   "conversations": {
      "default": true
   }
}
```

| Input                   | Type    | Description                                                                                                                |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `conversations.default` | Boolean | If `true`, the Flex conversation service created during provisioning is set as the account's default conversation service. |

### Response body

A successful request returns a `201 Created` status code and the following response:

```json
{
  "flex_instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "creation-in-progress",
  "date_created": "2016-08-01T22:10:40Z",
  "date_updated": "2016-08-01T22:10:40Z"
}
```

## Get Flex instance

Fetch information about a Flex instance by sending a `GET` request to the following endpoint:

```bash
GET "https://flex-api.twilio.com/v2/Instances/INSTANCE_SID"
```

### Response body

A successful request returns a `200 OK` status code and the following response:

```json
{
  "flex_instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "ready",
  "date_created": "2016-08-01T22:10:40Z",
  "date_updated": "2016-08-01T22:10:40Z"
}
```