Fundamentals

Authentication

Authentication with the API is done through Bearer Authorization. Simply include an Authorization: Bearer YOUR_API_TOKEN header in your request.

Request bodies

POST requests to the API require the Content-Type: application/json header and a JSON body while passing in any parameters to the request.

Base URL

The API base URL is https://app.hockeystack.com/integration/sales/ at this time.

Rate Limits

10 requests per 30 seconds per IP address.

When rate limit is reached, the API will return a 429 error code. In this case, we recommend an exponential backoff retry strategy.

Long-Running Tasks

If the endpoint you called performs a long-running task, it won't be able to return a response within the first time you call it. In this case, it will return a 202 status code, signaling you to retry the request until a response is reached.

In this case, we recommend retries every 30 seconds up to 40 times. If the endpoint does not return a valid response within 40 tries, you can declare it an error within your logic. If you see any such error, please contact our support team.

Errors

Authentication Errors

No Authorization Header (403)

{
  "message": "No token provided"
}

Invalid Token Format (403)

{
  "message": "Invalid token format"
}

Invalid or Inactive Token (403)

{
  "message": "Invalid or inactive token"
}

Validation Errors

Missing Company Domain (400)

{
  "message": "companyDomain is required"
}

Invalid Domain Format (400)

{
  "message": "Invalid company domain format. Must be a properly formatted domain name."
}

Invalid Fields Parameter (400)

{
  "message": "fields_to_get must be a string like: field_1,field_2"
}

Company Not Found (404)

{
  "result": {
    "status": "error",
    "code": 404,
    "error": "Requested company not found in hockeystack",
    "companyDomain": "nonexistent.com",
    "research": {}
  }
}

Server Errors

In the below cases, please contact our support team.

Internal Server Error (500)

{
  "message": "Internal error"
}

{
  "message": "An error occurred while processing your request."
}

API Support

For API support, contact [email protected]