> Calendly developer docs. For page Markdown, append .md to any URL.
> Index: https://developer.calendly.com/llms.txt
> API catalog: https://developer.calendly.com/.well-known/api-catalog
> OpenAPI: https://developer.calendly.com/openapi/calendly-api.yaml
> OAuth authorization server: https://calendly.com/.well-known/oauth-authorization-server
> MCP protected resource: https://mcp.calendly.com/.well-known/oauth-protected-resource
> Scheduling MCP endpoint: https://mcp.calendly.com
> Docs search MCP: https://developer.calendly.com/_mcp/server

# Create Contact List

POST https://api.calendly.com/contact_lists
Content-Type: application/json

Creates a List (`static_list`) and, optionally, adds contacts to it. You cannot create a View with this API.

Adding the initial contacts is not atomic with creating the List. The List is created first. Then the contacts are added. `membership_result` shows the result for the contacts: contacts that were invalid or whose write failed are listed by URI. To retry failed contacts, send them to Add Contacts to Static List. That operation is idempotent.

A List name that is taken returns 409. The name match ignores case, accents, and leading and trailing spaces. The limit is 25 Lists and Views for each user, including Views that a CSV import creates.

If the request returns a 500 error or times out, the List may still exist. Before you retry, use List Contact Lists to check for the List. Then send any missing contacts to Add Contacts to Static List, which is safe to repeat. A retry of this request with the same name returns 409.

> `contacts:write`

Reference: https://developer.calendly.com/api-docs/calendly-api/contacts/create-contact-list

## Authentication

- `Authorization` header (bearer token, required) — OAuth 2.0
- `Authorization` header (bearer token, required) — Personal Access Token

## Request

### Body (application/json)

This endpoint expects a CreateContactListRequest.

- `name` (string, required) — The name of the List. Leading and trailing whitespace is removed. The result must contain 1 to 255 characters. It must not match the name of another List. The match ignores case, accents, and leading and trailing spaces.
- `contacts` (list of string, optional) — Contacts to add to the new List, as contact URIs. Maximum 500. A contact that appears more than once is added once.

## Response

### 201

Created

- `resource` (ContactListCreated, required) — The created `static_list`, with the result of adding the initial contacts.

## Errors

### 400 Bad Request Error

Request is not valid

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

### 401 Unauthorized Error

Cannot authenticate caller

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

### 403 Forbidden Error

Permission Denied or insufficient scope

- `Create-contact-listRequestForbiddenError`
  - ContactListsError: ContactListsError
  - InsufficientScopeError: InsufficientScopeError

### 409 Conflict Error

The List name is taken, or the user has reached the limit of 25 Lists and Views

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

### 429 Too Many Requests Error

Too Many Requests

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

### 500 Internal Server Error

An error has occurred on the server

- `title` (enum, required)
  - Allowed values: `Internal Server Error`
- `message` (enum, required)
  - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.`
- `details` (list of ErrorResponseDetailsItem, optional)

## Types

### ContactListCreated

The created `static_list`, with the result of adding the initial contacts.

- `uri` (string, required) — Canonical reference (unique identifier) for the contact list.
- `name` (string, required) — The name of the List.
- `type` (enum, required) — Always `static_list`. You cannot create a View with this API.
  - Allowed values: `static_list`
- `contact_count` (integer, required) — The number of contacts on the List after the initial contacts are added.
- `membership_result` (ContactListMembershipAddResult, required) — The result of adding contacts to a List. This is a result payload, not an addressable resource. URIs are listed only for contacts that were not added.

### ErrorResponseDetailsItem

- `message` (string, required)
- `parameter` (string, optional)
- `code` (string, optional)

### ContactListsError

Permission Denied

- `title` (enum, required)
  - Allowed values: `Permission Denied`
- `message` (enum, required)
  - Allowed values: `Please upgrade to a paid Calendly account.`, `You do not have permission to access this resource.`

### InsufficientScopeError

Caller does not have required oauth scopes

- `title` (enum, required)
  - Allowed values: `Insufficient scope`
- `message` (enum, required)
  - Allowed values: `This operation requires the scopes listed in the 'required_scopes' array.`
- `required_scopes` (list of string, required)

### ContactListMembershipAddResult

The result of adding contacts to a List. This is a result payload, not an addressable resource. URIs are listed only for contacts that were not added.

- `added` (integer, required) — The number of contacts that were added. This includes contacts that were on the List before, were removed, and are now added again.
- `already_present` (integer, required) — The number of contacts that were already on the List. Nothing changed for them.
- `invalid` (integer, required) — The number of contacts that do not exist or that the user cannot access. The other contacts were still processed.
- `failed` (integer, required) — The number of contacts whose write failed. You can safely retry them.
- `already_present_contacts` (list of string, required) — The URIs of the contacts that were already on the List.
- `invalid_contacts` (list of string, required) — The URIs of the invalid contacts.
- `failed_contacts` (list of string, required) — The URIs of the contacts whose write failed. Send them again to retry.

## Examples

### With contacts

**Request**

```json
{
  "name": "VIP Contacts",
  "contacts": [
    "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
    "https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB"
  ]
}
```

**Response**

```json
{
  "resource": {
    "uri": "https://api.calendly.com/contact_lists/AAAAAAAAAAAAAAAA",
    "name": "VIP Contacts",
    "type": "static_list",
    "contact_count": 1,
    "membership_result": {
      "added": 1,
      "already_present": 0,
      "invalid": 1,
      "failed": 0,
      "already_present_contacts": [],
      "invalid_contacts": [
        "https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB"
      ],
      "failed_contacts": []
    }
  }
}
```

**SDK Code**

```python With contacts
import requests

