Get started with the REST API

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:

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. 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.