Skip to main content
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:
  1. Log in with your Vendaze account
  2. Select a workspace to connect
  3. Review the requested scopes
  4. 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

FieldWhat it means
access_tokenA signed JWT that authorizes requests to the workspace. Include it as Authorization: Bearer <token> in every API call. Expires in 1 hour.
refresh_tokenA 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_typeAlways Bearer. Tells you how to send the token in the Authorization header.
expires_inSeconds until the access_token expires. Always 3600. Use this to schedule proactive refreshes.
workspace_slugThe 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",
    "ranking": 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.