Request Format

The Vendasta APIs are defined as Protocol Buffers contracts and exposed over HTTPS with JSON request and response bodies. You call them with ordinary HTTP tooling — there is no special client library or binary encoding to deal with.

Anatomy of a request

Every method is a POST to a path derived from the service and method name, under the /grpc prefix:

POST https://prod.apigateway.co/grpc/v1/crm/contact/create

Part	Meaning
https://prod.apigateway.co	Environment host — see Environments
/grpc	Prefix for all Vendasta API calls
/v1/crm/contact/create	The service and method being called

Requests carry a bearer token and a JSON body:

curl -X POST 'https://prod.apigateway.co/grpc/v1/crm/contact/create' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "namespace": "AG-EXAMPLE",
    "crmObject": {
      "fields": [
        { "fieldId": "standard__email", "stringValue": "jane@example.com" }
      ]
    }
  }'

The body is a JSON representation of the method's request message. Field names use lowerCamelCase. The exact shape for any method — every field, its type, and whether it is required — is on that method's page in the API reference, generated from the contract itself.

Environments

Environment	Host
Production	https://prod.apigateway.co
Demo	https://demo.apigateway.co

Use Demo while building. Data and credentials are not shared between environments — a token issued for one will not work against the other.

Responses

A successful call returns 200 with the method's response message as JSON. Methods that return nothing return an empty object:

{}

Failures return an HTTP error status and a body with code, message, and optional details. See Errors for the shape and the status codes you are most likely to handle.

Generating a client

Because each service publishes an OpenAPI document, you do not have to hand-write HTTP calls. Every reference page has a Download link for its OpenAPI spec, which you can feed to:

• an OpenAPI generator, to produce a typed client in your language
• Postman or Insomnia, to import the full set of methods for exploration
• your IDE, for request completion and validation

Debugging

Because requests and responses are plain JSON over HTTPS, anything you already use for HTTP works — curl, your language's HTTP client, Postman, or a proxy such as Charles or mitmproxy. There is no binary payload to decode.

When a call does not behave as expected:

1. Check the status code and code field. 16 (UNAUTHENTICATED) means the token is missing or expired; 7 (PERMISSION_DENIED) means it is valid but lacks the scope the method requires.
2. Read details. Validation failures name the specific field rather than only saying the request was invalid.
3. Compare your body to the reference page. A field at the wrong nesting level is the most common cause of an otherwise puzzling INVALID_ARGUMENT.
4. Try the call from the reference page. Each method has a built-in client you can run against your own account, which removes your own code from the equation.

Legacy APIs

The Legacy APIs use a different format — JSON:API over REST, with resources addressed by path and filtering and paging expressed as query parameters. If you are maintaining an existing integration against those endpoints, the conventions described on this page do not apply to them.