Overview
Welcome to the Vendasta API Gateway. This service gives partners programmatic access to the platform.
The primary integration surface is the Vendasta APIs. Every service is defined as a Protocol Buffers contract, and the HTTP API you call is generated from that contract — so the reference documentation, the request and response shapes, and the service itself never drift apart.
Use the Vendasta APIs for all new integrations.
The Legacy APIs are the previous generation of hand-written REST endpoints. They remain fully supported for existing integrations, and some capabilities are still only available there — but they are not where new work should start.
Stable​
The platform is rapidly changing but you should not have to update your integration every few months. Our services are designed to continually evolve instead of making you upgrade versions. Each field and method has a status assigned to it. We aim to provide 2 years of notice before removal so you have time to migrate.
Built on standards​
We can all be more efficient when we follow the same way of doing things. Services are defined using Protocol Buffers, an open standard for describing typed contracts, and exposed over HTTP with JSON request and response bodies.
Because the contract is machine readable, the API reference is generated from it rather than maintained by hand. The OpenAPI document for each service is published alongside its documentation, so you can generate a client, drive a test tool, or import it into Postman without transcribing anything.
Self documenting​
Every field, type, and method is declared in the contract the documentation is generated from. Each service's reference page includes the full request and response schema for every method, plus a built-in client for trying calls against your own account.
Conventions​
The Legacy APIs use a different set, documented in Legacy API conventions. Filters, paging, errors, and localization all differ between the two.
Authentication​
Every request requires an OAuth2 bearer token issued by the API Gateway, sent in the Authorization header.
Authorization: Bearer <access_token>
Tokens are scoped. A method requires at least one of the scopes listed on its reference page, not all of them. Learn to create them
Errors​
They happen. It is a fact of life but we don't think they should be hard to solve.
When a call fails you receive an HTTP error status and a body with three fields:
| Field | Meaning |
|---|---|
code | Numeric gRPC status code identifying the class of failure |
message | Human readable description of what went wrong |
details | Optional array of structured entries, each tagged with an @type, carrying machine readable specifics |
Check code first to decide how to react, then read details for the specifics you can act on programmatically. message is intended for humans and may change.
{
"code": 3,
"message": "standard__email is required",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "standard__email",
"description": "Value is required when no other identifying field is provided."
}
]
}
]
}
The code values you are most likely to handle:
code | Status | Typical cause |
|---|---|---|
| 3 | INVALID_ARGUMENT | The request was malformed or failed validation |
| 5 | NOT_FOUND | The record or resource does not exist |
| 6 | ALREADY_EXISTS | A uniqueness constraint would be violated |
| 7 | PERMISSION_DENIED | The token is valid but lacks the required scope or access |
| 16 | UNAUTHENTICATED | The token is missing, malformed, or expired |
The Legacy APIs return a different shape, an errors array of JSON:API error objects. See Legacy API conventions.
Filters​
Nearly all methods are POST, and filtering is expressed as fields on the request body rather than query parameters. Each method's reference page shows which fields are filterable and how they combine.
How much filtering is available varies by service. CRM exposes a full grammar with operators and AND/OR groups; most services accept a flat set of optional fields. The two GET methods (/v1beta/widgets and /v1/forms/has-enterprise-api-key) take their parameters in the query string instead.
The Legacy APIs filter with bracketed query parameters. See Legacy API conventions.
Paging​
List methods return results a page at a time, using a pageSize and a cursor on the request and returning a nextCursor and hasMore on the response.
The cursor records your position in the result set, not your query, so every request must repeat the filters, search, and sort you sent on the first call. Sending only the cursor returns a different, unfiltered result set with a 200.
See Paging for a worked example and the per-service variations.
Dates & times​
Dates are formatted according to RFC-3339 which is an extension of ISO 8601.
| Type | Form | Example |
|---|---|---|
| Date, hour, minute and second in UTC | YYYY-MM-DDTHH:MM:SSTZD | 2020-10-28T10:37:23Z |
| Date, hour and minute in Saskatoon (UTC-6) | YYYY-MM-DDTHH:MMTZD | 2020-10-28T04:37-06:00 |
| Date | YYYY-MM-DD | 2001-12-25 |
Offsets are accepted on input. Timestamps in Vendasta API responses are normalized to UTC and returned with a Z suffix.