> ## Documentation Index
> Fetch the complete documentation index at: https://loops.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts API examples

> Copy/paste code examples for managing contacts with the Loops API, CLI, and SDKs, including create, update, find, and delete requests with sample payloads.

## Create a contact

[API reference](https://loops.so/docs/api-reference/create-contact.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#create)

```bash CLI theme={"dark"}
loops contacts create \
  --email test@example.com \
  --first-name John \
  --last-name Doe
```

```js JavaScript theme={"dark"}
const response = await fetch("https://app.loops.so/api/v1/contacts/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "test@example.com",
    firstName: "John",
    lastName: "Doe",
  }),
});

const data = await response.json();
```

```js JavaScript SDK theme={"dark"}
import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.createContact({
  email: "test@example.com",
  properties: {
    firstName: "John",
    lastName: "Doe",
  },
});
```

```php PHP SDK theme={"dark"}
use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->create(
  email: 'test@example.com',
  properties: [
    'firstName' => 'John',
    'lastName' => 'Doe',
  ],
);
```

```ruby Ruby SDK theme={"dark"}
response = LoopsSdk::Contacts.create(
  email: "test@example.com",
  properties: {
    firstName: "John",
    lastName: "Doe",
  },
)
```

```python Python theme={"dark"}
import requests

response = requests.post(
    "https://app.loops.so/api/v1/contacts/create",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "firstName": "John",
        "lastName": "Doe"
    }
)
```

## Create a contact and add them to a mailing list

[API reference](https://loops.so/docs/api-reference/create-contact.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#create)

```bash CLI {5} theme={"dark"}
loops contacts create \
  --email test@example.com \
  --first-name John \
  --last-name Doe \
  --list "<mailing-list-id>=true"
```

```js JavaScript {11-13} theme={"dark"}
const response = await fetch("https://app.loops.so/api/v1/contacts/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "test@example.com",
    firstName: "John",
    lastName: "Doe",
    mailingLists: {
      "<mailing-list-id>": true
    },
  }),
});

const data = await response.json();
```

```js JavaScript SDK {10-12,17} theme={"dark"}
import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const properties = {
  firstName: "John",
  lastName: "Doe",
};

const mailingLists = {
  "<mailing-list-id>": true,
};

const response = await loops.createContact({
  email: "test@example.com",
  properties,
  mailingLists,
});
```

```php PHP SDK {11-13} theme={"dark"}
use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->create(
  email: 'test@example.com',
  properties: [
    'firstName' => 'John',
    'lastName' => 'Doe',
  ],
  mailing_lists: [
    '<mailing-list-id>' => TRUE,
  ],
);
```

```ruby Ruby SDK {7-9} theme={"dark"}
response = LoopsSdk::Contacts.create(
  email: "test@example.com",
  properties: {
    firstName: "John",
    lastName: "Doe",
  },
  mailing_lists: {
    "<mailing-list-id>": true,
  },
)
```

```python Python {13-15} theme={"dark"}
import requests

response = requests.post(
    "https://app.loops.so/api/v1/contacts/create",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "mailingLists": {
            "<mailing-list-id>": True
        }
    }
)
```

## Update a contact

When updating a contact you must provide an `email` or `userId` value to identify the contact.

> [!TIP]
>
> You can use the "update" endpoint to update or create contacts. If the provided email or user ID does not exist, a new contact will be created.

[API reference](https://loops.so/docs/api-reference/update-contact.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#update)

```bash CLI theme={"dark"}
loops contacts update \
  --email test@example.com \
  --prop planName=Pro
```

```js JavaScript theme={"dark"}
const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
    planName: "Pro",
  }),
});

const data = await response.json();
```

```js JavaScript SDK theme={"dark"}
import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact({
  email: "test@example.com",
  properties: {
    planName: "Pro",
  },
});
```

```php PHP SDK theme={"dark"}
use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  properties: [
    'planName' => 'Pro',
  ],
);
```

```ruby Ruby SDK theme={"dark"}
response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  properties: {
    planName: "Pro",
  },
)
```

```python Python theme={"dark"}
import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "planName": "Pro"
    }
)
```

## Update a contact's email address

For this, the contact will need to already have a `userId` value set.

[API reference](https://loops.so/docs/api-reference/update-contact.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#update)

```bash CLI theme={"dark"}
loops contacts update \
  --user-id 12345 \
  --email test@example.com
```

```js JavaScript theme={"dark"}
const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    userId: "12345",
    email: "test@example.com",
  }),
});

const data = await response.json();
```

```js JavaScript SDK theme={"dark"}
import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact({
  userId: "12345",
  email: "test@example.com",
});
```

```php PHP SDK theme={"dark"}
use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  properties: [
    'userId' => '12345',
  ],
);
```

```ruby Ruby SDK theme={"dark"}
response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  properties: {
    userId: "12345",
  },
)
```

```python Python theme={"dark"}
import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "userId": "12345"
    }
)
```

## Subscribe a contact to a mailing list

[API reference](https://loops.so/docs/api-reference/update-contact.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#update)

```bash CLI theme={"dark"}
loops contacts update \
  --email test@example.com \
  --list "<mailing-list-id>=true"
```

```js JavaScript theme={"dark"}
const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
    mailingLists: {
      "<mailing-list-id>": true
    },
  }),
});

const data = await response.json();
```

```js JavaScript SDK theme={"dark"}
import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact({
  email: "test@example.com",
  mailingLists: {
    "<mailing-list-id>": true,
  },
});
```

```php PHP SDK theme={"dark"}
use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  mailing_lists: [
    '<mailing-list-id>' => TRUE,
  ],
);
```

```ruby Ruby SDK theme={"dark"}
response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  mailing_lists: {
    "<mailing-list-id>" => true,
  },
)
```

```python Python theme={"dark"}
import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "mailingLists": {
            "<mailing-list-id>": True
        }
    }
)
```

## Unsubscribe a contact from a mailing list

This removes a contact from a specific mailing list. [See below](#unsubscribe-a-contact) to see how to fully unsubscribe a contact.

Use `false` to unsubscribe a contact from a mailing list.

[API reference](https://loops.so/docs/api-reference/update-contact.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#update)

```bash CLI {4} theme={"dark"}
loops contacts update \
  --email test@example.com \
  --list "<mailing-list-id>=false"
```

```js JavaScript {9-11} theme={"dark"}
const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
    mailingLists: {
      "<mailing-list-id>": false
    },
  }),
});

const data = await response.json();
```

```js JavaScript SDK {7-9} theme={"dark"}
import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact({
  email: "test@example.com",
  mailingLists: {
    "<mailing-list-id>": false,
  },
});
```

```php PHP SDK {7-9} theme={"dark"}
use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  mailing_lists: [
    '<mailing-list-id>' => FALSE,
  ],
);
```

```ruby Ruby SDK {3-5} theme={"dark"}
response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  mailing_lists: {
    "<mailing-list-id>" => false,
  },
)
```

```python Python {11-13} theme={"dark"}
import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "mailingLists": {
            "<mailing-list-id>": False
        }
    }
)
```

## Unsubscribe a contact

Set `subscribed` to `false` to unsubscribe a contact. The contact will no longer receive campaign or workflow emails, but will remain listed in your audience.

[API reference](https://loops.so/docs/api-reference/update-contact.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#update)

```bash CLI {3} theme={"dark"}
loops contacts update \
  --email test@example.com \
  --subscribed false
```

```js JavaScript {9} theme={"dark"}
const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
    subscribed: false,
  }),
});

const data = await response.json();
```

```js JavaScript SDK {7-9} theme={"dark"}
import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact({
  email: "test@example.com",
  properties: {
    subscribed: false,
  },
});
```

```php PHP SDK {7} theme={"dark"}
use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  subscribed: false,
);
```

```ruby Ruby SDK {3} theme={"dark"}
response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  subscribed: false,
)
```

```python Python {11} theme={"dark"}
import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "subscribed": False
    }
)
```

## Delete a contact

You can delete contacts by email or user ID.

[API reference](https://loops.so/docs/api-reference/delete-contact.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#delete)

```bash CLI theme={"dark"}
loops contacts delete --email test@example.com
```

```js JavaScript theme={"dark"}
const response = await fetch("https://app.loops.so/api/v1/contacts/delete", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
  }),
});

const data = await response.json();
```

```js JavaScript SDK theme={"dark"}
import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.deleteContact({
  email: "test@example.com",
});
```

```php PHP SDK theme={"dark"}
use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->delete(
  email: 'test@example.com',
);
```

```ruby Ruby SDK theme={"dark"}
response = LoopsSdk::Contacts.delete(
  email: "test@example.com",
)
```

```python Python theme={"dark"}
import requests

response = requests.post(
    "https://app.loops.so/api/v1/contacts/delete",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
    }
)
```

## Check contact suppression status

[API reference](https://loops.so/docs/api-reference/check-contact-suppression.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#suppression-check)

```bash CLI theme={"dark"}
loops contacts suppression check --email test@example.com
```

```js JavaScript theme={"dark"}
const params = new URLSearchParams({ email: "test@example.com" });

const response = await fetch(
  `https://app.loops.so/api/v1/contacts/suppression?${params.toString()}`,
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer <your-api-key>",
    },
  },
);

const data = await response.json();
```

```python Python theme={"dark"}
import requests

response = requests.get(
    "https://app.loops.so/api/v1/contacts/suppression",
    headers={
        "Authorization": "Bearer <your-api-key>",
    },
    params={
        "email": "test@example.com",
    },
)

data = response.json()
```

## Remove suppression for a contact

[API reference](https://loops.so/docs/api-reference/remove-contact-suppression.md)\
[CLI reference](https://loops.so/docs/cli/contacts.md#suppression-remove)

```bash CLI theme={"dark"}
loops contacts suppression remove --email test@example.com
```

```js JavaScript theme={"dark"}
const params = new URLSearchParams({ email: "test@example.com" });

const response = await fetch(
  `https://app.loops.so/api/v1/contacts/suppression?${params.toString()}`,
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer <your-api-key>",
    },
  },
);

const data = await response.json();
```

```python Python theme={"dark"}
import requests

response = requests.delete(
    "https://app.loops.so/api/v1/contacts/suppression",
    headers={
        "Authorization": "Bearer <your-api-key>",
    },
    params={
        "email": "test@example.com",
    },
)

data = response.json()
```


## Related topics

- [API Examples](https://loops.so/docs/api-reference/examples.md)
- [Events API examples](https://loops.so/docs/api-reference/examples/events.md)
- [Workflows API examples](https://loops.so/docs/api-reference/examples/workflows.md)
- [Campaigns API examples](https://loops.so/docs/api-reference/examples/campaigns.md)
- [Add and update contacts with the Loops API](https://loops.so/docs/add-users/loops-api.md)