BETA

Marvin2 API Documentation

INTRODUCTION

ENDPOINTS

HISTORY

Getting Started

Welcome to our API documentation. This guide will help you get started with integrating our API into your applications.

Base URL

https://classification.relativity6.com

Non-prod (staging):

https://classification-staging.relativity6.com

Authentication

All requests require authentication. You can use any of the following methods:

API Key (recommended for most use cases):

Content-Type: application/json
x-api-key: YOUR_API_KEY

Bearer Token (for user sessions or service accounts):

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

M2M OAuth Token (for machine-to-machine integrations):

Content-Type: application/json
Authorization: Bearer mt_YOUR_M2M_TOKEN

See the Authorization section for detailed information on all methods.

Authorization

All API requests require authentication. We support three authentication methods: API keys, Bearer tokens (user sessions), and M2M OAuth tokens (machine-to-machine).

Method 1: API Key Authentication

Add your API key to the request headers. You can obtain your API key by contacting Relativity6.

Content-Type: application/json
x-api-key: YOUR_API_KEY

Method 2: Bearer Token Authentication (OAuth/JWT)

For enhanced security with short-lived credentials, you can authenticate using Bearer tokens. This method is ideal for service accounts and automated integrations.

Step 1: Obtain an Access Token

Request an access token using your service account credentials:

POST https://admin.relativity6.com/auth/sign-in
Content-Type: application/json

{
  "email": "your-service-account@example.com",
  "password": "your-password"
}

// Response:
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600  // Token valid for 1 hour
}

Step 2: Use the Token in API Requests

Include the access token in the Authorization header:

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Token Expiration & Refresh

Access tokens expire after 1 hour (3600 seconds). When a token expires, simply request a new one using the sign-in endpoint. Your requests are tracked against your organization's quota regardless of which authentication method you use.

Method 3: M2M OAuth Client Credentials (Machine-to-Machine)

For fully automated, server-to-server integrations without user interaction, use the OAuth 2.0 Client Credentials flow. This method provides short-lived access tokens ideal for backend services, scheduled jobs, and automated pipelines.

Step 1: Obtain Machine Credentials

Contact Relativity6 to provision M2M machine credentials for your organization. You will receive:

client_id - Your machine identifier (starts with mch_)
client_secret - Your machine secret key (starts with ak_)

Step 2: Request an Access Token

Exchange your machine credentials for an access token:

POST https://admin.relativity6.com/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "mch_your_machine_id",
  "client_secret": "ak_your_machine_secret"
}

// Response:
{
  "access_token": "mt_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "marvin2-api platform-api"
}

Step 3: Use the Token in API Requests

Include the M2M access token in the Authorization header:

POST https://classification.relativity6.com/marvin2
Content-Type: application/json
Authorization: Bearer mt_abc123...

{
  "name": "Acme Corporation",
  "state": "CA",
  "city": "San Francisco"
}

M2M Best Practices

• Cache tokens: Reuse tokens until they expire (check expires_in)
• Refresh proactively: Request a new token before the current one expires
• Secure secrets: Store client_secret securely (env vars, secret managers)
• Handle 401s: If you receive a 401, your token may have expired - request a new one

When to Use M2M vs API Keys

Use M2M OAuth when:

You need short-lived tokens (better security)
Your security policy requires credential rotation
You're building automated backend services

Use API Keys when:

You need simpler integration
You're building scripts or one-off tools
Token management adds unnecessary complexity

Migrating from Legacy Marvin API

Authentication Change

If you're migrating from the Marvin API, you'll need to update your authentication method.

Previous Method (Marvin API)

Including the API key in the request body:

{
  "token": "YOUR_API_KEY",
  "name": "Acme Corporation",
  "state": "CA",
  ...
}

New Method

Using the x-api-key header:

// Request Headers
x-api-key: YOUR_API_KEY

// Request Body
{
  "name": "Acme Corporation",
  "state": "CA",
  ...
}

Migration Steps

Remove the "token" field from your request body
Add the x-api-key: YOUR_API_KEY header to all requests
Keep all other request parameters the same

Health Endpoint

GET

/health

Simple health check to verify the Classification API is operational. Requires authentication via the x-api-key header.

Example Request

