Companies API

Name: Vantage PSA
Price: 49 USD
Author: Vantage

Companies are your customer organizations. Every project, ticket, invoice, and time entry is associated with a company.

In Vantage, “Companies” and “Clients” are synonymous. The API uses client in endpoints and field names (e.g., /v1/clients, client_id), but the UI refers to these as Companies.

The Company Object

{
  "id": "cli_cuid123456",
  "name": "Acme Corporation",
  "website": "https://acme.com",
  "phone": "+1 (555) 123-4567",
  "email_slug": "acme",
  "status": "active",
  "health_score": 85,
  "industry": "Technology",
  "timezone": "America/New_York",
  "address": {
    "line1": "123 Main Street",
    "line2": "Suite 400",
    "city": "Boston",
    "state": "MA",
    "postal_code": "02101",
    "country": "US"
  },
  "billing": {
    "payment_terms": 30,
    "payment_type": "ACH",
    "po_required": false,
    "tax_exempt": false,
    "default_rate_id": "rate_xxxxx"
  },
  "financials": {
    "lifetime_revenue": 125000.00,
    "outstanding_balance": 5000.00,
    "avg_payment_days": 28
  },
  "account_manager_id": "usr_xxxxx",
  "billing_contact_id": "con_xxxxx",
  "notes": "Key account, premium support",
  "created_at": "2025-03-15T10:30:00Z",
  "updated_at": "2026-01-20T14:22:00Z"
}

Company Fields

Field	Type	Description
`id`	string	Unique identifier (prefix: `cli_`)
`name`	string	Required. Company name
`website`	string	Company website URL
`phone`	string	Primary phone number
`email_slug`	string	Unique slug for inbound email routing
`status`	enum	`active`, `inactive`, `prospect`
`health_score`	integer	Calculated health score (0-100)
`industry`	string	Industry category
`timezone`	string	IANA timezone (e.g., `America/New_York`)
`address`	object	Address details (see below)
`billing`	object	Billing settings (see below)
`financials`	object	Read-only financial summary
`account_manager_id`	string	Assigned account manager
`billing_contact_id`	string	Primary billing contact
`notes`	string	Internal notes
`created_at`	datetime	When the company was created
`updated_at`	datetime	When the company was last updated

Address Object

Field	Type	Description
`line1`	string	Street address
`line2`	string	Apt, suite, building
`city`	string	City
`state`	string	State/province
`postal_code`	string	ZIP/postal code
`country`	string	ISO country code

Billing Object

Field	Type	Description
`payment_terms`	integer	Payment due days (default: 30)
`payment_type`	string	`Credit Card`, `ACH`, `Check`, `Wire`
`po_required`	boolean	Requires PO number on invoices
`tax_exempt`	boolean	Tax exempt status
`tax_exempt_id`	string	Tax exemption certificate number
`default_rate_id`	string	Default billing rate
`custom_rate`	decimal	Custom hourly rate
`expense_markup`	decimal	Expense markup percentage

List Companies

GET/v1/clientsList all companies

Returns a paginated list of companies.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Results per page (max: 100)
`status`	string	all	Filter by status: `active`, `inactive`, `prospect`
`search`	string		Search by name, email, or phone
`account_manager_id`	string		Filter by account manager
`industry`	string		Filter by industry
`sort`	string	`name`	Sort by: `name`, `created_at`, `health_score`, `lifetime_revenue`
`order`	string	`asc`	Sort order: `asc`, `desc`

Request

curl "https://api.govantage.co/v1/clients?status=active&per_page=50" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": [
    {
      "id": "cli_cuid123456",
      "name": "Acme Corporation",
      "status": "active",
      "health_score": 85,
      "industry": "Technology",
      "account_manager_id": "usr_xxxxx",
      "financials": {
        "lifetime_revenue": 125000.00,
        "outstanding_balance": 5000.00
      },
      "created_at": "2025-03-15T10:30:00Z"
    },
    {
      "id": "cli_cuid789012",
      "name": "Beta Industries",
      "status": "active",
      "health_score": 72,
      "industry": "Manufacturing",
      "account_manager_id": "usr_yyyyy",
      "financials": {
        "lifetime_revenue": 45000.00,
        "outstanding_balance": 0.00
      },
      "created_at": "2025-06-20T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 127,
    "total_pages": 3
  }
}

Create a Company

POST/v1/clientsCreate a new company

Request Body

Field	Type	Required	Description
`name`	string	Yes	Company name
`website`	string	No	Company website
`phone`	string	No	Phone number
`email_slug`	string	No	Unique slug for email routing
`status`	string	No	Default: `active`
`industry`	string	No	Industry category
`timezone`	string	No	IANA timezone
`address`	object	No	Address details
`billing`	object	No	Billing settings
`account_manager_id`	string	No	Account manager user ID
`notes`	string	No	Internal notes

Request

