Arbolus API

Access transcripts, customer insights, and company intelligence through a simple REST API.

v1 · Stable

Overview

The Arbolus API enables seamless integration with Arbolus's expert network platform. Through this API, partners can programmatically access:

Feature	Description
Transcripts	Retrieve expert call transcripts and canopy surveys with metadata and expert details
Customer Library	Access company data, customer insights, NPS scores, and reviews
Health Monitoring	Verify API availability and service status

The API follows RESTful conventions, returns JSON responses, and uses API key authentication.

Getting Started

Obtain Your API Key

Contact [email protected] to request an API key. Each key is scoped to specific features:

Scope	Access
`Transcripts`	All transcript-related endpoints
`CustomerLibrary`	All customer library endpoints

Make Your First Request

curl -X GET "https://api.arbolus.com/v1/health" \
  -H "Accept: application/json"

Authenticate & Fetch Data

curl -X GET "https://api.arbolus.com/v1/transcripts" \
  -H "x-api-key: your_api_key_here" \
  -H "Accept: application/json"

Authentication

All endpoints (except /v1/health) require an API key passed via the x-api-key HTTP header.

Request Header

x-api-key: your_api_key_here

How It Works

Include the x-api-key header in every request
The API validates your key and checks its assigned scope
If the key is valid and has the required scope, the request proceeds
If the key is missing, invalid, or lacks the required scope, an error is returned

Scopes

Scope	Endpoints
`Transcripts`	`GET /v1/transcripts/*`
`CustomerLibrary`	`GET /v1/customer-library/*`

ⓘ

Attempting to access an endpoint outside your key's scope will return a 403 Forbidden response.

Example — Authenticated Request

curl -X GET "https://api.arbolus.com/v1/transcripts" \
  -H "x-api-key: pk_live_abc123def456" \
  -H "Accept: application/json"

Example — Error Responses

// 401 Unauthorized — missing or invalid API key
{
  "statusCode": 401,
  "message": "Unauthorized"
}

// 403 Forbidden — valid key but insufficient scope
{
  "statusCode": 403,
  "message": "Forbidden"
}

Base URL

All API requests are made to:

https://api.arbolus.com

All endpoints are prefixed with the API version (/v1).

Versioning

The API uses URL path versioning. The current version is v1.

https://api.arbolus.com/v1/{endpoint}

When a new version is released, existing endpoints will continue to function under their original version prefix.

Credits & Rate Limiting

Each API key has a configurable credit limit that resets on a recurring billing cycle. Endpoints that return paid data consume credits on each successful (2xx) response; non-2xx responses are refunded automatically.

If your credit balance is exhausted for the current period, the API returns 429 Too Many Requests
Each billing cycle is defined by BillingCycleStart / BillingCycleEnd on the API key, and the cycle length is reused for every subsequent period (next start = previous end)
Contact [email protected] to check your balance or request an increase
API key validations are cached for 15 minutes to optimize performance

Error Handling

The API uses standard HTTP status codes and returns consistent error responses.

Error Response Format

{
  "statusCode": 400,
  "message": "One or more validation errors occurred.",
  "errors": {
    "website": ["Website is required."]
  }
}

Common Error Scenarios

Scenario	Status	Description
Missing API key	`401`	No `x-api-key` header provided
Invalid API key	`401`	The provided key does not exist or is deactivated
Insufficient scope	`403`	Your key does not have access to this endpoint
Resource not found	`404`	The requested transcript or company does not exist
Invalid parameters	`400`	Request parameters failed validation
Credit limit exceeded	`429`	Your API key has exhausted its credit allowance
Server error	`500`	An unexpected error occurred on the server

API Reference

Health Check

Check service availability. This endpoint does not require authentication.

GET /v1/health

Returns the current health status of the API.

✓ No Auth Required

Response

{
  "status": "Healthy",
  "timestamp": "2026-04-24T12:00:00Z"
}

Field	Type	Description
`status`	string	Service health status (`Healthy`)
`timestamp`	string (ISO 8601)	Current server time in UTC

Transcripts

Access expert consultation transcripts with full metadata and expert details.

⚠

Authentication required — All transcript endpoints require an API key with the Transcripts scope.

GET /v1/transcripts

Retrieve a list of all transcripts available to your account.

🔒 Transcripts

Query Parameters

