API Conventions

This page describes conventions used across ZoomInfo GTM API endpoints.

Base URL

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:

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:

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

Search Request Shape

Sample request:

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:

{
  "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
  }
}

Multi-Enrich Success

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

{
  "data": [
    {
      "attributes": {
        "company": {
          "id": 346572700,
          "name": "ZoomInfo",
          "employeeCount": 3508,
          "primaryIndustry": [
            "Software",
            "Business Intelligence Software"
          ]
        },
        "country": "United States",
        "email": "[email protected]",
        "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": "[email protected]",
            "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": "[email protected]",
        "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.