Libraries and HTTP Clients

There are no official Vendaze SDKs. The API follows standard REST and HTTP conventions and works with any HTTP client. The snippets below cover the most common operations in three languages. Copy, adapt, and ship.

All examples assume you have already completed the OAuth flow and have a valid access_token and refresh_token. See Authentication if you have not done that yet.

Node.js

Uses the built-in fetch API (Node.js 18+). No dependencies required.

OAuth token exchange
Refresh access token
Get a person by ID
Create a person
Error handling wrapper

// Exchange an authorization code for tokens
async function exchangeCode({ code, clientId, clientSecret }) {
  const res = await fetch('https://api.vendaze.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      client_id: clientId,
      client_secret: clientSecret,
    }),
  });

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  return res.json();
  // { access_token, refresh_token, token_type, expires_in, workspace_slug }
}

// Refresh an expired access token
async function refreshToken({ refreshToken, clientId, clientSecret }) {
  const res = await fetch('https://api.vendaze.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: clientId,
      client_secret: clientSecret,
    }),
  });

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  return res.json();
}

// Fetch a person by ID
async function getPerson(accessToken, personId) {
  const res = await fetch(
    `https://api.vendaze.com/v1/people/${personId}`,
    { headers: { Authorization: `Bearer ${accessToken}` } }
  );

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  const { data } = await res.json();
  return data;
}

// Create a new contact in the workspace
async function createPerson(accessToken, payload) {
  const res = await fetch('https://api.vendaze.com/v1/people', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    const { error } = await res.json();
    if (error.code === 'validation_error') {
      console.error('Validation failed:', error.fields);
    }
    throw new Error(`${error.code}: ${error.message}`);
  }

  const { data } = await res.json();
  return data;
}

// Usage
const person = await createPerson(accessToken, {
  full_name: 'Ana Costa',
  emails: [{ email: 'ana@company.com', type: 'work' }],
  phones: [{ phone: '+5511999990001', type: 'mobile' }],
  position: 'Head of Sales',
});

// Reusable API client with automatic token refresh
class VendazeClient {
  constructor({ accessToken, refreshToken, clientId, clientSecret, onTokenRefresh }) {
    this.accessToken = accessToken;
    this.refreshToken = refreshToken;
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.onTokenRefresh = onTokenRefresh; // callback to persist new tokens
  }