curl -X POST "https://api.govantage.co/v1/clients" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "website": "https://acme.com",
    "industry": "Technology",
    "billing": {
      "payment_terms": 30,
      "payment_type": "ACH"
    },
    "address": {
      "line1": "123 Main Street",
      "city": "Boston",
      "state": "MA",
      "postal_code": "02101",
      "country": "US"
    }
  }'

Response

{
  "data": {
    "id": "cli_cuid123456",
    "name": "Acme Corporation",
    "website": "https://acme.com",
    "status": "active",
    "industry": "Technology",
    "billing": {
      "payment_terms": 30,
      "payment_type": "ACH"
    },
    "address": {
      "line1": "123 Main Street",
      "city": "Boston",
      "state": "MA",
      "postal_code": "02101",
      "country": "US"
    },
    "created_at": "2026-01-25T10:30:00Z",
    "updated_at": "2026-01-25T10:30:00Z"
  }
}

Get a Company

GET/v1/clients/:idRetrieve a company by ID

Path Parameters

Parameter	Description
`id`	The company ID

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated related data: `contacts`, `projects`, `agreements`, `invoices`, `stats`

Request

curl "https://api.govantage.co/v1/clients/cli_cuid123456?include=contacts,stats" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": {
    "id": "cli_cuid123456",
    "name": "Acme Corporation",
    "website": "https://acme.com",
    "phone": "+1 (555) 123-4567",
    "status": "active",
    "health_score": 85,
    "industry": "Technology",
    "address": {
      "line1": "123 Main Street",
      "city": "Boston",
      "state": "MA",
      "postal_code": "02101",
      "country": "US"
    },
    "billing": {
      "payment_terms": 30,
      "payment_type": "ACH"
    },
    "financials": {
      "lifetime_revenue": 125000.00,
      "outstanding_balance": 5000.00,
      "avg_payment_days": 28
    },
    "contacts": [
      {
        "id": "con_xxxxx",
        "name": "John Smith",
        "email": "john@acme.com",
        "is_billing_contact": true
      }
    ],
    "stats": {
      "active_projects": 3,
      "open_tickets": 7,
      "active_agreements": 1,
      "total_hours_ytd": 450.5
    },
    "created_at": "2025-03-15T10:30:00Z",
    "updated_at": "2026-01-20T14:22:00Z"
  }
}

Update a Company

PUT/v1/clients/:idUpdate a company

Updates the specified company. Only include fields you want to change.

Path Parameters

Parameter	Description
`id`	The company ID

Request

curl -X PUT "https://api.govantage.co/v1/clients/cli_cuid123456" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "billing": {
      "payment_terms": 45,
      "po_required": true
    },
    "notes": "Updated: Now requires PO for all invoices"
  }'

Response

Returns the updated company object.

Delete a Company

DELETE/v1/clients/:idDelete a company

Deleting a company is permanent and removes all associated data including contacts, projects, tickets, time entries, and invoices. Consider setting status to inactive instead.

Path Parameters

Parameter	Description
`id`	The company ID

Request

curl -X DELETE "https://api.govantage.co/v1/clients/cli_cuid123456" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": {
    "id": "cli_cuid123456",
    "deleted": true
  }
}

Company Contacts

List Company Contacts

GET/v1/clients/:id/contactsList contacts for a company

curl "https://api.govantage.co/v1/clients/cli_cuid123456/contacts" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Add Contact to Company

POST/v1/clients/:id/contactsCreate a contact for this company

curl -X POST "https://api.govantage.co/v1/clients/cli_cuid123456/contacts" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@acme.com",
    "phone": "+1 (555) 987-6543",
    "title": "VP of Marketing",
    "is_billing_contact": false
  }'

Company Projects

List Company Projects

GET/v1/clients/:id/projectsList projects for a company

curl "https://api.govantage.co/v1/clients/cli_cuid123456/projects?status=active" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Company Tickets

List Company Tickets

GET/v1/clients/:id/ticketsList tickets for a company

curl "https://api.govantage.co/v1/clients/cli_cuid123456/tickets?status=open" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Company Invoices

List Company Invoices

GET/v1/clients/:id/invoicesList invoices for a company

curl "https://api.govantage.co/v1/clients/cli_cuid123456/invoices?status=sent" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Health Score

The health score is a composite metric (0-100) calculated from:

Component	Weight	Factors
Financial	40%	Revenue, margins, payment history
Operational	30%	Ticket volume, resolution times
Relationship	20%	Activity recency, engagement
Growth	10%	Revenue trend, pipeline

Health scores are recalculated hourly. Use the health_score field to identify at-risk companies early.

Score Ranges

Score	Status	Meaning
80-100	Excellent	Healthy, engaged company
65-79	Good	Minor issues, monitor
50-64	Fair	Attention needed
35-49	At Risk	Intervention required
0-34	Critical	Immediate action needed

Webhooks

Subscribe to company events:

Event	Description
`client.created`	New company created
`client.updated`	Company details changed
`client.deleted`	Company deleted
`client.health_changed`	Health score crossed threshold

Next Steps

Projects API - Manage company projects
Time Entries API - Log time against companies
Invoices API - Bill your companies