GET https://classification.relativity6.com/health
x-api-key: YOUR_API_KEY

Example Response

{
  "status": "healthy",
  "timestamp": "2025-03-27T03:51:52.922Z",
  "version": "1.0.0"
}

Property	Type	Description
status	string	Indicates the operational status. Always "healthy" on success.
timestamp	string	ISO 8601 timestamp when the health check was performed.
version	string	Service version.

Marvin2 Endpoint

POST

/marvin2

The Marvin2 endpoint provides backward compatibility for existing integrations while improving the accuracy of the predictions.

Full Request Examples

POST https://classification.relativity6.com/marvin2
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "name": "Acme Corporation",
  "state": "CA",
  "address": "123 Main Street",
  "city": "San Francisco",
  "zip": "94105",
  "country": "US",
  "predictionType": "USA_NAICS_2022",
  "description": "A software company specializing in web and mobile applications."
}

Request Body

{
  "name": "Acme Corporation",
  "state": "CA",
  "address": "123 Main Street",
  "city": "San Francisco",
  "zip": "94105",
  "country": "US",
  "predictionType": "USA_NAICS_2022",
  "description": "A software company specializing in web and mobile applications."
}

Parameters

Parameter	Type	Required	Description
name	string	Yes	The business name
state	string	No	State code (e.g., CA, NY)
address	string	No	Street address
city	string	No	City name
zip	string	No	Postal code
country	string	No	Country code
predictionType	string	No	Either 'USA_NAICS_2017', 'USA_NAICS_2022', or 'R6_WORKERS_COMP'. Defaults to 'USA_NAICS_2017'
description	string	No	Optional. Additional context about the business for improved search accuracy. Maximum 300 characters.

Advanced Parameters

predictionType

Specifies which version of the NAICS (North American Industry Classification System) code list to use for predictions.

USA_NAICS_2017:

Uses the 2017 NAICS code list (default)

USA_NAICS_2022:

Uses the 2022 NAICS code list with updated industry categories

R6_WORKERS_COMP:

Returns Workers Compensation class code predictions

description

An optional free-text field (up to 300 characters). Use this to provide additional business context, such as a summary of services, specialties, or other relevant information. This can help improve the accuracy of the search algorithm, especially for ambiguous business names.

Response

The response structure changes based on the predictionType parameter. The prediction object key will be either usa_naics_2017_prediction_hp, usa_naics_2022_prediction_hp, or R6_Workers_comp_prediction_hp.

{
  "usa_naics_2017_prediction_hp": {  // or "usa_naics_2022_prediction_hp" if predictionType is "USA_NAICS_2022"; or "R6_Workers_comp_prediction_hp" if predictionType is "R6_WORKERS_COMP"
    "prediction_a": {
      "code": "541511",
      "title": "Custom Computer Programming Services",
      "accuracy": 0.92
    },
    "prediction_b": {
      "code": "518210",
      "title": "Data Processing, Hosting, and Related Services",
      "accuracy": 0.87
    }
  },
  "keywords": ["software", "development", "web", "application"],
  "company_website": ["acmecorp.com", 0.95],
  "existence_check": {
    "exists": true,
    "evidence_exist": ["acmecorp.com", "linkedin.com/company/acme-corporation", "crunchbase.com/organization/acme-corp"]
  },
  "timestamp": "2023-06-15T14:32:25Z",
  "traceId": "1-64abc123-def456789012345678901234"
}

Workers Comp Response Example

{
  "R6_Workers_comp_prediction_hp": {
    "prediction_a": {
      "code": "8742",
      "title": "Salespersons, Collectors or Messengers—Outside",
      "accuracy": 0.90
    },
    "prediction_b": {
      "code": "5183",
      "title": "Plumbing NOC & Drivers",
      "accuracy": 0.85
    }
  },
  "keywords": ["software", "development", "web", "application"],
  "company_website": ["acmecorp.com", 0.95],
  "existence_check": {
    "exists": true,
    "evidence_exist": ["acmecorp.com", "linkedin.com/company/acme-corporation", "crunchbase.com/organization/acme-corp"]
  },
  "timestamp": "2023-06-15T14:32:25Z",
  "traceId": "1-64abc123-def456789012345678901234"
}

