Skip to main content

​
1. Base URL

All examples use the production public API: 
https://api.vzaps.com

​
2. Have your credentials ready

  • A JWT (Authorization: Bearer ...) for instance and billing endpoints, including POST /instances/list. Integrators obtain a JWT with POST /token using client_token and client_secret (Security in the app); the web UI still signs in with email and password.
  • X-Client-Token for server-to-server integrations and token-authenticated calls (must match the account token).
  • X-Instance-Token to operate a specific instance without a JWT.
curl -X POST "https://api.vzaps.com/token" \
  -H "Content-Type: application/json" \
  -d '{"client_token":"YOUR_CLIENT_TOKEN","client_secret":"YOUR_CLIENT_SECRET"}'
For server-to-server flows, keep client_token, client_secret, and the instance token in a secure environment. Do not expose these values in public front ends.

​
3. Create the instance

Use PUT /instances/create to create the instance and get the instance token. 
curl -X PUT "https://api.vzaps.com/instances/create" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My instance",
    "webhook": "https://customer.example.com/webhooks/vzaps",
    "events_subscribe": ["Message", "Connected", "Disconnected"],
    "reject_calls": false,
    "auto_read_messages": false
  }'
The response includes, among other fields, id, token, url, billing_status, and cycle dates.

​
4. Subscribe or confirm billing

Call POST /instances/{id}/subscribe with the instance owner Authorization: Bearer <jwt>. The default API flow is direct: the subscription is created and charged to the default credit card on the Stripe customer. To rely on that response, add the card first (for example in the VZaps app under Billing / payment). Typical calls use an empty body {}: that is the default path to create the subscription against the default payment method. Example: 
curl -X POST "https://api.vzaps.com/instances/INSTANCE_ID/subscribe" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'
Typical successful response for direct charge: 
{
  "url": "",
  "sessionId": "sub_xxxxxxxx",
  "mode": "direct",
  "subscriptionId": "sub_xxxxxxxx"
}

​
5. Start the session

After creating the instance you can:
  • call POST /instances/{id}/connect to start the instance connection flow;
  • use session endpoints such as GET /instances/{id}/session/qr and GET /instances/{id}/session/status.
Example to fetch the QR code: 
curl -X GET "https://api.vzaps.com/instances/INSTANCE_ID/session/qr" \
  -H "X-Instance-Token: INSTANCE_TOKEN" \
  -H "X-Client-Token: YOUR_CLIENT_TOKEN"

​
6. Next steps

Continue with: