First Request

This guide covers the complete end-to-end flow: registering the app, authorizing a user, and retrieving workspace contacts. By the end you will have a working access_token and a real API response in your terminal.

Prerequisites

A Vendaze account with at least one active workspace (create one free if you don’t have one)
curl available in your terminal

1. Register the app

Send a registration request with your app name, contact email, redirect URIs, and the scopes you need. This endpoint is public and requires no authentication.

curl -X POST https://api.vendaze.com/v1/auth/register-app \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "My Test Integration",
    "email": "dev@yourapp.com",
    "redirect_uris": ["https://yourapp.com/oauth/callback"],
    "scopes": ["people:read", "companies:read", "deals:read"]
  }'

Check your inbox. You will receive an email with a secure link to view your client_id and client_secret. Open the link within 15 minutes. The link expires and cannot be reopened. Copy both values to a safe place before continuing.

2. Build the authorization URL

Build the authorization URL and open it in your browser. Replace YOUR_CLIENT_ID with the value you received.

https://api.vendaze.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/oauth/callback&response_type=code&state=random-csrf-token-123

The state parameter should be a random string you generate. In production, store it in the session and verify it on the callback to prevent CSRF attacks.

3. Authorize and get the code

After opening the URL in your browser, you will:

Log in with your Vendaze account
Select a workspace to connect
Review the requested scopes
Click “Authorize”

After authorizing, the browser redirects to:

https://yourapp.com/oauth/callback?code=AUTH_CODE_HERE&state=random-csrf-token-123

Copy the code value from the URL. It expires in 10 minutes and can only be used once.

4. Exchange the code for tokens

Send the code from your server. This request must never be made from the browser.

curl -X POST https://api.vendaze.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE_HERE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "workspace_slug": "acme-corp"
}

What just happened

Field	What it means
`access_token`	A signed JWT that authorizes requests to the workspace. Include it as `Authorization: Bearer <token>` in every API call. Expires in 1 hour.
`refresh_token`	A long-lived token used to get a new `access_token` without user interaction. Valid for 60 days from last use. Store this encrypted in your DB.
`token_type`	Always `Bearer`. Tells you how to send the token in the `Authorization` header.
`expires_in`	Seconds until the `access_token` expires. Always 3600. Use this to schedule proactive refreshes.
`workspace_slug`	The slug of the workspace the user authorized. Use this to identify which workspace this token belongs to in your own data model.

Store both tokens securely on your server. Never expose them in client-side code or URLs.

5. Retrieve a contact

Use the access_token to make your first real API call. Fetch a specific person by their UUID:

curl https://api.vendaze.com/v1/people/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "Ana Costa",
    "emails": [{ "email": "ana@company.com", "type": "work" }],
    "phones": [{ "phone": "+5511999990001", "type": "mobile" }],
    "company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "company": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "full_name": "Acme Corp" },
    "position": "Head of Sales",
    "score": 0,
    "tags": [],
    "lists": [],
    "custom_fields": [],
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-05-20T14:22:00Z"
  }
}

The response includes the person’s data with embedded company, tags, lists, and custom_fields.

What to explore next

Custom Fields

Read and write workspace-defined custom fields on people, companies, and deals.

Errors

Understand error codes and build resilient error handling.

Webhooks

Receive real-time notifications when events occur in workspace data.

API Reference

Full endpoint reference with request and response schemas.

Overview

Getting Started

Using the API

Best Practices

Prerequisites

1. Register the app

2. Build the authorization URL

3. Authorize and get the code

4. Exchange the code for tokens

What just happened

5. Retrieve a contact

What to explore next

Custom Fields

Errors

Webhooks

API Reference

​Prerequisites

​1. Register the app

​2. Build the authorization URL

​3. Authorize and get the code

​4. Exchange the code for tokens

​What just happened

​5. Retrieve a contact

​What to explore next

Custom Fields

Errors

Webhooks

API Reference

Prerequisites

1. Register the app

2. Build the authorization URL

3. Authorize and get the code

4. Exchange the code for tokens

What just happened

5. Retrieve a contact

What to explore next