Parameter	Type	Required	Default	Description
`fromDate`	string (ISO 8601)	Yes	—	Start date filter for call date (inclusive)
`tillDate`	string (ISO 8601)	No	—	End date filter for call date (inclusive)
`page`	integer	No	`1`	Page number (must be ≥ 1)
`pageSize`	integer	No	`20`	Results per page (1–100)

Response

{
  "transcripts": [
    {
      "expertNetwork": "Arbolus",
      "transcriptId": "550e8400-e29b-41d4-a716-446655440000",
      "caseCode": "CASE-2024-001",
      "callDate": "2026-04-20T14:30:00Z",
      "callDuration": 3600,
      "consultationTitle": "Market Analysis Discussion"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 157,
    "totalPages": 8
  }
}

Response Fields — Transcript

Field	Type	Description
`expertNetwork`	string	Name of the expert network
`transcriptId`	string (UUID)	Unique identifier for the transcript
`caseCode`	string \| null	Case or project code
`callDate`	string (ISO 8601)	Date and time of the call (UTC)
`callDuration`	integer	Duration of the call in seconds
`consultationTitle`	string \| null	Title of the consultation

Response Fields — Pagination

Field	Type	Description
`page`	integer	Current page number
`pageSize`	integer	Number of results per page
`totalCount`	integer	Total number of matching transcripts
`totalPages`	integer	Total number of pages

Example

curl -X GET "https://api.arbolus.com/v1/transcripts?fromDate=2026-01-01&page=1&pageSize=20" \
  -H "x-api-key: your_api_key_here"

GET /v1/transcripts/{id}

Retrieve the full transcript for a specific interaction, including metadata, expert profile, and speaker-level dialogue.

🔒 Transcripts

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	The transcript identifier

Response

{
  "expertNetwork": "Arbolus",
  "transcriptId": "550e8400-e29b-41d4-a716-446655440000",
  "caseCode": "CASE-2024-001",
  "projectName": "SaaS Market Research",
  "callDate": "2026-04-20T14:30:00Z",
  "callDuration": 3600,
  "consultationTitle": "Market Analysis Discussion",
  "callSummary": "Discussed market trends and growth opportunities.",
  "invitees": ["[email protected]"],
  "office": "New York",
  "expert": {
    "expertId": "660e8400-e29b-41d4-a716-446655440111",
    "firstName": "Michael",
    "lastName": "Johnson",
    "country": "United States",
    "profileSummary": "Seasoned operations executive with 15+ years in SaaS.",
    "relevantExperience": {
      "title": "VP Operations",
      "employer": "TechCorp Inc",
      "startDate": "2020-01-15",
      "endDate": null
    },
    "otherExperiences": [
      {
        "title": "Operations Manager",
        "employer": "DataSoft Ltd",
        "startDate": "2018-06-01",
        "endDate": "2020-01-14"
      }
    ]
  },
  "transcript": [
    {
      "speaker": "Expert",
      "text": "Let's start with the market overview.",
      "timeStamp": "00:00:15"
    },
    {
      "speaker": "Client",
      "text": "The market has grown 20% year-over-year.",
      "timeStamp": "00:00:45"
    }
  ],
  "questionAnswers": [
    {
      "question": "What were the key themes discussed?",
      "sortOrder": 1,
      "answer": "Market consolidation, pricing pressure, and enterprise adoption trends."
    }
  ]
}

Response Fields

Field	Type	Description
`expertNetwork`	string	Name of the expert network
`transcriptId`	string (UUID)	Unique transcript identifier
`caseCode`	string \| null	Case or project code
`projectName`	string \| null	Name of the associated project
`callDate`	string (ISO 8601)	Call date and time (UTC)
`callDuration`	integer	Call duration in seconds
`consultationTitle`	string \| null	Title of the consultation
`callSummary`	string \| null	AI-generated summary of the call
`invitees`	array of strings	Email addresses of invitees
`office`	string \| null	Office location associated with the call
`expert`	object \| null	Expert profile (see below)
`transcript`	array	Ordered list of transcript segments
`transcript[].speaker`	string \| null	Speaker role (Expert, Client, or Others)
`transcript[].text`	string \| null	Spoken text content
`transcript[].timeStamp`	string \| null	Timestamp in `HH:MM:SS` format
`questionAnswers`	array	Pre-call screening questions and expert answers
`questionAnswers[].question`	string \| null	The question text
`questionAnswers[].sortOrder`	integer	Display order of the question
`questionAnswers[].answer`	string \| null	The expert's answer

Expert Object

Field	Type	Description
`expertId`	string (UUID) \| null	Expert's unique identifier
`firstName`	string \| null	Expert's first name
`lastName`	string \| null	Expert's last name
`country`	string \| null	Expert's country
`profileSummary`	string \| null	Brief summary of the expert's professional background
`relevantExperience`	object \| null	Most relevant work experience
`otherExperiences`	array	Additional work history entries

Experience Object

Field	Type	Description
`title`	string \| null	Job title
`employer`	string \| null	Company name
`startDate`	string \| null	Start date (ISO format)
`endDate`	string \| null	End date (`null` if current position)

Example

curl -X GET "https://api.arbolus.com/v1/transcripts/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: your_api_key_here"

GET /v1/transcripts/canopies

List active or paused canopies created within a date range.

🔒 Transcripts

Query Parameters

Parameter	Type	Required	Default	Description
`fromDate`	string (ISO 8601)	Yes	—	Start date filter for canopy creation date (inclusive)
`tillDate`	string (ISO 8601)	No	—	End date filter for canopy creation date (inclusive)
`page`	integer	No	`1`	Page number (must be ≥ 1)
`pageSize`	integer	No	`20`	Results per page (1–100)

Response

{
  "canopies": [
    {
      "canopyId": "bb0e8400-e29b-41d4-a716-446655440666",
      "canopyName": "Q2 SaaS Buyer Sentiment",
      "projectName": "SaaS Market Research",
      "created": "2026-03-12T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 42,
    "totalPages": 3
  }
}

Response Fields — Canopy

Field	Type	Description
`canopyId`	string (UUID)	Unique canopy identifier
`canopyName`	string \| null	Canopy display name
`projectName`	string \| null	Associated project name
`created`	string (ISO 8601)	Canopy creation date (UTC)

Pagination fields match those returned by GET /v1/transcripts.

Example

curl -X GET "https://api.arbolus.com/v1/transcripts/canopies?fromDate=2026-01-01&page=1&pageSize=20" \
  -H "x-api-key: your_api_key_here"

GET /v1/transcripts/canopies/{id}

Retrieve the full set of canopy questions, each with all expert answers.

🔒 Transcripts

Path Parameters

Parameter	Type	Required	Description
`id`	UUID	Yes	Canopy identifier

Response

{
  "canopyId": "bb0e8400-e29b-41d4-a716-446655440666",
  "canopyTitle": "Q2 SaaS Buyer Sentiment",
  "projectName": "SaaS Market Research",
  "questions": [
    {
      "question": "Which vendors did you evaluate?",
      "sortOrder": 1,
      "answers": [
        {
          "expertId": "660e8400-e29b-41d4-a716-446655440111",
          "expertName": "Michael Johnson",
          "answer": "We evaluated VendorA, VendorB, and VendorC."
        },
        {
          "expertId": "cc0e8400-e29b-41d4-a716-446655440777",
          "expertName": "Sarah Lee",
          "answer": "Primarily VendorA and VendorB."
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
`canopyId`	string (UUID)	Canopy identifier
`canopyTitle`	string \| null	Canopy display name
`projectName`	string \| null	Associated project name
`questions`	array	Ordered list of canopy questions
`questions[].question`	string \| null	Question text
`questions[].sortOrder`	integer	Display order of the question
`questions[].answers`	array	Expert answers to this question
`questions[].answers[].expertId`	string (UUID)	Expert identifier
`questions[].answers[].expertName`	string \| null	Expert full name
`questions[].answers[].answer`	string \| null	Expert's answer text

Example

curl -X GET "https://api.arbolus.com/v1/transcripts/canopies/bb0e8400-e29b-41d4-a716-446655440666" \
  -H "x-api-key: your_api_key_here"

Customer Library

Access company intelligence, customer insights, NPS data, and reviews.

⚠

Authentication required — All customer library endpoints require an API key with the CustomerLibrary scope.

GET /v1/customer-library/companies

Retrieve a list of companies filtered by website, with optional name filtering.

🔒 CustomerLibrary

Query Parameters

Parameter	Type	Required	Default	Description
`website`	string	Yes	—	Filter companies by website domain
`companyName`	string	No	—	Filter companies by name prefix

Response

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440222",
    "name": "TechCorp Inc",
    "website": "https://techcorp.com",
    "logoUrl": "https://logos.arbolus.com/techcorp.png",
    "nps": 72,
    "numberOfCustomers": 150,
    "description": "Cloud platform for enterprise data workflows.",
    "revenue": 125000000,
    "totalEmployees": 850,
    "foundationYear": 2008,
    "ownershipType": "Private",
    "exchangeTicker": null,
    "specialities": ["Cloud", "Data Analytics", "SaaS"],
    "competitors": ["DataSoft Solutions", "InsightWorks"],
    "headquarterAddress": {
      "address": "500 Market St, Suite 200",
      "state": "CA",
      "zipCode": "94105",
      "city": "San Francisco",
      "country": "United States"
    }
  }
]

Response Fields — Company

Field	Type	Description
`id`	string (UUID)	Company's unique identifier
`name`	string \| null	Company name
`website`	string \| null	Company website URL
`logoUrl`	string \| null	URL to company logo image
`nps`	integer \| null	Net Promoter Score
`numberOfCustomers`	integer \| null	Total number of customers
`description`	string \| null	Company description
`revenue`	integer \| null	Annual revenue (raw value)
`totalEmployees`	integer \| null	Total employee headcount
`foundationYear`	integer \| null	Year company was founded
`ownershipType`	string \| null	Ownership type (e.g. Private, Public)
`exchangeTicker`	string \| null	Stock exchange ticker symbol
`specialities`	string[] \| null	Company specialities / focus areas
`competitors`	string[] \| null	Competitor company names (from `CompetitorEvaluated` where `VendorCompanyId = company.id` and `CustomerId IS NULL`)
`headquarterAddress`	object \| null	Headquarter address — see below; omitted when all address fields are null

Response Fields — HeadquarterAddress

Field	Type	Description
`address`	string \| null	Street address
`state`	string \| null	State / province
`zipCode`	string \| null	Postal / ZIP code
`city`	string \| null	City name
`country`	string \| null	Country name (resolved from `CompanyDetails.CountryId`)

Example

curl -X GET "https://api.arbolus.com/v1/customer-library/companies?website=techcorp.com&companyName=Tech" \
  -H "x-api-key: your_api_key_here"

GET /v1/customer-library/companies/{companyId}/insights

Retrieve customer insights for a specific company, including spend, NPS, renewal intent, and competitive data. The response includes the current insights (status InReview or Approved) plus any historical Outdated rows for the same customers, so callers can see how a customer's responses have changed over time. Use modifiedDate to distinguish current from outdated entries; outdated rows do not carry competitorsNames.

🔒 CustomerLibrary

Path Parameters

Parameter	Type	Required	Description
`companyId`	UUID	Yes	The target company's identifier

Response

[
  {
    "customerId": "990e8400-e29b-41d4-a716-446655440444",
    "customerName": "GlobalBank Ltd",
    "customerLogoUrl": "https://logos.arbolus.com/globalbank.png",
    "persona": "VP of Operations",
    "spend": 250000,
    "nps": 8,
    "renewalIntent": "Yes",
    "implementationStage": "User",
    "competitorsNames": ["Competitor A", "Competitor B"],
    "modifiedDate": "2026-04-18T10:22:00Z"
  },
  {
    "customerId": "990e8400-e29b-41d4-a716-446655440444",
    "customerName": "GlobalBank Ltd",
    "customerLogoUrl": "https://logos.arbolus.com/globalbank.png",
    "persona": "VP of Operations",
    "spend": 180000,
    "nps": 7,
    "renewalIntent": "NotSure",
    "implementationStage": "Pilot",
    "competitorsNames": null,
    "modifiedDate": "2025-09-02T08:10:00Z"
  }
]

Response Fields

Field	Type	Description
`customerId`	string (UUID)	Identifier of the customer the expert represents
`customerName`	string \| null	Customer company name
`customerLogoUrl`	string \| null	Logo URL of customer company
`persona`	string \| null	Expert's job role/title
`spend`	integer \| null	Annual spend amount
`nps`	integer \| null	Net Promoter Score (0–10)
`renewalIntent`	string \| null	`Yes`, `No`, or `NotSure`
`implementationStage`	string \| null	`Pilot`, `User`, or `OffBoarding`
`competitorsNames`	array of strings \| null	Names of competing vendors (current insights only; `null` on outdated rows)
`modifiedDate`	string (ISO 8601)	Last modification timestamp — use to order current vs. outdated insights

Example

curl -X GET "https://api.arbolus.com/v1/customer-library/companies/770e8400-e29b-41d4-a716-446655440222/insights" \
  -H "x-api-key: your_api_key_here"

GET /v1/customer-library/companies/{companyId}/reviews

Retrieve customer reviews for a specific company. Returns a list of customers with their identifying information and individual question-answer reviews.

🔒 CustomerLibrary

Path Parameters

Parameter	Type	Required	Description
`companyId`	UUID	Yes	The target company's identifier

Response

[
  {
    "customerId": "990e8400-e29b-41d4-a716-446655440444",
    "customerName": "Acme Corporation",
    "nps": 8,
    "reviews": [
      {
        "questionText": "What are the main strengths of this product?",
        "sortOrder": 1,
        "answerText": "Excellent customer support, intuitive UI, and seamless onboarding process."
      },
      {
        "questionText": "What areas need improvement?",
        "sortOrder": 2,
        "answerText": "Reporting dashboards could be more customizable."
      }
    ]
  },
  {
    "customerId": "aa0e8400-e29b-41d4-a716-446655440555",
    "customerName": "GlobalTech Inc.",
    "nps": 9,
    "reviews": [
      {
        "questionText": "What are the main strengths of this product?",
        "sortOrder": 1,
        "answerText": "The integration capabilities and API documentation are outstanding."
      },
      {
        "questionText": "What areas need improvement?",
        "sortOrder": 2,
        "answerText": "Mobile app experience could be improved."
      }
    ]
  }
]

Response Fields — Customer Review

Field	Type	Description
`customerId`	string (UUID) \| null	Customer identifier
`customerName`	string \| null	Customer company name
`nps`	integer \| null	Net Promoter Score (0–10)
`reviews`	array	List of question-answer reviews for this customer

Response Fields — Review Answer

Field	Type	Description
`questionText`	string \| null	The survey question text
`sortOrder`	integer \| null	Display order of the question
`answerText`	string \| null	The review/answer content

Example

curl -X GET "https://api.arbolus.com/v1/customer-library/companies/770e8400-e29b-41d4-a716-446655440222/reviews" \
  -H "x-api-key: your_api_key_here"

Data Models

Enumerations

Renewal Intent

Value	Description
`Yes`	Customer intends to renew
`No`	Customer does not intend to renew
`NotSure`	Customer is undecided about renewal

Implementation Stage

Value	Description
`Pilot`	Product is in pilot/trial phase
`User`	Product is in active use
`OffBoarding`	Customer is in the process of leaving

UUID Format

All identifiers use UUID v4 format:

550e8400-e29b-41d4-a716-446655440000

Date & Time Format

All timestamps follow ISO 8601 in UTC:

2026-04-24T14:30:00Z

Status Codes

Code	Meaning	When It Occurs
`200 OK`	Request succeeded	Data returned successfully
`400 Bad Request`	Invalid input	Validation errors in query parameters
`401 Unauthorized`	Authentication failed	Missing or invalid API key
`403 Forbidden`	Insufficient permissions	API key lacks the required scope
`404 Not Found`	Resource not found	Transcript or company does not exist
`429 Too Many Requests`	Credit limit exceeded	API key has no remaining credits
`500 Internal Server Error`	Server error	Unexpected error — contact support

Quick Reference

GET /v1/health Health check No Auth GET /v1/transcripts List all transcripts Transcripts GET /v1/transcripts/{id} Get full transcript Transcripts GET /v1/transcripts/canopies List canopies Transcripts GET /v1/transcripts/canopies/{id} Get canopy questions & answers Transcripts GET /v1/customer-library/companies List companies CustomerLibrary GET /v1/.../companies/{id}/insights Get customer insights CustomerLibrary GET /v1/.../companies/{id}/reviews Get customer reviews CustomerLibrary

Support

For questions, issues, or to request an API key:

Email: [email protected]
Website: https://www.arbolus.com
Terms of Service: https://www.arbolus.com/terms-of-use