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

# Integration API

> Outpost's REST API for managing members programmatically via custom integrations.

<Info>
  The Integration API is available to publications using the **Custom Integration** feature. Email [support@outpost.pub](mailto:support@outpost.pub) to request access. Outpost enables Custom Integrations for your site, and the panel then appears on the Integrations page, where you select **Add new Integration** to create one and copy its API URL and API key.
</Info>

The Outpost Integration API lets you create, read, update, and delete members programmatically. It's designed for connecting external systems (CRMs, form tools, membership platforms) that need to sync member data with Outpost.

## Base URL

All API requests use the integration endpoint:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://your-outpost-domain.com/integration
```

## Authentication

Authenticate using the **Integration key** from your Custom Integration settings. Include it as a Bearer token in the `Authorization` header:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /integration/members/jane@example.com
Authorization: Bearer your_integration_key
Content-Type: application/json
```

Your integration key is found on the **Custom Integrations** panel, under **Integrations and Core Connections → Integrations**, after connecting the integration.

<Warning>
  Store your integration key securely. It provides full access to create, read, update, and delete members on your publication.
</Warning>

## Response format

All responses use a consistent JSON structure:

**Success:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "data": {
    "guid": "abc-123-def",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "is_subscribed": true,
    "note": "Joined via partner form",
    "labels": ["partner", "newsletter"],
    "tier_id": null,
    "status": "free",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  },
  "message": "Member retrieved successfully."
}
```

**Error:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "message": "Member not found."
}
```

## Member fields

| Field           | Type           | Description                                                    |
| --------------- | -------------- | -------------------------------------------------------------- |
| `guid`          | string         | Unique member identifier                                       |
| `email`         | string         | Member's email address                                         |
| `name`          | string         | Full name                                                      |
| `is_subscribed` | boolean        | Whether the member is subscribed to newsletters                |
| `note`          | string         | Notes or description                                           |
| `labels`        | array          | Label names applied to the member                              |
| `tier_id`       | string \| null | Stripe product ID of the member's tier (null for free members) |
| `member_id`     | string \| null | Custom member ID (only when using Custom ID mode)              |
| `status`        | string         | One of: `free`, `paid`, `complimentary`                        |
| `created_at`    | timestamp      | When the member was created                                    |
| `updated_at`    | timestamp      | When the member was last updated                               |

## Integration modes

Custom integrations operate in one of two modes:

**Email mode** (default): Members are identified by email address in all API requests. One member per email.

**Custom ID mode**: Members are identified by a custom ID you provide (e.g., an ID from your external system). This mode optionally allows multiple members to share the same email address.

<Note>
  When duplicate emails are allowed and you create a member whose email already exists, Outpost stores a generated placeholder address (`your-member-id@example.com`) for the new record and sets `is_subscribed` to false, so the duplicate never receives email. Look members up by their custom ID, not by email, in this mode.
</Note>

The mode is configured when you set up the custom integration in Outpost.

## Rate limiting

API requests are limited to **30 requests per minute**. Exceeding this returns a `429 Too Many Requests` response with a `Retry-After` header.

## Endpoints

See [Members API](/api-reference/members) for the full endpoint reference.

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I create paid subscriptions via the API?">
    The API creates free members only. Paid subscriptions require a Stripe checkout flow. You can set a member's `tier_id` to associate them with a tier, but billing is managed through Stripe.
  </Accordion>

  <Accordion title="Does the API sync changes to Ghost?">
    Yes. All member changes made via the API are automatically synced to your connected Ghost publication.
  </Accordion>

  <Accordion title="What's the difference between email mode and custom ID mode?">
    Email mode identifies members by their email address (one member per email). Custom ID mode lets you assign your own identifier to each member, which is useful when syncing with external systems that have their own member IDs. Custom ID mode can optionally allow duplicate emails.
  </Accordion>

  <Accordion title="Is there a list/search endpoint?">
    Not currently. The API supports get, create, update, and delete operations on individual members. For bulk data, use the [Data Export](/features/data-export) feature.
  </Accordion>
</AccordionGroup>