--- title: "Get started with the REST API" description: "Create a personal access token with the right scopes, or register an OAuth app, and read campaigns, leads and lists from your own systems." url: https://scratcher.io/help/developers/rest-api language: en --- 1. [Help center](https://scratcher.io/help) 2. [API, webhooks and MCP](https://scratcher.io/help/developers) 3. Get started with the REST API # Get started with the REST API Create a personal access token with the right scopes, or register an OAuth app, and read campaigns, leads and lists from your own systems. The Scratcher REST API lets your own systems read your campaigns, leads and lists, add and update leads, and manage products and placements. This article is for the developer who sets it up. The API is part of the plans that include **Webhooks & API** (Basic and up). On other plans the buttons to create tokens and apps are locked. ## Create a personal access token A personal access token is the quickest way to call the API from your own scripts and systems. 1. Go to **Settings** > **API** (under **Developers**). 2. Under **Personal access tokens**, click **Create personal access token**. The dialog says "Generate a token to authenticate API requests." 3. Give it a **Name** you will recognise later, such as "Data warehouse". 4. Under **Scopes**, choose what the token may do (see below). **Select all** picks every scope. Give the token only the access it needs. 5. Click **Save**. You see "Your access token has been created". 6. Copy the token under **Secret**. "Save the secret above, as this is the only time you will see it." Store it safely, for example in a password manager. 7. Click **Close**. A token belongs to your user. It can reach every Scratcher account you are a member of, with the scopes you chose. ## Scopes - `read:campaigns` (**View campaigns**): list and read campaigns - `read:lists` (**View lists**): list and read lead lists - `read:leads` (**View leads**): read leads - `write:leads` (**Write leads**): create, update and delete leads in a list - `read:placements` (**View placements**): read placements - `write:placements` (**Write placements**): create, update and delete placements - `read:products` (**View products**): read products - `write:products` (**Write products**): create, update and delete products To read the leads of a campaign, the token needs both `read:campaigns` and `read:leads`. Creating and changing placements also needs **Embed / URL** on your plan. ## Revoke a token Click the token in the list to open **Show personal access token**. It shows the **Name** and **Scopes**. Click **Revoke** and confirm ("Are you sure you want to delete this token? This cannot be undone!"). Anything that uses the token stops working right away. ## Make a request The base URL is `https://platform.scratcher.io/api/v1/`. Send the token in the `Authorization` header, and ask for JSON: ```text curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" ``` ## Main endpoints - `GET /me`: the user the token belongs to - `GET /accounts`: the accounts you have access to. Use the account id in the other calls. - `GET /accounts/{account}/campaigns` and `/campaigns/{campaign}`: your campaigns - `GET /accounts/{account}/campaigns/{campaign}/leads`: the leads of a campaign, newest first, with their fields, accepted consents and, for winners, the prize and code - `GET /accounts/{account}/lists` and `/lists/{list}`: your lead lists - `/accounts/{account}/lists/{list}/leads`: the leads of a list. `GET` to read, `POST` to create, `PUT` to update and `DELETE` to delete. A lead has an `email`, a `phone_number` and an optional `custom_token`. - `/accounts/{account}/products`: products (`GET`, `POST`, `PUT`, `DELETE`) - `/accounts/{account}/placements`: placements (`GET`, `POST`, `PUT`, `DELETE`) Lists are paged: add `?page=2` and so on. You can only reach accounts you are a member of; other account ids return an error. ## Limits You can make 60 requests per minute per user. If you go over, the API answers with status 429; wait a moment and try again. ## API reference The full reference, with all fields, filters, examples and a Postman collection, is in the [API reference documentation](https://platform.scratcher.io/docs/index.html). The **API reference** button at the top of **Settings** > **API** links to it too. ## Build an app with OAuth If you build an app that other Scratcher users connect to their own account, register an OAuth app instead of using a personal token. 1. Go to **Settings** > **API**. Under **My apps**, click **Create app** ("Register an OAuth application for the API."). 2. Fill in the **Application name** (users see it when they approve your app) and the **Redirect URI** (where users are sent back after approving). 3. Click **Save**. You see "Your app has been created!" with the **Client ID** and **Client secret**. 4. Copy the client secret now: "Save the client secret above, as this is the only time you will see it." Click **Continue**. Your app sends users to `https://platform.scratcher.io/oauth/authorize` with your client ID, redirect URI and the scopes it needs. The user logs in to Scratcher and sees an **Authorization request**: "This application will be able to:" followed by the scopes. They click **Authorize** or **Cancel**. Your app then exchanges the code for tokens at `https://platform.scratcher.io/oauth/token`. - Access tokens from OAuth last two months. Refresh tokens last three months; use them to get a new access token. - To change the name or redirect URI, click the app under **My apps**, change it and click **Save** ("Your settings have been saved"). "You cannot view your secret afterwards." - **Delete app** removes the app, and every user's connection to it stops working: "Are you sure you want to delete this app? This cannot be undone!" ## Apps you have approved **Authorized apps** lists the apps you have given access to your account, such as Zapier, with the scopes they have. Click **Revoke** to take the access away. ## Who can use the API? The **API** page is shown to users with the role **Owner**, **Admin** or **Manager**. A token can never do more than the user who created it. API, webhooks and MCP - [Get started with the REST API](https://scratcher.io/help/developers/rest-api) - [Send data to your systems with webhooks](https://scratcher.io/help/developers/webhooks) - [Scratcher MCP for your own AI tools](https://scratcher.io/help/developers/mcp) ## Related articles - [Send data to your systems with webhooks](https://scratcher.io/help/developers/webhooks): Get a request to your own URL when someone signs up, takes part or wins, with a signed payload, basic auth, a custom payload and a log of every delivery. - [Scratcher MCP for your own AI tools](https://scratcher.io/help/developers/mcp): Soon you can connect Claude, ChatGPT and other AI tools to Scratcher with MCP. Here is what we know so far, and what you can use today. - [Connect 8,000+ apps with Zapier](https://scratcher.io/help/integrations/zapier): Send new sign-ups from Scratcher to Google Sheets, Slack, your CRM or thousands of other apps with Zapier. ## Still need help? Real people are here to help. If you already use Scratcher, the quickest way is the chat inside the platform. - **[Chat with us](https://platform.scratcher.io/login)** Log in and click the chat button in the bottom-right corner. Rex answers right away, and our team is a click away. - **[Book a meeting](https://scratcher.io/book-a-meeting)** A free 30-minute video call with our team: a tour, campaign ideas or help with your setup. - **[Email us](mailto:contact@scratcher.io)** Write to contact@scratcher.io and we will get back to you.