Response Properties

Property	Type	Description
usa_naics_2017_prediction_hp	object	Predictions with top NAICS codes (when predictionType is "USA_NAICS_2017" or not specified)
usa_naics_2022_prediction_hp	object	Predictions with top NAICS codes (when predictionType is "USA_NAICS_2022")
R6_Workers_comp_prediction_hp	object	Workers Compensation class code predictions (when predictionType is "R6_WORKERS_COMP")
keywords	array	Keywords extracted from company data
company_website	array	Domain name of company website and confidence score [domain, confidence]
existence_check	object	Company existence verification
existence_check.evidence_exist	array	Array of website domains where company evidence was found
timestamp	string	ISO-8601 timestamp of the response
traceId	string	Unique trace identifier for debugging

Error Codes

Status	Description
400	Bad Request - Invalid parameters
403	Forbidden - Invalid API Key or Authentication
429	Too Many Requests - Quota exceeded or plan limit reached
500	Server Error - Something went wrong on our end

Co-Tenant Endpoint

POST

/co-tenant

The Co-Tenant endpoint provides information about businesses that share the same physical location or building. This helps identify other businesses operating at the same address.

Full Request Example

POST https://classification.relativity6.com/co-tenant
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "address": "123 Main Street",
  "city": "San Francisco",
  "state": "CA",
  "postal": "94105"
}

Request Body

{
  "address": "123 Main Street",
  "city": "San Francisco",
  "state": "CA",
  "postal": "94105"
}

Parameters

Parameter	Type	Required	Description
address	string	Yes	Street address of the location
city	string	Yes	City name
state	string	Yes	State code (e.g., CA, NY)
postal	string	Yes	Postal/ZIP code

Response

The response contains co-tenancy data, including geocoding information, structure details, and comprehensive tenant information.

{
  "geocode": {
    "lat": 35.08225579999999,
    "lng": -80.8773368
  },
  "structure": {
    "structure_polygon": "POLYGON ((-80.87688135199994 35.08437577900003))"
  },
  "tenants": [
    {
      "placekey": "zzw-224@8gf-dqc-8d9",
      "location_name": "Vans",
      "brand_name": "Vans",
      "brand_id": "SG_BRAND_336d95866bf50e8249657647cb15b68c",
      "naics_code": "448210",
      "top_category": "Shoe Stores",
      "sub_category": "Shoe Stores",
      "category_tags": "[\"Accessories\", \"Children's Clothing\", \"Hats\", \"Men's Clothing\", \"Women's Clothing\"]",
      "latitude": 35.082698,
      "longitude": -80.876984,
      "street_address": "11025 Carolina Place Pkwy Ste A25",
      "city": "Pineville",
      "region": "NC",
      "postal_code": "28134",
      "open_hours": "{ \"Mon\": [[\"11:00\", \"19:00\"]], \"Tue\": [[\"11:00\", \"19:00\"]], \"Wed\": [[\"11:00\", \"19:00\"]], \"Thu\": [[\"11:00\", \"19:00\"]], \"Fri\": [[\"11:00\", \"20:00\"]], \"Sat\": [[\"11:00\", \"20:00\"]], \"Sun\": [[\"12:00\", \"18:00\"]] }",
      "domains": "[\"vans.com\"]",
      "phone_number": "+17045448551"
    }
  ]
}

Response Properties

Property	Type	Description
geocode	object	Geocoding information for the location
geocode.lat	number	Latitude of the location
geocode.lng	number	Longitude of the location
structure	object	Structure details of the building
structure.structure_polygon	string	Polygon representation of the building structure
tenants	array	List of businesses at the location
tenants[].placekey	string	Unique place key identifier for the business
tenants[].location_name	string	Name of the business location
tenants[].brand_name	string	Brand name of the business
tenants[].brand_id	string	Unique brand identifier
tenants[].naics_code	string	NAICS classification code
tenants[].top_category	string	Primary business category
tenants[].sub_category	string	Business subcategory
tenants[].category_tags	string	JSON string of category tags
tenants[].latitude	number	Latitude of the business
tenants[].longitude	number	Longitude of the business
tenants[].street_address	string	Street address of the business
tenants[].city	string	City of the business
tenants[].region	string	State/region of the business
tenants[].postal_code	string	Postal code of the business
tenants[].open_hours	string	JSON string of business hours
tenants[].domains	string	JSON string of associated domains
tenants[].phone_number	string	Phone number of the business

