Aan de slag met de REST API

Met de REST API van Scratcher kunnen je eigen systemen je campagnes, leads en lijsten uitlezen, leads toevoegen en bijwerken, en producten beheren. Dit artikel is voor de ontwikkelaar die het instelt. De API zit in het Basic-abonnement en hoger.

Een toegangstoken aanmaken

1. Ga naar Instellingen > API (onder Ontwikkelaars).
2. Klik onder Persoonlijke toegangstokens op Persoonlijk toegangstoken aanmaken.
3. Geef het een Naam, zoals "Datawarehouse", en kies de Scopes die het nodig heeft. Geef het alleen de toegang die het nodig heeft.
4. Klik op Opslaan en kopieer het token onder Secret. Je ziet het maar één keer, dus bewaar het veilig, bijvoorbeeld in een wachtwoordmanager.

Een token hoort bij jouw gebruiker en heeft toegang tot elk account waarvan je lid bent. Wil je de toegang intrekken, open dan het token en klik op Intrekken.

Scopes

• read:campaigns: campagnes uitlezen
• read:lists: leadlijsten uitlezen
• read:leads en write:leads: leads uitlezen, aanmaken, bijwerken en verwijderen
• read:placements en write:placements: plaatsingen uitlezen en beheren
• read:products en write:products: producten uitlezen en beheren

Een verzoek doen

De basis-URL is https://platform.scratcher.io/api/v1/. Stuur het token mee in de header Authorization:

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

Belangrijkste endpoints

• GET /me: de gebruiker bij wie het token hoort
• GET /accounts: de accounts waartoe je toegang hebt
• GET /accounts/{account}/campaigns en /campaigns/{campaign}: je campagnes
• GET /accounts/{account}/campaigns/{campaign}/leads: de leads van een campagne, met prijzen, codes en gegeven toestemmingen
• GET /accounts/{account}/lists en /lists/{list}/leads: leadlijsten en hun leads, plus POST, PUT en DELETE om leads te beheren
• /accounts/{account}/products: producten
• /accounts/{account}/placements: plaatsingen

Resultaten worden gepagineerd met ?page=. De limiet is 60 verzoeken per minuut per gebruiker.

De volledige referentie, met voorbeelden en een Postman-collectie, vind je in de API-referentiedocumentatie. De knop API-referentie in het platform linkt er ook naartoe.

OAuth-apps

Bouw je een app waarmee andere Scratcher-gebruikers koppelen, registreer die dan onder Mijn apps > App aanmaken met een Naam van de applicatie en Redirect-URI. Je krijgt een Client-ID en Client secret. De secret wordt maar één keer getoond. Apps die mensen hebben goedgekeurd, staan onder Geautoriseerde apps, waar ze kunnen worden ingetrokken.