API reference

Base URL

https://api.harvestwave.com

Authentication

Create and rotate credentials in the portal under API credentials. Do not put the portal password on the lookup request.

Applications authenticate with an OAuth2 client-credentials bearer token on Authorization: Bearer.

Get an access token

Request a token:

POST https://api.harvestwave.com/oauth/token

Body fields: grant_type, client_id, and client_secret. grant_type must be client_credentials. The same call accepts Content-Type: application/json or Content-Type: application/x-www-form-urlencoded.

JSON body:

POST /oauth/token HTTP/1.1
Host: api.harvestwave.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Form body, same three fields:

POST /oauth/token HTTP/1.1
Host: api.harvestwave.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Response fields: access_token, token_type (Bearer), and expires_in (seconds). The default expires_in is 28800 (eight hours). There is no refresh token — request a new client-credentials token when near expiry.

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 28800
}

Call the API

Send the token as Authorization: Bearer <access_token>.

Authorization: Bearer YOUR_ACCESS_TOKEN

For the full implementer walkthrough (portal credentials, token call, lookup samples, and TypeScript), see How to connect.

POST /v1/lookups

Send one E.164 number. The match is exact. Off-by-one is a different number; there is no fuzzy matching.

Request

POST /v1/lookups HTTP/1.1
Host: api.harvestwave.com
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "phoneNumber": "+15551234567"
}

Response

{
  "isBusiness": true,
  "businesses": [
    { "name": "Example Firm LLP", "confidence": 1.0 }
  ]
}

confidence is 1.0 for an exact directory listing. Address, additional numbers, and contacts are omitted unless your token includes those data permissions and the directory has them. Entitled extra slices that actually appear on the body add one credit each.

Errors and rate limits

See the portal for the live account status of credentials, remaining credits, and any enforced limits. This page does not invent status codes or SLA numbers.