Use Cases

Market Research

Understand the business ecosystem around a specific location

Competitive Analysis

Identify competitors or complementary businesses in the same building

Location Intelligence

Assess the commercial viability of a location based on existing tenants

Error Codes

Status	Description
400	Bad Request - Missing required fields (address, city, state, postal)
403	Forbidden - Invalid API Key or Authentication
502	Bad Gateway - Upstream API error
503	Service Unavailable - Configuration error
504	Gateway Timeout - Error communicating with upstream service

Classification Endpoint

POST

/classification

The Classification endpoint provides multi-code business classification supporting NAICS, SIC, MCC, and GL codes. This unified endpoint allows you to request multiple types of industry classification codes in a single request.

Key Features

NAICS 2017 & 2022 Classification

SIC Code Classification

MCC Code Classification

GL Code Classification

Full Request Example

POST https://classification.relativity6.com/classification
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "name": "Acme Corporation",
  "state": "CA",
  "address": "123 Main Street",
  "city": "San Francisco",
  "zip": "94105",
  "country": "US",
  "predictionType": "USA_NAICS_2022",
  "searchIntelligence": "medium",
  "includeNAICS": true,
  "includeSIC": true,
  "includeMCC": false,
  "includeGL": true,
  "NAICSOptions": {
    "numberOfPredictions": 2,
    "predictionLevels": [2, 4, 6]
  },
  "GLOptions": {
    "numberOfPredictions": 2
  }
}

Request Body

{
  "name": "Acme Corporation",
  "state": "CA",
  "address": "123 Main Street",
  "city": "San Francisco",
  "zip": "94105",
  "country": "US",
  "predictionType": "USA_NAICS_2022",
  "searchIntelligence": "medium",
  "includeNAICS": true,
  "includeSIC": true,
  "includeMCC": false,
  "includeGL": true,
  "NAICSOptions": {
    "numberOfPredictions": 2,
    "predictionLevels": [2, 4, 6]
  },
  "SICOptions": {
    "numberOfPredictions": 2
  },
  "MCCOptions": {
    "numberOfPredictions": 2
  },
  "GLOptions": {
    "numberOfPredictions": 2
  }
}

Parameters

Parameter	Type	Required	Description
name	string	Yes	The business name
state	string	Yes	State code (e.g., CA, NY)
address	string	No	Street address
city	string	No	City name
zip	string	No	Postal code
country	string	No	Country code (default: US)
predictionType	string	No	Either 'USA_NAICS_2017' or 'USA_NAICS_2022' (default: USA_NAICS_2017)
searchIntelligence	string	No	'low', 'medium', or 'high' - higher levels use more web search context (default: low)
includeNAICS	boolean	No	Include NAICS codes in response (default: true)
includeSIC	boolean	No	Include SIC codes in response (default: false)
includeMCC	boolean	No	Include MCC codes in response (default: false)
includeGL	boolean	No	Include GL codes in response (default: false)

Classification Options

NAICSOptions

numberOfPredictionsNumber of NAICS predictions to return (default: 2)

predictionLevelsArray of NAICS levels to include: [2, 4, 6] (default: [6])

SICOptions

numberOfPredictionsNumber of SIC predictions to return (default: 2)

MCCOptions

numberOfPredictionsNumber of MCC predictions to return (default: 2)

GLOptions

numberOfPredictionsNumber of GL predictions to return: 1 or 2 (default: 2)

Response

The response contains hierarchical classification codes organized by type, along with company information and evidence URLs.

