Kenmerken

Je CRM heeft eigen id's voor het werk dat het aan Schedulinq geeft: een deal, een lead, een campagne. Stuur ze mee als metadata — in het dashboard heten ze kenmerken — en Schedulinq bewaart ze op de uitnodiging of afspraak, kopieert ze naar wat daaruit volgt, en geeft ze terug in elk antwoord en elke webhook. Zo herkent je CRM bij welke lead een boeking hoort, zonder eerst een id van Schedulinq op te slaan.

{
  "metadata": {
    "dealId": "D-123",
    "campaignId": "C-42"
  }
}

Je geeft ze mee als je iets aanmaakt:

• een planningslink (POST /api/v1/planning-links) — de afspraken ervan krijgen ze;
• een uitnodiging (POST /api/v1/invitations) — en elke afspraak die eruit wordt geboekt;
• een uitnodiging voor een teamlid (POST /api/v1/users) — ze blijven op die uitnodiging.

Ze worden één keer geschreven. Niets — niet de API, niet een beheerder in het dashboard — kan ze daarna nog veranderen.

De regels

Een verzoek dat een regel breekt, wordt in zijn geheel geweigerd met errors.api.validationFailed. Alle fouten staan in één keer in errors[], elk met field en code:

Een geweigerde sleutel wordt getoond, niet herhaald: in field wordt elk teken buiten A-Z a-z 0-9 _ een ?, en een sleutel van meer dan 40 tekens wordt afgekapt met ….

Waar ze mee naartoe gaan

Kenmerken worden gekopieerd, nooit opnieuw ingetypt. Ze gaan mee:

• van een uitnodiging naar elke afspraak die ermee wordt geboekt, ook als de klant meerdere diensten tegelijk boekt;
• van een planningslink naar de afspraken die ermee worden gemaakt, één of een reeks;
• van een afspraak naar de nieuwe afspraak als de klant die zelf verzet;
• van een afspraak naar de uitnodiging die een teamlid met Verzetten stuurt, en van daar naar de afspraak die de klant boekt;
• van een uitnodiging voor een teamlid naar de webhook colleague.activated zodra die is geaccepteerd. Het teamlid zelf krijgt ze niet: één koper kan uit veel campagnes komen.

Een afspraak die in het dashboard is gemaakt zonder planningslink, een uitnodiging die een beheerder verstuurt en de uitnodigingen van een abonnement beginnen zonder kenmerken. Een afspraak bewerken verandert ze nooit.

Zoeken op waarde

Zoek een afspraak of uitnodiging op met je eigen id:

curl "https://api.schedulinq.com/api/v1/appointments?metadata[dealId]=D-123" \
  -H "Authorization: Bearer $SCHEDULINQ_API_KEY"

GET /api/v1/appointments en GET /api/v1/invitations vragen minstens één metadata[<key>]=<value> (zonder: errors.validation.metadataFilterRequired). Een filter zoekt de waarde precies; bij meerdere filters moeten ze allemaal kloppen. De haken mogen zo worden meegestuurd of als %5B en %5D. De details, en de andere filters, staan in de referentie.

Wie ze ziet

• Je team. Iedereen die de afspraak of uitnodiging in Schedulinq kan openen, ziet de kenmerken — ook een teamlid met een rol die alleen de eigen afspraken ziet.
• De zoekvelden. Het afspraken- en het uitnodigingenoverzicht vinden een waarde.
• Logboeken. Bij het opzoeken staat de waarde in de URL, en webservers bewaren URL's in hun logboeken.
• Niemand kan ze verbeteren of wissen vanuit het dashboard.

Zet er dus geen persoonsgegevens en geen geheimen in, en niets commercieel gevoeligs dat een andere koper niet mag zien: een deal-id, niet de waarde van de deal. Moet een waarde toch weg, neem dan contact op met support.

In het dashboard

• De afspraakpagina en de uitnodigingspagina tonen een blok Kenmerken dat je alleen kunt lezen, met één regel per sleutel, op volgorde van sleutel. Het staat er alleen als er kenmerken zijn.
• Een openstaande uitnodiging voor een teamlid toont ze in haar venster op de Team-pagina.
• Een afspraak bewerken verandert ze nooit.
• Het zoekveld van het afsprakenoverzicht vindt een waarde vanaf drie tekens. Een kortere id vind je via het uitnodigingenoverzicht, of met het precieze zoeken van de API hierboven.

Bij elke webhook

Elke gebeurtenis over een afspraak of uitnodiging bevat de metadata ervan, {} als er geen zijn, en colleague.activated bevat die van de uitnodiging. Zo kan je webhook-ontvanger een gebeurtenis aan je eigen record koppelen zonder iets op te zoeken. Zie Webhook-gebeurtenissen.

Veelgestelde vragen

Kan een beheerder kenmerken aanpassen?

Nee. Het zijn de verwijzingen van je CRM, en een aangepast deal-id zou de koppeling van je CRM met de afspraak breken. Het dashboard toont ze, en meer niet.

Kan ik het telefoonnummer van een klant erin zetten?

Liever niet. Kenmerken zijn zichtbaar voor teamleden en gaan mee in elke webhook. Bewaar de gegevens van de klant in je eigen CRM, en geef Schedulinq alleen je id ervoor.

Kan ik kenmerken toevoegen aan een afspraak die al bestaat?

Nee. Ze worden meegegeven als de planningslink of uitnodiging wordt gemaakt, en van daaruit gekopieerd.

Waarom wordt mijn numerieke id geweigerd?

Waarden zijn tekst. Stuur "dealId": "123", niet "dealId": 123.