Contacts API

Contacts are individuals at your companies. They can receive invoices, submit tickets via email, and access the company portal. Every company can have multiple contacts with different roles.

The Contact Object

{
  "id": "con_cuid123456",
  "client_id": "cli_xxxxx",
  "name": "John Smith",
  "email": "john@acme.com",
  "phone": "+1 (555) 123-4567",
  "mobile": "+1 (555) 987-6543",
  "title": "VP of Marketing",
  "department": "Marketing",
  "roles": {
    "is_primary": true,
    "is_billing": true,
    "is_technical": false
  },
  "portal": {
    "access_enabled": true,
    "access_level": "full",
    "last_login_at": "2026-01-20T14:30:00Z"
  },
  "communication": {
    "receives_invoices": true,
    "receives_reports": false,
    "receives_project_updates": true
  },
  "notes": "Primary point of contact, prefers email",
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2026-01-20T14:30:00Z"
}

Contact Fields

Field	Type	Description
`id`	string	Unique identifier (prefix: `con_`)
`client_id`	string	Required. Parent client
`name`	string	Required. Contact name
`email`	string	Email address
`phone`	string	Office phone
`mobile`	string	Mobile phone
`title`	string	Job title
`department`	string	Department
`roles`	object	Contact role flags
`portal`	object	Company portal settings
`communication`	object	Email preferences
`notes`	string	Internal notes
`created_at`	datetime	When created
`updated_at`	datetime	When last updated

Contact Roles

Role	Description
`is_primary`	Main point of contact
`is_billing`	Receives invoices
`is_technical`	Technical escalations

Portal Access Levels

Level	Description
`none`	No portal access
`view`	View projects and tickets
`full`	View + create tickets + approve

List Contacts

GET/v1/contactsList all contacts

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page (max: 100)
`client_id`	string		Filter by client
`is_primary`	boolean		Only primary contacts
`is_billing`	boolean		Only billing contacts
`has_portal_access`	boolean		Only contacts with portal access
`search`	string		Search by name or email

Request

curl "https://api.govantage.co/v1/contacts?client_id=cli_xxxxx" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": [
    {
      "id": "con_cuid123456",
      "client_id": "cli_xxxxx",
      "name": "John Smith",
      "email": "john@acme.com",
      "title": "VP of Marketing",
      "roles": {
        "is_primary": true,
        "is_billing": true
      },
      "portal": {
        "access_enabled": true
      }
    },
    {
      "id": "con_cuid789012",
      "client_id": "cli_xxxxx",
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "title": "Developer",
      "roles": {
        "is_technical": true
      },
      "portal": {
        "access_enabled": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 2
  }
}

Create a Contact

POST/v1/contactsCreate a new contact

Request Body

Field	Type	Required	Description
`client_id`	string	Yes	Client ID
`name`	string	Yes	Contact name
`email`	string	No	Email address
`phone`	string	No	Office phone
`mobile`	string	No	Mobile phone
`title`	string	No	Job title
`department`	string	No	Department
`is_primary`	boolean	No	Primary contact
`is_billing`	boolean	No	Billing contact
`is_technical`	boolean	No	Technical contact
`portal_access`	string	No	`none`, `view`, `full`
`receives_invoices`	boolean	No	Receive invoice emails
`receives_reports`	boolean	No	Receive report emails
`notes`	string	No	Internal notes

Request

curl -X POST "https://api.govantage.co/v1/contacts" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "cli_xxxxx",
    "name": "John Smith",
    "email": "john@acme.com",
    "title": "VP of Marketing",
    "is_primary": true,
    "is_billing": true,
    "portal_access": "full",
    "receives_invoices": true
  }'

Get a Contact

GET/v1/contacts/:idRetrieve a contact by ID

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated: `client`, `tickets`, `activity`

Request

curl "https://api.govantage.co/v1/contacts/con_cuid123456?include=tickets" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Response

{
  "data": {
    "id": "con_cuid123456",
    "client_id": "cli_xxxxx",
    "name": "John Smith",
    "email": "john@acme.com",
    "phone": "+1 (555) 123-4567",
    "title": "VP of Marketing",
    "roles": {
      "is_primary": true,
      "is_billing": true
    },
    "portal": {
      "access_enabled": true,
      "access_level": "full",
      "last_login_at": "2026-01-20T14:30:00Z"
    },
    "tickets": [
      {
        "id": "tkt_xxxxx",
        "title": "Update homepage banner",
        "status": "open",
        "created_at": "2026-01-18T10:00:00Z"
      }
    ]
  }
}

Update a Contact

PUT/v1/contacts/:idUpdate a contact

Request

curl -X PUT "https://api.govantage.co/v1/contacts/con_cuid123456" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chief Marketing Officer",
    "is_billing": true,
    "receives_reports": true
  }'

Delete a Contact

DELETE/v1/contacts/:idDelete a contact

Deleting a contact removes their portal access and unlinks them from tickets. Historical references are preserved.

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

Portal Access

Enable Portal Access

POST/v1/contacts/:id/portal/enableEnable portal access

Sends an invitation email with login instructions.

curl -X POST "https://api.govantage.co/v1/contacts/con_cuid123456/portal/enable" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "access_level": "full",
    "send_invitation": true
  }'

Response

{
  "data": {
    "id": "con_cuid123456",
    "portal": {
      "access_enabled": true,
      "access_level": "full",
      "invitation_sent_at": "2026-01-25T10:30:00Z"
    }
  }
}

Disable Portal Access

POST/v1/contacts/:id/portal/disableDisable portal access

curl -X POST "https://api.govantage.co/v1/contacts/con_cuid123456/portal/disable" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Reset Portal Password

POST/v1/contacts/:id/portal/reset-passwordSend password reset email

curl -X POST "https://api.govantage.co/v1/contacts/con_cuid123456/portal/reset-password" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx"

Merge Contacts

POST/v1/contacts/:id/mergeMerge duplicate contacts

Merge another contact into this one. All references are updated.

curl -X POST "https://api.govantage.co/v1/contacts/con_cuid123456/merge" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "merge_contact_id": "con_duplicate789"
  }'

Find Duplicates

GET/v1/contacts/duplicatesFind potential duplicate contacts

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

Response

{
  "data": [
    {
      "contacts": [
        { "id": "con_xxxxx", "name": "John Smith", "email": "john@acme.com" },
        { "id": "con_yyyyy", "name": "John Smith", "email": "jsmith@acme.com" }
      ],
      "match_reason": "same_name",
      "confidence": 0.85
    }
  ]
}

Bulk Operations

Bulk Create

POST/v1/contacts/bulkCreate multiple contacts

curl -X POST "https://api.govantage.co/v1/contacts/bulk" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "client_id": "cli_xxxxx",
        "name": "John Smith",
        "email": "john@acme.com"
      },
      {
        "client_id": "cli_xxxxx",
        "name": "Jane Doe",
        "email": "jane@acme.com"
      }
    ]
  }'

Bulk Update

PUT/v1/contacts/bulkUpdate multiple contacts

curl -X PUT "https://api.govantage.co/v1/contacts/bulk" \
  -H "Authorization: Bearer vnt_sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["con_xxxxx", "con_yyyyy"],
    "updates": {
      "receives_reports": true
    }
  }'

Webhooks

Subscribe to contact events:

Event	Description
`contact.created`	New contact created
`contact.updated`	Contact details changed
`contact.deleted`	Contact deleted
`contact.portal_enabled`	Portal access granted
`contact.portal_login`	Contact logged into portal

Next Steps

Companies API - Manage parent companies
Tickets API - Contacts can submit tickets
Invoices API - Send invoices to contacts