Skip to main content
Alva provides a RESTful API for integrating with external applications, automation platforms (e.g. Zapier), and custom workflows.

​
Overview

  • Base URL: https://app.alvahq.com/api/v1
  • Format: JSON request and response bodies
  • Authentication: Bearer token (API keys)
  • Rate limit: 100 requests per minute per API key
  • Specification: OpenAPI 3.1

​
Authentication

All API requests require a Bearer token. Create API keys at Settings → Developer. 
curl -H "Authorization: Bearer alva_sk_your_key_here" \
  https://app.alvahq.com/api/v1/me

​
API key format

Keys follow the format: alva_sk_{32 hex characters} The full key is shown once on creation. Store it securely — it cannot be retrieved later.

​
Scopes

API keys have granular scopes that control what they can access:
ScopeWhat it allows
companies:readList and get companies
companies:writeCreate, update, and delete companies
contacts:readList and get contacts
contacts:writeCreate, update, and delete contacts
deals:readList and get deals (including methodology data)
deals:writeCreate, update, and delete deals
activities:readList and get activities
activities:writeCreate and update activities
pipeline:readList pipeline stages and methodologies

​
Available endpoints

​
Companies

MethodPathDescription
GET/api/v1/companiesList companies (paginated)
POST/api/v1/companiesCreate a company
GET/api/v1/companies/:idGet a company
PATCH/api/v1/companies/:idUpdate a company
DELETE/api/v1/companies/:idDelete a company

​
Contacts

MethodPathDescription
GET/api/v1/contactsList contacts (paginated)
POST/api/v1/contactsCreate a contact
GET/api/v1/contacts/:idGet a contact
PATCH/api/v1/contacts/:idUpdate a contact
DELETE/api/v1/contacts/:idDelete a contact

​
Deals

MethodPathDescription
GET/api/v1/dealsList deals (paginated)
POST/api/v1/dealsCreate a deal
GET/api/v1/deals/:idGet a deal (includes methodology data)
PATCH/api/v1/deals/:idUpdate a deal
DELETE/api/v1/deals/:idDelete a deal

​
Activities

MethodPathDescription
GET/api/v1/activitiesList activities (paginated)
POST/api/v1/activitiesCreate an activity
GET/api/v1/activities/:idGet an activity
PATCH/api/v1/activities/:idUpdate an activity

​
Metadata

MethodPathDescription
GET/api/v1/pipeline/stagesList pipeline stages and methodologies
GET/api/v1/meGet current API key and account info

​
Rate limiting

All responses include rate limit headers:
HeaderDescription
X-RateLimit-LimitMaximum requests per minute
X-RateLimit-RemainingRemaining requests in the current window
X-RateLimit-ResetWhen the limit resets (Unix timestamp)
If you exceed the limit, you’ll receive a 429 Too Many Requests response with a Retry-After header.

​
Managing API keys

Go to Settings → Developer (admin only) to:
  • Create new keys with a name, selected scopes, and optional expiry
  • View active keys with their prefix, scopes, and last-used time
  • Revoke keys that are no longer needed

​
OpenAPI specification

The full OpenAPI 3.1 specification is available at: 
GET /api/v1/openapi
You can use this to auto-generate client libraries, import into Postman, or power other API tools.