Authenticate and make your first API call
Outcomes
Your code, reaching in
This is the other direction of an integration: your own code reaching into the platform, to push a contact into the CRM or pull data back out. It starts where every real integration starts, at the wall of authentication: proving to the platform that your code is allowed to act. Nothing here is hard once the pieces have names.
A service account is your code's identity
When a person signs in, they prove who they are. Your code needs the same thing, and it uses a service account: an identity that belongs to your integration rather than to a person. You create one in the platform, and from then on your code acts as that account.
A service account can hold many permissions, but it does not use them all at once. It asks for the specific ones it needs, when it needs them. Those permissions are called scopes.
Scopes: ask for exactly what the job needs
A scope is a single permission, like reading contacts or writing contacts. When your code gets its token, it names the scopes that call requires, and nothing more. Pushing a contact needs a contact-write scope; reading one back needs only a read scope, and most products offer a read-only variant for exactly that.
The discipline worth building early: request the narrowest scopes that do the job. It is safer, and it makes what your integration can do obvious to anyone who looks later.
One honest note. The service-account screen inside the platform is spare on its own. You read it next to the API reference at developers.vendasta.com, which lists the real scope names. Pairing the screen with the reference is how this work is meant to be done, not a sign you are missing something.
Get a token
An access token is the proof your code carries on every call. You generate it from your service account, naming the scopes you want. If the names are right, the token comes back ready to use. If one is wrong, the response tells you which name it did not recognize, so you correct it and try again. Keep the token where the rest of your code cannot leak it, the same way you would treat any password.
Your first call: the contact upsert
The most common first call a builder makes is pushing a contact into the CRM, and the platform makes it one call, not two. It is an upsert: create the contact if it is new, update it if it already exists. You do not look first and branch; you send the contact and let the platform decide.
What decides "already exists" is a match key. Email is the common choice, with phone as a fallback. Choose your match key deliberately, because it is what keeps you from creating a second copy of a contact you already have.
Two behaviors are worth knowing before you send anything:
- By default, an update only fills fields that are empty. A value already in the record stays put.
- When you do want to replace a value, you mark that field to overwrite. Reach for it deliberately, because overwrite is also how good data gets erased by a stale import.
Phone numbers are forgiving: send them in whatever format you have, and the platform normalizes them on the way in, so what lands stays consistent.
The exact request, field by field, lives in the CRM API reference. This step is the shape of it, so that reference reads like confirmation instead of a foreign language.
In a sandbox account, generate a token with a contact-write scope and upsert one contact by email. Then send the same contact again with a different phone number, and check the record: did it match the contact you already had instead of creating a second one, and did your overwrite choice behave the way you expected? That one loop is authentication, scopes, and upsert semantics learned in a single sitting.
Knowledge Check
Three quick questions on scopes, the upsert, and how records match and update.