> For a complete page index, fetch https://developer.close.com/llms.txt

# Create a membership

POST https://api.close.com/api/v1/membership/
Content-Type: application/json

Ensures an active membership for the given email will be provisioned.

- If the user already exists, they will be added to the requestor's organization.
- If it doesn't exist, a new user will be provisioned.

This request requires "Manage Organization" permissions.

As a security precaution, this operation requires the organization to have the
"Restrict new users to emails from these domains" setting enabled, and the new
member's email address must belong to one of its verified domains.

Reference: https://developer.close.com/api/resources/memberships/create

## Authentication

- `Authorization` header (basic auth, required) — Use your API key as the username and leave the password empty.
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects a CreateMembership.

- `email` (string, required)
- `role_id` (string, required) — One of `superuser`, `user`, or `restricteduser` for the corresponding predefined role, or the ID of a custom [Role](https://developer.close.com/api/resources/roles). The role must not grant the `manage_organization` permission.

## Response

### 200

Successful response

- `auto_record_calls` (enum, required)
  - Allowed values: `enabled`, `disabled`, `unset`
- `default_caller_id` (string, required, nullable)
- `default_caller_id_mode` (enum, required) — How a caller's outbound number is chosen. Fixed uses a single configured number; Auto lets Close select the best number per call/SMS (Managed by Close Caller ID).
  - Allowed values: `fixed`, `auto`
- `hangup_recording_url` (string, required, nullable)
- `id` (string, required)
- `may_workflows_impersonate` (boolean, required)
- `onboarding_status` (string, required, nullable)
- `organization_id` (string, required)
- `primary_personal_number` (string, required, nullable)
- `role_id` (string, required)
- `track_email_opens` (boolean, required)
- `user_id` (string, required)
- `permissions_granted` (list of enum, optional)
  - Allowed values: `manage_organization`, `manage_own_api_keys`, `manage_others_api_keys`, `manage_customizations`, `manage_oauth_apps`, `manage_group_numbers`, `manage_team_smart_views`, `manage_team_email_templates`, `manage_email_sequences`, `ai_enrich`, `bulk_import`, `bulk_email`, `bulk_enrich`, `bulk_sequence_subscriptions`, `bulk_edit`, `bulk_delete`, `export`, `merge_leads`, `delete_leads`, `manage_others_opportunities`, `delete_own_opportunities`, `manage_others_tasks`, `delete_own_tasks`, `view_voice_agents`, `manage_voice_agents`, `ai_chat`, `manage_chloe_call_tasks`, `view_custom_agents`, `manage_custom_agents`, `manage_others_activities`, `delete_own_activities`, `calling`, `call_coach_listen`, `call_coach_barge`, `view_all_leads`, `manage_web_forms`
- `role` (string, optional)
- `user` (MembershipUser, optional) — A user nested in a membership response.
- `user_email` (string, optional)
- `user_first_name` (string, optional, nullable)
- `user_full_name` (string, optional, nullable)
- `user_google_profile_image_url` (string, optional, nullable)
- `user_image` (string, optional, nullable)
- `user_last_name` (string, optional, nullable)
- `user_phone` (string, optional, nullable) — Phone number in E.164 format.
- `user_phone_formatted` (string, optional, nullable)
- `user_totp_auth_state` (enum, optional)
  - Allowed values: `enabled`, `disabled`, `blocked`

## Errors

### 400 Bad Request Error

Invalid membership data, including an email address that does not belong to one of the organization's verified domains.

- `any`

### 401 Unauthorized Error

Unauthorized

- `any`

### 403 Forbidden Error

Membership creation is not permitted because the requestor cannot manage the organization, the verified domain restriction is disabled, or the requested role grants the `manage_organization` permission.

- `any`

### 404 Not Found Error

Not found

- `any`

## Types

### MembershipUser

A user nested in a membership response.

- `email` (string, required)
- `first_name` (string, required, nullable)
- `full_name` (string, required, nullable)
- `google_profile_image_url` (string, required, nullable)
- `id` (string, required)
- `image` (string, required, nullable)
- `last_name` (string, required, nullable)
- `totp_auth_state` (enum, required)
  - Allowed values: `enabled`, `disabled`, `blocked`

## Examples

**Request**

```json
{
  "email": "john@salesteam.com",
  "role_id": "user"
}
```

**Response**

```json
{
  "auto_record_calls": "unset",
  "default_caller_id": null,
  "default_caller_id_mode": "fixed",
  "hangup_recording_url": null,
  "id": "memb_JPCqDJq0AmoZFhemXAWrWk9327DqfJgUF2VGPMOL4Lp",
  "may_workflows_impersonate": false,
  "onboarding_status": "in-progress",
  "organization_id": "orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH",
  "primary_personal_number": null,
  "role_id": "user",
  "track_email_opens": true,
  "user_id": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
  "permissions_granted": [
    "bulk_email",
    "bulk_import",
    "bulk_sequence_subscriptions",
    "calling",
    "delete_leads",
    "delete_own_activities",
    "delete_own_opportunities",
    "delete_own_tasks",
    "manage_others_activities",
    "manage_others_opportunities",
    "manage_others_tasks",
    "merge_leads",
    "view_all_leads"
  ],
  "role": "user"
}
```

**SDK Code**

```python memberships_create_example
import requests

url = "https://api.close.com/api/v1/membership/"

payload = {
    "email": "john@salesteam.com",
    "role_id": "user"
}
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, auth=("<CLOSE_API_KEY>", ""))

print(response.json())
```

```javascript memberships_create_example
const url = 'https://api.close.com/api/v1/membership/';
const credentials = btoa("<CLOSE_API_KEY>:");

const options = {
  method: 'POST',
  headers: {Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json'},
  body: '{"email":"john@salesteam.com","role_id":"user"}'
};

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

```go memberships_create_example
package main

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

func main() {

	url := "https://api.close.com/api/v1/membership/"

	payload := strings.NewReader("{\n  \"email\": \"john@salesteam.com\",\n  \"role_id\": \"user\"\n}")

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

	req.SetBasicAuth("<CLOSE_API_KEY>", "")
	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 memberships_create_example
require 'uri'
require 'net/http'

url = URI("https://api.close.com/api/v1/membership/")

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

request = Net::HTTP::Post.new(url)
request.basic_auth("<CLOSE_API_KEY>", "")
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"john@salesteam.com\",\n  \"role_id\": \"user\"\n}"

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

```java memberships_create_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.close.com/api/v1/membership/")
  .basicAuth("<CLOSE_API_KEY>", "")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"john@salesteam.com\",\n  \"role_id\": \"user\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.close.com/api/v1/membership/', [
  'body' => '{
  "email": "john@salesteam.com",
  "role_id": "user"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
    'auth' => ['<CLOSE_API_KEY>', ''],
]);

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

```csharp memberships_create_example
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.close.com/api/v1/membership/");
client.Authenticator = new HttpBasicAuthenticator("<CLOSE_API_KEY>", "");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"email\": \"john@salesteam.com\",\n  \"role_id\": \"user\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```