---
title: "REST APIを使い始める"
description: "適切なスコープを持つパーソナルアクセストークンを作成するか、OAuthアプリを登録して、自社のシステムからキャンペーン、リード、リストを読み取りましょう。"
url: https://scratcher.io/ja/help/developers/rest-api
language: ja
---

1. [ヘルプセンター](https://scratcher.io/ja/help)
2. [API、Webhook、MCP](https://scratcher.io/ja/help/developers)
3. REST APIを使い始める

# REST APIを使い始める

適切なスコープを持つパーソナルアクセストークンを作成するか、OAuthアプリを登録して、自社のシステムからキャンペーン、リード、リストを読み取りましょう。

Scratcher REST APIを使うと、自社のシステムからキャンペーン、リード、リストの読み取り、リードの追加・更新、商品やプレースメントの管理が行えます。この記事は、APIを設定する開発者向けです。

APIは **Webhooks & API** を含むプラン（Basic以上）でご利用いただけます。それ以外のプランでは、トークンやアプリを作成するボタンはロックされています。

## パーソナルアクセストークンを作成する

パーソナルアクセストークンは、自社のスクリプトやシステムからAPIを呼び出す最も手軽な方法です。

1. **設定** > **API**（**開発者**の下）に移動します。
2. **パーソナルアクセストークン**で、**パーソナルアクセストークンを作成**をクリックします。ダイアログに「APIリクエストを認証するためのトークンを生成します。」と表示されます。
3. 後で見分けやすい**名前**（例：「データウェアハウス」）を付けます。
4. **スコープ**で、トークンに許可する操作を選択します（下記参照）。**すべて選択**ですべてのスコープが選ばれます。トークンには必要最小限のアクセス権のみを付与してください。
5. **保存**をクリックします。「アクセストークンが作成されました」と表示されます。
6. **シークレット**の下に表示されたトークンをコピーします。「上記のシークレットを保存してください。表示されるのはこの一度だけです。」パスワードマネージャーなど、安全な場所に保管してください。
7. **閉じる**をクリックします。

トークンはユーザーに紐づきます。選択したスコープの範囲で、あなたがメンバーになっているすべてのScratcherアカウントにアクセスできます。

## スコープ

- `read:campaigns`（**キャンペーンを表示**）：キャンペーンの一覧表示と読み取り
- `read:lists`（**リストを表示**）：リードリストの一覧表示と読み取り
- `read:leads`（**リードを表示**）：リードの読み取り
- `write:leads`（**リードを書き込み**）：リスト内のリードの作成、更新、削除
- `read:placements`（**プレースメントを表示**）：プレースメントの読み取り
- `write:placements`（**プレースメントを書き込み**）：プレースメントの作成、更新、削除
- `read:products`（**商品を表示**）：商品の読み取り
- `write:products`（**商品を書き込み**）：商品の作成、更新、削除

キャンペーンのリードを読み取るには、トークンに `read:campaigns` と `read:leads` の両方が必要です。プレースメントの作成・変更には、プランに **Embed / URL** が含まれている必要もあります。

## トークンを無効化する

一覧でトークンをクリックすると、**パーソナルアクセストークンを表示**が開き、**名前**と**スコープ**が表示されます。**無効化**をクリックして確認します（「このトークンを削除してもよろしいですか？この操作は元に戻せません！」）。そのトークンを使用しているものはすべて、直ちに動作しなくなります。

## リクエストを送信する

ベースURLは `https://platform.scratcher.io/api/v1/` です。トークンを `Authorization` ヘッダーで送信し、JSONを指定します。

```text
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
```

## 主なエンドポイント

- `GET /me`：トークンの所有ユーザー
- `GET /accounts`：アクセス可能なアカウント。他の呼び出しではこのアカウントIDを使用します。
- `GET /accounts/{account}/campaigns` と `/campaigns/{campaign}`：キャンペーン
- `GET /accounts/{account}/campaigns/{campaign}/leads`：キャンペーンのリード（新しい順）。各フィールド、同意済みの項目、当選者の場合は賞品とコードを含みます
- `GET /accounts/{account}/lists` と `/lists/{list}`：リードリスト
- `/accounts/{account}/lists/{list}/leads`：リストのリード。`GET` で読み取り、`POST` で作成、`PUT` で更新、`DELETE` で削除します。リードには `email`、`phone_number`、および任意の `custom_token` があります。
- `/accounts/{account}/products`：商品（`GET`、`POST`、`PUT`、`DELETE`）
- `/accounts/{account}/placements`：プレースメント（`GET`、`POST`、`PUT`、`DELETE`）

一覧はページ分割されています。`?page=2` などを付けて取得してください。アクセスできるのはメンバーになっているアカウントのみで、それ以外のアカウントIDではエラーが返されます。

## 制限

リクエストはユーザーごとに1分あたり60回まで送信できます。上限を超えるとAPIはステータス429を返します。少し待ってから再試行してください。

## APIリファレンス

すべてのフィールド、フィルター、サンプル、Postmanコレクションを含む完全なリファレンスは、[APIリファレンスドキュメント](https://platform.scratcher.io/docs/index.html)をご覧ください。**設定** > **API** 上部の **APIリファレンス** ボタンからもアクセスできます。

## OAuthでアプリを構築する

他のScratcherユーザーが自分のアカウントに接続するアプリを構築する場合は、パーソナルトークンではなくOAuthアプリを登録してください。

1. **設定** > **API** に移動します。**マイアプリ**で**アプリを作成**をクリックします（「API用のOAuthアプリケーションを登録します。」）。
2. **アプリケーション名**（ユーザーがアプリを承認する際に表示されます）と**リダイレクトURI**（承認後にユーザーが戻される先）を入力します。
3. **保存**をクリックします。「アプリが作成されました！」と表示され、**クライアントID**と**クライアントシークレット**が示されます。
4. ここでクライアントシークレットをコピーしてください。「上記のクライアントシークレットを保存してください。表示されるのはこの一度だけです。」**続行**をクリックします。

アプリは、クライアントID、リダイレクトURI、必要なスコープを付けてユーザーを `https://platform.scratcher.io/oauth/authorize` に送ります。ユーザーはScratcherにログインし、**認可リクエスト**を確認します。「このアプリケーションは次のことができるようになります：」の後にスコープが表示されます。ユーザーは**認可**または**キャンセル**をクリックします。その後、アプリは `https://platform.scratcher.io/oauth/token` でコードをトークンと交換します。

- OAuthのアクセストークンの有効期間は2か月です。リフレッシュトークンの有効期間は3か月で、新しいアクセストークンの取得に使用します。
- 名前やリダイレクトURIを変更するには、**マイアプリ**でアプリをクリックして変更し、**保存**をクリックします（「設定が保存されました」）。「シークレットは後から表示できません。」
- **アプリを削除**するとアプリが削除され、すべてのユーザーの接続が動作しなくなります。「このアプリを削除してもよろしいですか？この操作は元に戻せません！」

## 承認済みのアプリ

**認可済みアプリ**には、Zapierなど、アカウントへのアクセスを許可したアプリと、そのスコープが一覧表示されます。**無効化**をクリックするとアクセスを取り消せます。

## APIを利用できるユーザー

**API** ページは、**オーナー**、**管理者**、**マネージャー**のロールを持つユーザーに表示されます。トークンが作成したユーザーの権限を超える操作を行うことはできません。

API、Webhook、MCP

- [REST APIを使い始める](https://scratcher.io/ja/help/developers/rest-api)
- [Webhookで自社システムにデータを送信](https://scratcher.io/ja/help/developers/webhooks)
- [自社のAIツールで使えるScratcher MCP](https://scratcher.io/ja/help/developers/mcp)

さらに学ぶ

## 関連記事

- [Webhookで自社システムにデータを送信](https://scratcher.io/ja/help/developers/webhooks): 登録・参加・当選のたびに指定したURLへリクエストを送信。署名付きペイロード、Basic認証、カスタムペイロード、全配信のログに対応しています。
- [自社のAIツールで使えるScratcher MCP](https://scratcher.io/ja/help/developers/mcp): MCPを使って、Claude、ChatGPTなどのAIツールをScratcherアカウントに接続できます。設定方法と、AIでできることをご紹介します。
- [Zapierで8,000以上のアプリと連携](https://scratcher.io/ja/help/integrations/zapier): Zapierを使えば、Scratcherの新規登録データをGoogleスプレッドシート、Slack、CRMなど数千のアプリに送信できます。

お困りですか？

## まだお困りですか？

担当者がサポートします。すでに Scratcher をご利用の場合は、プラットフォーム内のチャットが最も早い方法です。

- **[チャットで相談](https://platform.scratcher.io/ja/login)**

    ログインして右下のチャットボタンをクリックしてください。Rex がすぐに回答し、チームにもワンクリックでつながります。
- **[ミーティングを予約](https://scratcher.io/ja/book-a-meeting)**

    チームとの 30 分の無料ビデオ通話：製品ツアー、キャンペーンのアイデア、設定のサポート。
- **[メールで問い合わせ](mailto:contact@scratcher.io)**

    contact@scratcher.io までご連絡いただければ、折り返しご返信します。
