API

API Access is for enterprise customers only

Rox APIs are split into two types — Management APIs and Agent APIs. Management APIs are used to set up and tune Rox agents, human users, data integrations and track agent health and security. Agent action APIs are used for getting/ updating agent info, account intelligence and conversational intelligence (Alpha Release). API specs are described below

Management APIs

Agents

Add Agent

This API is responsible for adding an agent that tracks, updates and maintains a single company across public and private data sources.

POST /v1/agent/

Host: [api.rox.com](<http://api.rox.com/>)
Authorization: Bearer {your_api_key}
Content-Type: application/json

Request:

{
	"name": "string", // (required) The name of the company
	"domain": "string" // (required) The domain of the company
}

Response:

{
	"id" : <uuid>
}

Code	Description
201	Agent Registered
400	Validation error.
401	Unauthorized.
500	Internal server error.

List Agents

List all the agents that have been registered.

GET /management_apis/agents/

Response:

{
	"id": "uuid" // uuid for the agent
	"name": "string", 
	"domain": "string"
}

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Delete Agent

Remove registered agent

POST /v1/agent/delete/{id}

Response:

Code	Description
201	Deleted
400	Validation error.
401	Unauthorized.
500	Internal server error.

Tune Agents

The APIs in this section will allow to tune the agents to the requirements of the org

Tune Insights

Tune your Rox Agent Swarm by specifying important things to look out for when monitoring public and private data for insights.

POST /v1/agents/tune-insights

Request:

{
	"exclusive": "true/false" // When exclusive, only insights 
	matching your preferences are displayed. Otherwise, your preferences refine results but don't exclude other relevant insights.
	"news": [String] // list of strings which represent news events of interest 
	"job postings": [String] 
}

GET /v1/agents/tune-insights

Response:

{
	"exclusive": "true/false" // When exclusive, only insights 
	matching your preferences are displayed. Otherwise, your preferences refine results but don't exclude other relevant insights.
	"news": [String] // list of strings which represent news events of interest 
	"job postings": [String] 
}

Response:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Tune Agent Personas

Tune your AI Agent Swarm by specifying specific personas to look for when finding and enriching relevant people at companies. Rox has a default set of personas it generates depending on your org.

POST /v1/agents/tune-personas

Request:

{
	"personas":[String] // list of personas of interest to register 
}

GET /v1/agent/tune-personas

Response:

{
	"personas":[String] // list of personas registered for the agent swarm 
}

Response:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Upload Org Templates

Templates can be uploaded for notes / account research. These templates are general for the entire org.

POST /v1/agents/template

Request:

{
	"name": "string" //name of the template
	"type": "notes/account-research" // template-type
	"format": "txt/pdf/ppt" //template format
	"data": [bytes] // template data here (max 1MB)
	"default": "true/false"
}

Response:

{
	"id": "uuid" //template uuid
	"content": "string" // extracted sections
}

GET /v1/agents/template/{template-id}

Response:

{
	"id": "uuid" //template uuid
	"content": "string" // extracted sections
}

DELETE /v1/agents/template/{template-id}

Response:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Upload Agent Artifacts

Artifacts, such as product information, case studies, and value propositions, provide company-specific context for Rox's agents, helping them evaluate events and generate content more precisely. These can be documents or publicly available web pages.

Track Public Data Sources

Public data source URLs that the Rox agent swarm should track to provide actionable insights

Track Newsletters

Public newsletters that the Rox agent swam should track to provide actionable insights

User

1. Create User

2. Upload User Templates

3. Assign Agents to User

4. List Agents associated with User

5. Delete Agents from User

Integrations

1. Connect SFDC (Org Specific)

2. Connect Zendesk (Org Specific)

3. Connect Google Calendar (User Specific)

   1. Configure pre-meeting briefs

4. Connect Email (User Specific)

5. Data Share (Talk to Rox)

Health

1. Agent Status

Security

1. Get Audit Logs

Auth

Get Access Token

Request

{ 
  "client_id": <client_id>
  "client_secret": <client_secret>
}

Response

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

Agent Action APIs

Once the agents have been setup, agent action APIs can be used to interact with the agent for information. An agent in Rox ONLY knows about the triplet — seller, seller’s organization and a single company the seller is selling into. It ingests and tracks both public and private data from various different data sources and provides account info, account intelligence and conversational intelligence

Agent Info

Get Pain Hypothesis

Gets pain hypothesis of the company. For public companies, this is gotten from their recent 10K/10Q and for private companies, this is gotten by looking at a variety of sources like competitors, case studies etc. More the data (notes etc), the pain hypothesis becomes more personalized.

GET /v1/agent/{agent-id}/pain-hypothesis

Response:

{
	"tldr": "string" //tldr formatted with markdown in a numbered list
	"content": "string" //full blown content with markdown
}

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Corporate Objectives

Gets the corporate objectives.

GET /v1/agent/{agent-id}/corporate-objectives

Response:

{
	"content": "string" //Corporate objectives in a numbered list
}

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Firmographics

Gets the company firmographics

GET /v1/agent/{agent-id}/firmographics

Response:

{
	"website": "string",
	"industry": "string", //industry, can be empty
	"revenue": "string",  //revenue, can be empty
	"headcount": "string", //total head count, can be empty 
	"headcount-by-team": { //headcount split by team, can be empty
    "team_name_1": "string",
    "team_name_2": "string"
  }
  
  "rox-verified-fields": [string] //industry, revenue, headcount...
}

Get Contacts

Gets the contacts that have been searched based on the contacts for the given agent

GET /v1/agent/{agent-id}/contacts

Response:

[{
	"id": "uuid",
	"firstname": "string", //can be empty
	"lastname": "string", //can be empty
	"linkedinurl": "string", 
	"email": "string",  //can be empty
	"phonenumber": "string", //can be empty
	"title": "string", //can be empty
	"level": "string", // [One of C-suite, VP, Director, Manager, Non-Manager]
	"snippet": "string", //can be empty
	"type": "string"// [One of New, Engaged, Dismissed] 
  }, 
{
	"id": "uuid",
	..
}
]

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Patch Contact

Modify an existing contact

PATCH /v1/agent/{agent-id}/contacts/{contact-id}

Request:

{
	"id": "uuid",
	"firstname": "string", 
	"lastname": "string",
	"linkedinurl": "string", 
	"email": "string", 
	"phonenumber": "string",
	"title": "string",
	"level": "string", // [One of C-suite, VP, Director, Manager, Non-Manager]
	"snippet": "string",
	"type": "string" //[One of New, Engaged, Dismissed] 
 }

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Load more contacts

Load more contacts. Personas is optional. If provided, it overrides the agent level and user level personas already configured. If not provided, the agent and user level personas will be used to load more contacts

POST /v1/agent/{agent-id}/contacts/add

Request:

{
	"personas": [string] // (optional) if provided will override org level/ user level personas 
 }

Response:

[{
	"id": "uuid",
	"firstname": "string", 
	"lastname": "string",
	"linkedinurl": "string", 
	"email": "string", 
	"phonenumber": "string",
	"title": "string",
	"level": "string", // [One of C-suite, VP, Director, Manager, Non-Manager]
	"snippet": "string",
	"type": "string" //[One of New, Engaged, Dismissed] 
 }]

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Notes

Get the notes associated with the agent. These notes could be auto-generated or input by the seller

GET /v1/agent/{agent-id}/notes

Response:

[ 
 {
	"note-id": "uuid", //uuid	
	"date": "timestamp", // time-stamp
	"notes": "string" // Notes
 }, 
 {
 }
 ]

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Add Notes

Add notes to the agent

POST /v1/agent/{agent-id}/notes

Request:

[ 
 {
	"date": "timestamp", // time-stamp
	"notes": "string" // Notes
 }
 ]

Response:

[ 
 {
	"note-id": "uuid" //note uuid
 }
]

Response Code:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Patch Notes

Update existing notes

POST /v1/agent/{agent-id}/notes/{note-id}

Request:

 {
	"notes": "string" // Update existing notes.
 }

Response Code:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Previous / Next calendar events

Get the previous and next calendar events for the seller

GET /v1/agents/{agent-id}/calendar-events

Response:

 {
	"prev-calendar-event": "timestamp", // can be empty
	"next-calendar-event": "timestamp", // time-stamp
 }
 

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

List Salesforce opportunities

List of endpoints to retrieve and update opportunities in salesforce

GET /v1/agents/{agent-id}/opportunities

Get the list of active opportunities (not CLOSED_LOST or CLOSED_WON) from salesforce for this specific account.

Response:

[{
  "field-name1": "value",
  "field-name2": "value"
},
{
  "field-name1": "value",
  "field-name2": "value"
}
]
 

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Create new Salesforce Opportunity

Create a new salesforce opportunity given an opportunity object fields

POST /v1/agents/{agent-id}/opportunity

Request:

{
  "field-name1": "value",
  "field-name2": "value"
}

Response Code:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Patch existing Salesforce Opportunity

PATCH /v1/agents/{agent-id}/opportunity

Request:

{
	"opportunity-id": "value", //(required) opportunity id to patch
  "field-name1": "value",
  "field-name2": "value"
}

Response Code:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Next Steps

Use this endpoint to get next steps associated with an agent.

GET /v1/agents/{agent-id}/next-steps

Response:

[{
	"step-id": uuid,
	"step-name": "string", 
	"due-timestamp": long // 
  "type": "string", // [One of "completed" or "upcoming"]
}, ...
]

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Create Next Step

Creates the next step associated with the agent

POST /v1/agents/{agent-id}/next-step

Request:

{
	"step-name": "string", 
	"due-timestamp": long // 
  "type": "string", // [One of "completed" or "upcoming"]
 }

Response:

{
	"step-id": uuid
 }

Update Next Step

Update the next steps associated with the agent

PATCH /v1/agents/{agent-id}/next-step

Request:

{
	"step-id": [uuid], //(required) set of uuids for seller notes
	"step-name": "string", 
	"due-timestamp": long // 
  "type": "string", // [One of "completed" or "upcoming"]
}

Response Code:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Delete Next Step

Delete the next step associated with the agent

DELETE /v1/agents/{agent-id}/next-step

Request:

{
	"step-id": [uuid], //(required) set of uuids for seller notes
}

Response Code:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Rox Embeddable Dashboard

Get a Rox Embeddable dashboard url that can be used by clients to stick into their portals / sfdc

GET /v1/agents/{agent-id}/dashboard

Request:

{
// Optional list of colors to override
  "color_overrides": [
    {
      // The color to override
      "name": enum, // "gray_dark", "gray_medium", "gray_light", "gray_extralight", "white", "primary_medium", "primary_light", "usageline_0", "usageline_1", "usageline_2", "usageline_3", "usageline_4", "usageline_5", "usageline_6", "usageline_7", "usageline_8", "usageline_9", "primary_green", or "primary_red"

      // Hex value representation of the color
      "value": string
    }
  ]
}
 

Response:

{
"url": "string" // rox url 
}

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Agent Account Intelligence

Get Insights

Get insights for the current account. Use this API to poll every day to get the latest insights for the account. This API can also be used to get historical insights depending on the start-date.

GET /intellgence_api/agents/{agent-id}/insights

Request:

{
  "start-date": "timestamp" // start timestamp
}
 

Response:

[
{
	"insight-id": "uuid",
	"date": "timestamp",
	"type": "string" ["news"/"job postings"/"10k"/"10Q"/"Earnings call"]
	"tldr": "string",
	"content": "string",
	"domain" : "string",
},
{
	"insight-id": "uuid",
	"date": "timestamp",
	"type": "string" ["news"/"job postings"/"10k"/"10Q"/"Earnings call"]
	"tldr": "string",
	"content": "string",
	"domain" : "string",
}
] 

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get pre-meeting brief

Get pre-meeting briefs either specific to a user. Use this API to poll every day to get the pre-meeting briefs for that specific user.

GET /v1/{user-id}/pre-meeting-briefs

Response:

[
{
		"Meeting header": "string",
		"date": "timestamp",
		"attendees": [{
		"name" : "string",
		"email": "string",
		"linkedinurl": "string",
		"title": "string",
		"company": "string",
		"snippet": "string"
}
"insights - last 30 days": [{
				"insight-id": "uuid",
				"date": "timestamp",
				"type": "string" ["news"/"job postings"/"10k"/"10Q"/"Earnings call"]
				"tldr": "string",
				"content": "string",
			},
			{
				"insight-id": "uuid",
				"date": "timestamp",
				"type": "string" ["news"/"job postings"/"10k"/"10Q"/"Earnings call"]
				"tldr": "string",
				"content": "string",
			}]
}
] 

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Account Research Report

Gets a quick high level summary of the account. If a template was provided in the “Upload templates”, tries to fit the account research to that format (on a best-effort basis).

GET /v1/agents/{agent-id}/account-research

Request:

{
  "template-id": uuid // (optional) template id to use for account research
}
 

Response:

{
  "Business Unit Summary": [string, source] 
  "Financials" : "string" // mark down string
  "Recent-events": [{ "tldr": "string", 
										  "content": "string", 
										  "source-link": "string" }, {}]
  "Relevant people": [{"name": "string", 
										   "title": "string",
											 "information": "string",
											 "linkedinurl": "string"}, {}]
	"Use cases": [{ "tldr": "string", 
								  "content": "string", 
								  "source-link": "string" }, {}]
	
	"Case studies": [{ "tldr": "string", 
								  "content": "string", 
								  "source-link": "string" }, {}]
								  
	"custom fields metadata": [{"field-name": "string",
															"values": [{"field-name1": "string", 
																					"field-name2": "string",}]]
															
	.... (custom fields and its values below)
  }
 

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Draft Email

Draft an email to a specified contact or set of contacts given a prompt and other attributes - insights, templates, artifacts etc.

GET /v1/agents/{agent-id}/draft-email

Request:

{
  "prompt": "string" // (required) intent for the email,
  "contacts": [uuids] //(optional) uuid of the contacts we want to send email to
  "insights": [uuids] // (optional) uuids of the insights to use for generating email
  "template": uuid // (optional) email template uuid to use
  "artifacts": [uuids]// (optional) uploaded artifacts like case-study, use-cases etc to use
  "company-info": [strings] // (optional) Input can be - "pain-hypothesis", "corporate-objectives"
}

Response:

{
  "subject": "string",
  "content" "string"
}
 

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Agent Opportunity Recommendation (Alpha Feature)

Gets opportunity recommendation by the agent by taking in seller notes. One can either use the endpoint to create an existing opportunity or update an existing one. Note that the API does not create or update but rather provides an opportunity object. The implementor should then use one of create/patch opportunity endpoints above to do the necessary action. This is to ensure that there is human-in-the-loop validation.

GET /v1/agents/{agent-id}/opportunity-recommendation

Request:

{
	"note-id": [uuid], //(required) set of uuids for seller notes
	"action": "string" // [One of "create" or "update"]
  "opportunity-id": "string", // opportunity-id to use to generate if action is "update"
}

Response:

{
	"field-name1": "value",
  "field-name2": "value"
}

Response Code:

Code	Description
200	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Get Agent Next Step Recommendation

Recommends next steps to perform for the account based on various input fields like notes, calendar, emails (if connected)

GET /v1/agents/{agent-id}/next-step-recommendation

Response:

{
	"step-name": "string", 
	"due-timestamp": long // 
}

Response Code:

Code	Description
201	OK
400	Validation error.
401	Unauthorized.
500	Internal server error.

Agent QA

Generic Question and Answer to the agent. The agent manages contexts of the last chat messages before answering the question

POST /v1/agents/{agent-id}/qa

Request:

{
	"message": "string", 
}

Response:

{
	"answer": "string" // mark down style 
}

Agent Conversational Intelligence

1. Meeting Summary

2. Meeting Notes