  async request(path, options = {}) {
    const res = await fetch(`https://api.vendaze.com${path}`, {
      ...options,
      headers: {
        Authorization: `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });

    if (res.status === 401) {
      const { error } = await res.json();
      if (error.code === 'token_expired') {
        await this._refresh();
        return this.request(path, options); // retry once
      }
      throw new Error(`${error.code}: ${error.message}`);
    }

    if (!res.ok) {
      const { error } = await res.json();
      throw new Error(`${error.code}: ${error.message}`);
    }

    if (res.status === 204) return null;
    return res.json();
  }

  async _refresh() {
    const res = await fetch('https://api.vendaze.com/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: this.refreshToken,
        client_id: this.clientId,
        client_secret: this.clientSecret,
      }),
    });

    if (!res.ok) throw new Error('Refresh token expired. User must re-authorize.');

    const tokens = await res.json();
    this.accessToken = tokens.access_token;
    this.refreshToken = tokens.refresh_token;

    if (this.onTokenRefresh) {
      await this.onTokenRefresh(tokens);
    }
  }
}

// Usage
const client = new VendazeClient({
  accessToken: storedAccessToken,
  refreshToken: storedRefreshToken,
  clientId: process.env.VENDAZE_CLIENT_ID,
  clientSecret: process.env.VENDAZE_CLIENT_SECRET,
  onTokenRefresh: async (tokens) => {
    await db.updateTokens(workspaceSlug, tokens);
  },
});

const { data: people } = await client.request('/v1/people/PERSON_UUID');

Python

Uses the httpx library (async). Install with pip install httpx.

OAuth token exchange
Get a person by ID
Create a person
Error handling wrapper

import httpx

async def exchange_code(code: str, client_id: str, client_secret: str) -> dict:
    async with httpx.AsyncClient() as client:
        res = await client.post(
            "https://api.vendaze.com/oauth/token",
            data={
                "grant_type": "authorization_code",
                "code": code,
                "client_id": client_id,
                "client_secret": client_secret,
            },
        )

    res.raise_for_status()
    return res.json()
    # { "access_token": ..., "refresh_token": ..., "workspace_slug": ... }

import httpx

async def get_person(access_token: str, person_id: str) -> dict:
    headers = {"Authorization": f"Bearer {access_token}"}

    async with httpx.AsyncClient() as client:
        res = await client.get(
            f"https://api.vendaze.com/v1/people/{person_id}",
            headers=headers,
        )
        res.raise_for_status()
        return res.json()["data"]

import httpx
import uuid

async def create_person(access_token: str, payload: dict) -> dict:
    async with httpx.AsyncClient() as client:
        res = await client.post(
            "https://api.vendaze.com/v1/people",
            json=payload,
            headers={
                "Authorization": f"Bearer {access_token}",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )

    if res.status_code == 422:
        error = res.json()["error"]
        raise ValueError(f"Validation failed: {error['fields']}")

    res.raise_for_status()
    return res.json()["data"]

# Usage
person = await create_person(access_token, {
    "full_name": "Ana Costa",
    "emails": [{"email": "ana@company.com", "type": "work"}],
    "phones": [{"phone": "+5511999990001", "type": "mobile"}],
    "position": "Head of Sales",
})

import httpx
import uuid
from typing import Callable, Awaitable

class VendazeClient:
    def __init__(
        self,
        access_token: str,
        refresh_token: str,
        client_id: str,
        client_secret: str,
        on_token_refresh: Callable[[dict], Awaitable[None]] | None = None,
    ):
        self.access_token = access_token
        self.refresh_token = refresh_token
        self.client_id = client_id
        self.client_secret = client_secret
        self.on_token_refresh = on_token_refresh

    async def request(self, method: str, path: str, **kwargs) -> dict | None:
        async with httpx.AsyncClient() as client:
            res = await client.request(
                method,
                f"https://api.vendaze.com{path}",
                headers={"Authorization": f"Bearer {self.access_token}"},
                **kwargs,
            )

        if res.status_code == 401:
            error = res.json()["error"]
            if error["code"] == "token_expired":
                await self._refresh()
                return await self.request(method, path, **kwargs)
            raise PermissionError(f"{error['code']}: {error['message']}")

        if res.status_code == 204:
            return None

        res.raise_for_status()
        return res.json()

    async def _refresh(self):
        async with httpx.AsyncClient() as client:
            res = await client.post(
                "https://api.vendaze.com/oauth/token",
                data={
                    "grant_type": "refresh_token",
                    "refresh_token": self.refresh_token,
                    "client_id": self.client_id,
                    "client_secret": self.client_secret,
                },
            )

        if not res.is_success:
            raise PermissionError("Refresh token expired. User must re-authorize.")

        tokens = res.json()
        self.access_token = tokens["access_token"]
        self.refresh_token = tokens["refresh_token"]

        if self.on_token_refresh:
            await self.on_token_refresh(tokens)

Go

Uses the standard library only. No external dependencies.

OAuth token exchange
Get a person by ID
Create a person

package vendaze

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "strings"
)

type TokenResponse struct {
    AccessToken   string `json:"access_token"`
    RefreshToken  string `json:"refresh_token"`
    TokenType     string `json:"token_type"`
    ExpiresIn     int    `json:"expires_in"`
    WorkspaceSlug string `json:"workspace_slug"`
}

func ExchangeCode(code, clientID, clientSecret string) (*TokenResponse, error) {
    form := url.Values{
        "grant_type":    {"authorization_code"},
        "code":          {code},
        "client_id":     {clientID},
        "client_secret": {clientSecret},
    }

    res, err := http.Post(
        "https://api.vendaze.com/oauth/token",
        "application/x-www-form-urlencoded",
        strings.NewReader(form.Encode()),
    )
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    if res.StatusCode != http.StatusOK {
        var errBody struct {
            Error struct {
                Code    string `json:"code"`
                Message string `json:"message"`
            } `json:"error"`
        }
        json.NewDecoder(res.Body).Decode(&errBody)
        return nil, fmt.Errorf("%s: %s", errBody.Error.Code, errBody.Error.Message)
    }

    var tokens TokenResponse
    if err := json.NewDecoder(res.Body).Decode(&tokens); err != nil {
        return nil, err
    }
    return &tokens, nil
}

package vendaze

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type Person struct {
    ID        string `json:"id"`
    FullName  string `json:"full_name"`
    CreatedAt string `json:"created_at"`
}

func GetPerson(accessToken string, personID string) (*Person, error) {
    client := &http.Client{}

    req, _ := http.NewRequest("GET",
        fmt.Sprintf("https://api.vendaze.com/v1/people/%s", personID),
        nil,
    )
    req.Header.Set("Authorization", "Bearer "+accessToken)

    res, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    if res.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("unexpected status: %d", res.StatusCode)
    }

    var body struct {
        Data Person `json:"data"`
    }
    if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
        return nil, err
    }

    return &body.Data, nil
}

package vendaze

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"

    "github.com/google/uuid"
)

type CreatePersonRequest struct {
    FullName string          `json:"full_name"`
    Emails   []ContactEmail  `json:"emails,omitempty"`
    Phones   []ContactPhone  `json:"phones,omitempty"`
    Position string          `json:"position,omitempty"`
}

type ContactEmail struct {
    Email string `json:"email"`
    Type  string `json:"type,omitempty"`
}

type ContactPhone struct {
    Phone string `json:"phone"`
    Type  string `json:"type,omitempty"`
}

func CreatePerson(accessToken string, payload CreatePersonRequest) (*Person, error) {
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", "https://api.vendaze.com/v1/people", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+accessToken)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Idempotency-Key", uuid.New().String())

    res, err := (&http.Client{}).Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()

    if res.StatusCode != http.StatusCreated {
        var errBody struct {
            Error struct {
                Code    string            `json:"code"`
                Message string            `json:"message"`
                Fields  map[string]string `json:"fields,omitempty"`
            } `json:"error"`
        }
        json.NewDecoder(res.Body).Decode(&errBody)
        return nil, fmt.Errorf("%s: %s", errBody.Error.Code, errBody.Error.Message)
    }

    var result struct {
        Data Person `json:"data"`
    }
    if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
        return nil, err
    }
    return &result.Data, nil
}

Community resources

No official SDKs exist yet. If you build a client library for Vendaze, open a pull request on the vendaze/vendaze-api repository to have it listed here.

Overview

Getting Started

Using the API

Best Practices

Node.js

Python

Go

Community resources

​Node.js

​Python

​Go

​Community resources

Node.js

Python

Go

Community resources