---
title: Subscribers
description: Manage subscribers.
---

# Subscribers

Manage subscribers.

## [GET /subscribers](/api-reference/subscribers#tag/subscribers/GET/subscribers)

List subscribers

List all subscribers.

Will return all subscribers the requester has access to.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Query parameters

- `customerIds` (`array of string`, optional) — Filter by customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.
- `subscriptionIds` (`array of string`, optional) — The unique identifier of the subscription to filter by.
- `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return.
- `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor.

### Responses

#### 200

A list of subscribers.

Type: `object`

- `items` (`array of SubscriberListItem`, required)
  - `subscriberId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The unique identifier of the subscriber.
  - `name` (`string`, required, example John Doe) — The full name of the subscriber.
  - `email` (`string`, optional, email, example john.doe@example.com) — Optional email address of the subscriber.
  - `address` (`object`, optional) — The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
    - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
    - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
    - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
    - `city` (`string`, required, example Natick) — The city or municipality of the address.
    - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').
    - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
    - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
    - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
    - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
  - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer the subscriber belongs to.
  - `subscriptionIds` (`array of string`, optional) — List of subscriptions ids associated with the subscriber. Typically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions.
  - `createdAt` (`string`, optional, date-time, example 2024-01-10T08:00:00Z) — Date and time when the subscriber was created.
  - `updatedAt` (`string`, optional, date-time, example 2024-01-15T10:30:00Z) — Date and time when the subscriber was last updated.
- `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page.
  - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results.

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/subscribers \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

## [GET /subscribers/{subscriberId}](/api-reference/subscribers#tag/subscribers/GET/subscribers/{subscriberId})

Get subscriber

Retrieve detailed information about a specific subscriber using its unique identifier.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

- `subscriberId` (`string`, required) — The unique identifier of the subscriber.

### Responses

#### 200

A subscriber object.

Type: [Subscriber](/api-reference/models.md#models/Subscriber)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/subscribers/SUBSCRIBER_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

## [PUT /subscribers/{subscriberId}](/api-reference/subscribers#tag/subscribers/PUT/subscribers/{subscriberId})

Update subscriber

Update the details of an existing subscriber.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

- `subscriberId` (`string`, required) — The unique identifier of the subscriber.

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code.

### Request body (required)

Type: `object`

- `name` (`string`, optional, example John Doe) — The full name of the subscriber.
- `email` (`string`, optional, email, example john.doe@example.com) — The email address of the subscriber.
- `contactNumber` (`string`, optional, phone, example +15551234567) — A phone number for reaching the subscriber, separate from the number their subscription provides.
- `address` (`object`, optional) — The address of the subscriber. In the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services. Changing it schedules an update with the network operator, so the new address becomes the one emergency services receive. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.
  - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number.
  - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number.
  - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc.
  - `city` (`string`, required, example Natick) — The city or municipality of the address.
  - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').
  - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).
  - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).
  - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).
  - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address.
- `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
  - `*` (`string`, optional)

### Responses

#### 200

Subscriber updated successfully.

Type: [Subscriber](/api-reference/models.md#models/Subscriber)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/subscribers/SUBSCRIBER_ID \
  --request PUT \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "contactNumber": "+15551234567",
  "address": {
    "street": "500 S Main St",
    "street1": "string",
    "street2": "Apt 1",
    "city": "Natick",
    "zip": "01701",
    "country": "US",
    "state": "CA",
    "region": "Ontario",
    "attention": "John Doe"
  },
  "metadata": {
    "propertyName": "string"
  }
}'
```