{
  "codes": {
    "naics": [
      {
        "predictionNumber": 1,
        "codes": [
          {
            "code": "51",
            "title": "Information",
            "confidence": 0.95,
            "level": 2
          },
          {
            "code": "5112",
            "title": "Software Publishers",
            "confidence": 0.92,
            "level": 4
          },
          {
            "code": "511210",
            "title": "Software Publishers",
            "confidence": 0.88,
            "level": 6
          }
        ]
      },
      {
        "predictionNumber": 2,
        "codes": [
          {
            "code": "54",
            "title": "Professional, Scientific, and Technical Services",
            "confidence": 0.87,
            "level": 2
          },
          {
            "code": "5415",
            "title": "Computer Systems Design and Related Services",
            "confidence": 0.84,
            "level": 4
          },
          {
            "code": "541511",
            "title": "Custom Computer Programming Services",
            "confidence": 0.82,
            "level": 6
          }
        ]
      }
    ],
    "sic": [
      {
        "predictionNumber": 1,
        "codes": [
          {
            "code": "7372",
            "title": "Prepackaged Software",
            "confidence": 0.90,
            "level": 4
          }
        ]
      },
      {
        "predictionNumber": 2,
        "codes": [
          {
            "code": "7371",
            "title": "Computer Programming Services",
            "confidence": 0.85,
            "level": 4
          }
        ]
      }
    ],
    "mcc": [],
    "gl": [
      {
        "predictionNumber": 1,
        "codes": [
          {
            "code": "91880",
            "title": "Software Development",
            "confidence": 0.92,
            "level": 5
          }
        ]
      },
      {
        "predictionNumber": 2,
        "codes": [
          {
            "code": "91590",
            "title": "Computer Consulting",
            "confidence": 0.88,
            "level": 5
          }
        ]
      }
    ]
  },
  "keywords": ["SOFTWARE", "DEVELOPMENT", "WEB", "APPLICATION"],
  "companyInfo": {
    "website": "acmecorp.com",
    "websiteConfidence": 0.95,
    "exists": true,
    "evidences": [
      "acmecorp.com",
      "linkedin.com/company/acme-corporation",
      "crunchbase.com/organization/acme-corp"
    ]
  },
  "request": {
    "name": "Acme Corporation",
    "state": "CA",
    "address": "123 Main Street",
    "city": "San Francisco",
    "zip": "94105"
  },
  "responseId": "resp_123abc",
  "timestamp": "2023-06-15T14:32:25Z",
  "executionTime": 2850,
  "traceId": "1-64abc123-def456789012345678901234",
  "requestId": "req_456def"
}

Response Properties

Property	Type	Description
codes	object	Container for all classification code types
codes.naics	array	NAICS code predictions with hierarchical levels
codes.sic	array	SIC code predictions
codes.mcc	array	MCC code predictions
codes.gl	array	GL code predictions
predictionNumber	number	Ranking of the prediction (1 = primary, 2 = secondary, etc.)
codes[].code	string	The classification code
codes[].title	string	Human-readable description of the code
codes[].confidence	number	Confidence score between 0.10 and 0.95
codes[].level	number	Hierarchical level (2/4/6 for NAICS, 4 for SIC/MCC, 5 for GL)
keywords	array	Keywords extracted from company data (uppercase)
companyInfo	object	Company verification and website information
companyInfo.website	string	Primary website domain
companyInfo.websiteConfidence	number	Confidence in the website prediction (0.00-1.00)
companyInfo.exists	boolean	Whether evidence of company existence was found
companyInfo.evidences	array	URLs where company evidence was found
request	object	Original request parameters
responseId	string	Unique response identifier
timestamp	string	ISO-8601 timestamp of the response
executionTime	number	Processing time in milliseconds
traceId	string	AWS X-Ray trace identifier for debugging
requestId	string	Per-invocation correlation ID

Code Type Details

NAICS (North American Industry Classification System)

Hierarchical codes (2, 4, 6 digits) for industry classification used by US, Canada, and Mexico

SIC (Standard Industrial Classification)

4-digit codes used for classifying business establishments by industry type

MCC (Merchant Category Code)

4-digit codes used by payment processors to categorize merchant transactions

GL (General Liability)

5-digit General Liability codes for insurance classification

Error Codes

Status	Description
400	Bad Request - Invalid parameters or missing required fields (name, state)
400	Bad Request - At least one code type must be requested (includeNAICS, includeSIC, includeMCC, or includeGL)
403	Forbidden - Invalid API Key or Authentication
429	Too Many Requests - Rate limit exceeded or quota exceeded
500	Server Error - Internal configuration error
502	Bad Gateway - Upstream provider error or parsing failure