---
updatedAt: 2026-07-21T14:53:28.000Z
agentTools:
  projectIndex: https://docs.gtm.ai/llms.txt
---

# API Conventions

Shared request, response, pagination, error, and identifier conventions for the ZoomInfo GTM API.

This page describes conventions used across ZoomInfo GTM API endpoints.

## Base URL

```text
https://api.zoominfo.com/gtm
```

## Versioning

The current API version is `v1.0`.

Breaking changes are introduced through a new version. Non-breaking additions, such as new optional fields, new enum values, or new endpoints, may be added within the current version.

## Authentication Header

Send the OAuth access token as a bearer token:

```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```

## Identifiers

Use ZoomInfo IDs returned by Search and Lookup responses in later calls. Do not rely on display names when an ID is available.

Recommended pattern:

```text
User says "VP Engineering in Boston SaaS"
-> Lookup management level, job function, region, and industry
-> Search Contacts using lookup IDs
-> Enrich selected contact IDs
```

<br />

## Search Request Shape

Sample request:

```json
curl --request POST \
     --url https://api.zoominfo.com/gtm/data/v1/contacts/search \
     --header 'accept: application/vnd.api+json' \
     --header 'content-type: application/vnd.api+json' \
     --data '
{
  "data": {
    "attributes": {
      "companyName": "ZoomInfo",
      "firstName": "Filip",
      "lastName": "Popovic"
    },
    "type": "ContactSearch"
  }
}
```

## Search Response Shape

Sample response envelope:

```json
{
  "data": [
    {
      "attributes": {
        "company": {
          "id": 344589814,
          "name": "ZoomInfo"
        },
        "contactAccuracyScore": 95,
        "directPhoneDoNotCall": false,
        "firstName": "Filip",
        "hasCompanyCountry": true,
        "hasCompanyEmployeeCount": true,
        "hasCompanyIndustry": true,
        "hasCompanyPhone": true,
        "hasCompanyRevenue": true,
        "hasCompanyState": true,
        "hasCompanyStreet": true,
        "hasCompanyZipCode": true,
        "hasDirectPhone": false,
        "hasEmail": true,
        "hasMobilePhone": true,
        "hasSupplementalEmail": true,
        "jobTitle": "Chief Technology Officer",
        "lastName": "Popovic",
        "lastUpdatedDate": "2025-04-04T18:13:00Z",
        "mobilePhoneDoNotCall": false,
        "validDate": "2024-11-14T22:29:00Z"
      },
      "id": "4191419698",
      "type": "Contact"
    }
  ],
  "links": {
    "first": "/data/v1/contacts/search?page[number]=1&page[size]=25",
    "last": "/data/v1/contacts/search?page[number]=1&page[size]=25"
  },
  "meta": {
    "page": {
      "number": 1,
      "total": 1
    },
    "totalResults": 1
  }
}
```

<br />

## Multi-Enrich Success

Batch endpoints should return successful records and record-level errors in the same response contained in a data array.

```json
{
  "data": [
    {
      "attributes": {
        "company": {
          "id": 346572700,
          "name": "ZoomInfo",
          "employeeCount": 3508,
          "primaryIndustry": [
            "Software",
            "Business Intelligence Software"
          ]
        },
        "country": "United States",
        "email": "henry@zoominfo.com",
        "hasCanadianEmail": false,
        "jobTitle": "Chief Executive Officer & Board Member",
        "directPhoneDoNotCall": false,
        "directPhoneAlt": [
          {
            "value": "+1-360-555-1234",
            "source": "waterfall"
          }
        ],
        "mobilePhoneAlt": [
          {
            "value": "+1-360-555-5678",
            "source": "waterfall"
          }
        ],
        "emailAlt": [
          {
            "value": "henry.schuck@zoominfo.com",
            "source": "waterfall"
          }
        ],
        "withinCalifornia": false,
        "withinCanada": false,
        "withinEu": false,
        "metroArea": "Boston",
        "personHasMoved": "No",
        "region": "Massachusetts",
        "state": "Massachusetts",
        "street": "404 Wyman St",
        "zipCode": "02451"
      },
      "id": "344589814",
      "meta": {
        "input": {
          "companyName": "zoominfo",
          "firstName": "henry",
          "lastName": "schuck"
        },
        "matchStatus": "FULL_MATCH"
      },
      "type": "Contact"
    },
    {
      "attributes": {
        "city": "Bethesda",
        "company": {
          "id": 346572700,
          "name": "ZoomInfo",
          "employeeCount": 3508,
          "primaryIndustry": [
            "Software",
            "Business Intelligence Software"
          ]
        },
        "country": "United States",
        "directPhoneDoNotCall": false,
        "email": "filip@discoverorg.com",
        "firstName": "Filip",
        "hasCanadianEmail": false,
        "jobTitle": "Chief Technology Officer",
        "managementLevel": [
          "C-Level"
        ],
        "metroArea": "Washington",
        "personHasMoved": "Uncertain",
        "region": "Maryland",
        "state": "Maryland",
        "street": "7700 Old Georgetown Rd 5th Fl",
        "zipCode": "20814"
      },
      "id": "234343645",
      "meta": {
        "input": {
          "personId": 4191419698
        },
        "matchStatus": "FULL_MATCH"
      },
      "type": "Contact"
    }
  ]
}
```

## Agent Guidance

When building an AI agent on the API:

* Use Lookup before Search when the user provides natural-language filters.
* Use Search before Enrich.
* Prefer IDs over names.
* Ask for user confirmation before paid enrichment above your configured threshold.
* Keep enrichment batches within documented limits.
* Retry 429 and 5xx responses with backoff.
* Do not retry validation, entitlement, or scope errors without changing the request.

<br />

# Sibling pages

* [Rate Limits](https://docs.gtm.ai/zoominfoenterprise/docs/rate-limits.md)
* [Pagination, Batching and Bulk](https://docs.gtm.ai/zoominfoenterprise/docs/pagination-batching-and-bulk.md)
* [Status Codes and Errors](https://docs.gtm.ai/zoominfoenterprise/docs/status-codes-and-errors.md)
* [Webhook and Events](https://docs.gtm.ai/zoominfoenterprise/docs/webhook-and-events.md)
* [ZoomInfo OAuth Scopes](https://docs.gtm.ai/zoominfoenterprise/docs/zoominfo-oauth-scopes.md)
* [OpenAPI Specifications](https://docs.gtm.ai/zoominfoenterprise/docs/openapi-specifications.md)
* [Credit Usage and Limits](https://docs.gtm.ai/zoominfoenterprise/docs/credit-usage-and-limits.md)