Call the API yourself
Outcomes
A token is the proof every call carries
Every call to the platform carries a token, and the token is what says both who is asking and what they are allowed to ask for. Get one and the API stops being a wall.
This step is where most builder tracks lose people, because the traditional route is to create a service account, generate a key pair, and write code that signs a request before anything happens at all. There is a shorter way in, and it produces a real call against your own data in a few minutes.
You need your partner ID, and the account group ID of the test account you have been building in. Your partner ID sits in the top left of Partner Center, in the header that reads #YourName (ABC): it is the short code in the parentheses. The account group ID is the AG- segment of the Business App address bar.
Generate one for yourself
You are here: developers.vendasta.com, the developer documentation.
The Generate Token button in the top navigation opens a form that mints a short-lived token for you. It logs you in through Vendasta in a popup window, so the token it hands back carries your own access and nothing more.
Labmint a read-only token
Go to Generate Token in the top navigation.
The token is now saved to your browser, which is what makes the next two calls a matter of editing one value on a reference page.
Ask for exactly what the job needs
A scope is a single permission, and a token carries only the ones you asked for when you generated it. Both scopes above end in :read, which is deliberate: a read-only token cannot change anything while you are learning what the calls return. Both calls are sent as POST even though they only read, which is how this gateway works; the scope is what decides what a call may do, not the method.
That discipline is worth keeping past this step. Request the narrowest scopes that do the job, and what an integration is able to do stays obvious to whoever looks at it next year.
Two errors tell you which half is wrong, and they are worth recognising on sight:
| What comes back | What it means |
|---|---|
UNAUTHENTICATED | The token is missing, malformed, or expired. Generate a new one. |
PERMISSION_DENIED | The token is valid, but it does not carry the scope this call requires. Generate a new one with that scope added. |
Your first call reads, and changes nothing
The first call is a read against your own CRM: it returns the field schema, which is the list of fields your contacts actually have, including any you added yourself. It is a good first call because it cannot change anything while you are getting your bearings.
Lablist your CRM's contact fields
Go to the API reference, under CRM → CRMFieldSchemaService → List Field Schema. There are two CRM sections in the reference; take the one under Vendasta APIs rather than Legacy APIs.
Find your own lead
The second call goes to the test account you have been building in, and returns the contacts on it. One of them is the lead your AI Employee captured when you first proved booking and lead capture worked.
You need that account's ID. Open the account in Business App and read the address bar: the ID is the AG- segment, in /account/location/AG-XXXXXXXXXX/.
Labread back the contact your build captured
Go to CRM → CRMService → List Contacts in the API reference.
That is the whole point of this step. The conversation, the booking, the CRM record, and the API are one system, and you have now touched it from both ends.
When you go to production
What changes when this stops being you clicking and starts being your integration running is the identity, not the ideas.
Your code authenticates as a service account: an identity that belongs to the integration rather than to a person, created in Partner Center and carrying a key pair you download once. It exchanges that key for a token the same way the generator just did for you, and asks for the same kind of scopes. Tokens expire, so production code requests a fresh one rather than storing it. Writes work the same way reads do, with one addition worth knowing before you send any: a contact write is an upsert, matched on a key you choose, which is what keeps you from creating a second copy of a contact you already have.
The developer documentation covers all of it, and the generator stays useful for exploring long after your integration has its own credentials.
Generate one more token, this time with only crm.schema:read, and run List Contacts again. Read the error you get back. Recognising PERMISSION_DENIED on sight is worth more than any amount of reading about scopes.
Knowledge Check
Three quick questions on scopes, reading the two common errors, and what changes in production.