url = "https://api.calendly.com/contact_lists"

payload = {
    "name": "VIP Contacts",
    "contacts": ["https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA", "https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript With contacts
const url = 'https://api.calendly.com/contact_lists';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"VIP Contacts","contacts":["https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA","https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go With contacts
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.calendly.com/contact_lists"

	payload := strings.NewReader("{\n  \"name\": \"VIP Contacts\",\n  \"contacts\": [\n    \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n    \"https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby With contacts
require 'uri'
require 'net/http'

url = URI("https://api.calendly.com/contact_lists")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"VIP Contacts\",\n  \"contacts\": [\n    \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n    \"https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java With contacts
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.calendly.com/contact_lists")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"VIP Contacts\",\n  \"contacts\": [\n    \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n    \"https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB\"\n  ]\n}")
  .asString();
```

```php With contacts
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.calendly.com/contact_lists', [
  'body' => '{
  "name": "VIP Contacts",
  "contacts": [
    "https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA",
    "https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp With contacts
using RestSharp;

var client = new RestClient("https://api.calendly.com/contact_lists");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"VIP Contacts\",\n  \"contacts\": [\n    \"https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA\",\n    \"https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift With contacts
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "VIP Contacts",
  "contacts": ["https://api.calendly.com/contacts/AAAAAAAAAAAAAAAA", "https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/contact_lists")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Name only

**Request**

```json
{
  "name": "VIP Contacts"
}
```

**Response**

```json
{
  "resource": {
    "uri": "https://api.calendly.com/contact_lists/AAAAAAAAAAAAAAAA",
    "name": "VIP Contacts",
    "type": "static_list",
    "contact_count": 1,
    "membership_result": {
      "added": 1,
      "already_present": 0,
      "invalid": 1,
      "failed": 0,
      "already_present_contacts": [],
      "invalid_contacts": [
        "https://api.calendly.com/contacts/BBBBBBBBBBBBBBBB"
      ],
      "failed_contacts": []
    }
  }
}
```

**SDK Code**

```python Name only
import requests

url = "https://api.calendly.com/contact_lists"

payload = { "name": "VIP Contacts" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Name only
const url = 'https://api.calendly.com/contact_lists';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"VIP Contacts"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Name only
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.calendly.com/contact_lists"

	payload := strings.NewReader("{\n  \"name\": \"VIP Contacts\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Name only
require 'uri'
require 'net/http'

url = URI("https://api.calendly.com/contact_lists")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"VIP Contacts\"\n}"

response = http.request(request)
puts response.read_body
```

```java Name only
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.calendly.com/contact_lists")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"VIP Contacts\"\n}")
  .asString();
```

```php Name only
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.calendly.com/contact_lists', [
  'body' => '{
  "name": "VIP Contacts"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Name only
using RestSharp;

var client = new RestClient("https://api.calendly.com/contact_lists");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"VIP Contacts\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Name only
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["name": "VIP Contacts"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/contact_lists")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```