Platform API Documentation

INTRODUCTION

Getting Started

Welcome to the Relativity6 Platform API documentation. This guide provides information on how to integrate with our core platform services.

Base URL

https://api.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

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://api.relativity6.com/business/risk
Content-Type: application/json
Authorization: Bearer mt_abc123...

{
  "company_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

Health Check Endpoint

GET

/health

This endpoint provides a simple health check to verify that the API is operational. It requires authentication via the x-api-key header.

Example Request

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

Response

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

Response Properties

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	The current running version of the API service.
environment	string	The deployment environment (e.g., development, staging, production).

Business Risk API

POST

/business/risk

The Business Risk API provides comprehensive business intelligence and risk assessment. This endpoint aggregates data from multiple sources to deliver firmographic information, online presence analysis, public filings, digital asset health scores, corporate stability assessment, and custom risk flags.

Comprehensive Business Intelligence

This API combines data from multiple authoritative sources to provide a complete risk profile including industry classification, financial indicators, digital presence analysis, and compliance information.

Example Request

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

{
  "company_name": "Acme Corporation",
  "domain": "acmecorp.com",
  "address": "123 Main Street",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94105",
  "country": "US"
}

Request Body

{
  "company_name": "Acme Corporation",
  "domain": "acmecorp.com",
  "address": "123 Main Street",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94105",
  "country": "US"
}

Parameters

Parameter	Type	Required	Description
company_name	string	Yes	The legal business name to search for
domain	string	No	Company website domain (e.g., "example.com")
address	string	No	Street address
city	string	No	City name
state	string	No	State or province code (e.g., "CA", "NY")
zip	string	No	Postal or ZIP code
country	string	No	Country code (defaults to "US")

Response

The response contains comprehensive business data organized into logical sections, along with verification results, execution metadata, and data quality metrics.

{
  "company": {
    "firmographic": {
      "industryClassification": {
        "naics": {
          "primary": {
            "naics6": {
              "value": { "code": "541511", "title": "Custom Computer Programming Services" },
              "confidence": 0.92,
              "verificationStatus": "verified"
            },
            "naics4": {
              "value": { "code": "5415", "title": "Computer Systems Design" },
              "confidence": 0.92,
              "verificationStatus": "verified"
            },
            "naics2": {
              "value": { "code": "54", "title": "Professional Services" },
              "confidence": 0.92,
              "verificationStatus": "verified"
            }
          }
        },
        "sic": {
          "value": { "code": "7371", "title": "Computer Programming Services" },
          "confidence": 0.88,
          "verificationStatus": "verified"
        }
      },
      "employeeCount": {
        "value": 150,
        "confidence": 0.85,
        "verificationStatus": "verified"
      },
      "annualRevenue": {
        "value": "$10M - $50M",
        "confidence": 0.75,
        "verificationStatus": "verified"
      },
      "productsAndServices": {
        "value": ["Software Development", "Cloud Services", "Consulting"],
        "confidence": 0.9,
        "verificationStatus": "verified"
      },
      "timeInBusiness": {
        "value": 12,
        "confidence": 0.95,
        "verificationStatus": "verified"
      },
      "headquarters": {
        "value": {
          "streetAddress": "123 Main Street",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        },
        "confidence": 0.92,
        "verificationStatus": "verified"
      }
    },
    "onlinePresence": {
      "companyWebsite": {
        "value": "https://acmecorp.com",
        "confidence": 0.98,
        "verificationStatus": "verified"
      },
      "socialMediaLinks": {
        "value": {
          "linkedin": "https://linkedin.com/company/acmecorp",
          "twitter": "https://twitter.com/acmecorp"
        },
        "confidence": 0.85,
        "verificationStatus": "verified"
      }
    },
    "publicReviews": {
      "reviewSummary": {
        "value": {
          "averageRating": 4.6,
          "reviewCount": 353,
          "platforms": ["Google Maps"]
        },
        "confidence": 0.9,
        "verificationStatus": "verified"
      },
      "reviewAnalysis": {
        "value": {
          "trend_3_months": {
            "value": {
              "averageRating": 5.0,
              "reviewCount": 3,
              "trend": "positive"
            },
            "confidence": 0.85,
            "verificationStatus": "verified"
          },
          "trend_6_months": { "...": "similar structure" },
          "trend_12_months": { "...": "similar structure" }
        },
        "confidence": 0.85,
        "verificationStatus": "verified"
      }
    },
    "publicFilings": {
      "companyRegistration": {
        "value": {
          "incorporationDate": "2012-03-15",
          "registrationStatus": "Active",
          "entityType": "Corporation",
          "filingState": "CA"
        },
        "confidence": 0.95,
        "verificationStatus": "verified"
      },
      "filings": {
        "value": [
          { "number": "C1234567", "register": "California Secretary of State" }
        ],
        "confidence": 0.95,
        "verificationStatus": "verified"
      }
    },
    "digitalAssetHealth": {
      "riskScores": {
        "companyGrowthScore": {
          "value": { "numericValue": 75, "gradeValue": "B", "riskLevel": "Low" },
          "confidence": 0.8,
          "verificationStatus": "verified"
        },
        "websiteRiskPropensityScore": {
          "value": { "numericValue": 85, "gradeValue": "A", "riskLevel": "Low" },
          "confidence": 0.88,
          "verificationStatus": "verified"
        }
      },
      "domainAndSecurityGrades": {
        "websiteSecurityGrade": {
          "value": { "grade": "A", "numericValue": 90, "riskLevel": "Low" },
          "confidence": 0.92,
          "verificationStatus": "verified"
        },
        "sslGrade": {
          "value": { "grade": "A+", "numericValue": 95, "riskLevel": "Low" },
          "confidence": 0.95,
          "verificationStatus": "verified"
        }
      }
    },
    "corporateStability": {
      "stability": {
        "keyPersonnelStability": {
          "value": { "score": "Stable", "reasons": ["Leadership consistent for 5+ years"] },
          "confidence": 0.8,
          "verificationStatus": "verified"
        },
        "businessLineage": {
          "value": { "status": "Established", "foundingDate": "2012-03-15", "businessAge": 12 },
          "confidence": 0.9,
          "verificationStatus": "verified"
        }
      }
    },
    "riskAssessment": {
      "customFlags": {
        "value": [
          {
            "flagType": "Technology Company",
            "reasoning": "Primary business involves software development",
            "riskLevel": "low",
            "category": "industry"
          }
        ],
        "confidence": 0.85,
        "verificationStatus": "verified"
      }
    },
    "summary": {
      "companyName": {
        "value": "Acme Corporation",
        "confidence": 0.98,
        "verificationStatus": "verified"
      },
      "businessDescription": {
        "value": "Software development company specializing in enterprise solutions",
        "confidence": 0.9,
        "verificationStatus": "verified"
      },
      "riskLevel": {
        "value": "Low",
        "confidence": 0.85,
        "verificationStatus": "verified"
      }
    }
  },
  "verifications": {
    "companyName": {
      "value": "Acme Corporation",
      "verified": { "isVerified": true },
      "originalInput": "Acme Corporation"
    },
    "address": {
      "value": { "streetAddress": "123 Main Street", "city": "San Francisco" },
      "verified": { "isVerifiedAddress": true },
      "originalInput": { "address": "123 Main Street", "city": "San Francisco" }
    }
  },
  "execution": {
    "totalLatency": 2340,
    "completeness": 0.85
  },
  "quality": {
    "totalFields": 45,
    "verifiedFields": 38,
    "unverifiableFields": 4,
    "notSearchedFields": 3,
    "completenessScore": 0.84,
    "verificationEffort": {
      "totalSourcesRun": 5,
      "averageSourcesPerField": 1.2,
      "highConfidenceFields": 32
    }
  }
}

Response Sections

Section	Description
company.firmographic	Industry classification (NAICS, SIC, MCC), employee count, revenue, products/services, time in business, headquarters, owners, and contact information
company.onlinePresence	Company website, social media links, online verification links, and web presence analysis
company.publicReviews	Review summary (average rating, count, platforms) and trend analysis (3, 6, 12 month trends)
company.publicFilings	Company registration details, incorporation status, entity type, and filing records
company.digitalAssetHealth	Risk scores (company growth, infrastructure, website risk) and security grades (SSL, domain classification)
company.corporateStability	Personnel stability assessment, structural changes, business lineage, and corporate timeline
company.riskAssessment	Custom risk flags with reasoning, risk level, and category classification
company.summary	Company name, business description, and overall risk level assessment
verifications	Input verification results for company name, address, and domain
execution	Execution metadata including total latency and data completeness score
quality	Data quality metrics: total/verified/unverifiable fields, completeness score, verification effort

VerifiableField Structure

All data fields in the response follow a consistent VerifiableField structure that provides transparency about data quality and sources:

{
  "value": <T>,                    // The actual data value (or null if not found)
  "confidence": 0.85,              // Confidence score (0.0 to 1.0)
  "sources": [...],                // Array of data sources
  "conflicts": false,              // Whether conflicting data was found
  "verificationStatus": "verified" // "verified" | "unverifiable" | "not_searched" | "pending"
}

Error Codes

Status	Description
400	Bad Request - Missing required 'company_name' parameter or invalid request format
401	Unauthorized - Missing x-api-key header
403	Forbidden - Invalid API Key or insufficient permissions
429	Too Many Requests - Quota exceeded
500	Server Error - Business risk service temporarily unavailable

Flags API

POST

/flags

The Flags API provides configurable hazard analysis and risk assessment for businesses. This endpoint analyzes business information and returns a custom set of flags determined by your organization's requirements.

Configurable Analysis

The flags returned by this API are customized for each client based on their specific risk assessment needs. The available flags and categories are configured during onboarding.

Full Request Example

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

{
  "business_name": "Acme Construction Company",
  "business_address": "123 Industrial Blvd, San Francisco, CA 94107",
  "category_filter": ["High-Risk Activities", "Regulatory/Compliance"],
  "flag_filter": ["Construction", "OSHA violations"]
}

Request Body

{
  "business_name": "Acme Construction Company",
  "business_address": "123 Industrial Blvd, San Francisco, CA 94107",
  "category_filter": ["High-Risk Activities", "Regulatory/Compliance"],
  "flag_filter": ["Construction", "OSHA violations"]
}

Parameters

Parameter	Type	Required	Description
business_name	string	Yes	The name of the business to analyze
business_address	string	Yes	The complete business address including city and state
category_filter	array	No	Optional array of category names to limit analysis to specific risk categories
flag_filter	array	No	Optional array of specific flag names to check for (overrides category_filter)

Response

The response contains the analysis results with detailed information about each identified hazard or risk factor.

{
  "requestId": "flags-1234567890abcdef",
  "business_name": "Acme Construction Company",
  "business_address": "123 Industrial Blvd, San Francisco, CA 94107",
  "hazard_results": [
    {
      "hazard_flag": "Construction",
      "hazard_category": "High-Risk Activities",
      "explanation": "Business appears to be involved in construction activities based on company name and industry classification",
      "confidence_score": 0.95,
      "evidence_link": "https://example.com/evidence-source"
    },
    {
      "hazard_flag": "OSHA violations",
      "hazard_category": "Regulatory/Compliance",
      "explanation": "Recent OSHA violations found for this business location",
      "confidence_score": 0.87,
      "evidence_link": "https://osha.gov/enforcement/results"
    }
  ]
}

Error Codes

Status	Description
400	Bad Request - Missing required fields or invalid filter values
403	Forbidden - Invalid API Key or insufficient permissions
429	Too Many Requests - Rate limit exceeded
500	Server Error - Analysis service temporarily unavailable

SOS API

POST

/sos

The SOS (Secretary of State) API provides comprehensive business incorporation and registration data. This endpoint searches for business entities in state databases and returns detailed information about incorporation status, business identifiers, and official registration records.

Official State Records

This API searches official state business registries to provide authoritative information about business incorporation and legal status.

Full Request Example

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

{
  "name": "Acme Corporation",
  "address": "123 Main Street, San Francisco, CA 94105"
}

Request Body

{
  "name": "Acme Corporation",
  "address": "123 Main Street, San Francisco, CA 94105"
}

Parameters

Parameter	Type	Required	Description
name	string	Yes	The legal business name to search for
address	string	No	Business address to help improve matching accuracy

Response

The response contains detailed business information if a match is found, including incorporation details, identifiers, and addresses.

Success Response (Match Found)

{
  "requestId": "sos-1234567890abcdef",
  "searchedName": "Acme Corporation",
  "searchedAddress": "123 Main Street, San Francisco, CA 94105",
  "matchFound": true,
  "matchChecks": {
    "exactNameMatch": true,
    "exactAddressMatch": false,
    "matchStrength": 0.95,
    "matchedName": "Acme Corporation",
    "matchedAddress": "125 Main Street, San Francisco, CA 94105"
  },
  "entityData": {
    "businessName": "Acme Corporation",
    "aliases": ["Acme Corp", "Acme Industries"],
    "incorporation": {
      "status": "Active",
      "type": "Corporation",
      "foundedDate": "2020-03-15",
      "state": "CA",
      "country": "US"
    },
    "identifiers": [
      {
        "register": "California Secretary of State",
        "number": "C1234567"
      }
    ],
    "addresses": [
      {
        "street": "125 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    ]
  }
}

No Match Response

{
  "requestId": "sos-1234567890abcdef", 
  "searchedName": "Nonexistent Business LLC",
  "searchedAddress": "456 Fake Street, Nowhere, CA 90210",
  "matchFound": false
}

Error Codes

Status	Description
400	Bad Request - Missing required 'name' parameter
403	Forbidden - Invalid API Key or insufficient permissions
429	Too Many Requests - Rate limit exceeded
500	Server Error - Business registry service temporarily unavailable

Property APIs

The Property APIs provide comprehensive property data services including address validation and detailed property information combining characteristics, financial data, and ownership details. All property endpoints use the /property resource path.

Comprehensive Property Intelligence

Access validated address data, detailed property characteristics, financial information, and ownership details from authoritative property databases.

Validate

Standardize and validate US postal addresses

POST /property/validate

Principals & Financials

Get comprehensive property data including characteristics, financial information, and ownership details

POST /property/principals-financials

POST

/property/validate

Validates and standardizes US postal addresses using official USPS data. Returns standardized address components, geographic coordinates, and delivery information.

Request Example

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

{
  "street": "123 Main Street",
  "city": "San Francisco",
  "state": "CA",
  "zipcode": "94105"
}

Parameters

Parameter	Type	Required	Description
street	string	Yes	Primary street address
street2	string	No	Secondary address (apt, suite, etc.)
city	string	No	City name
state	string	No	State abbreviation
zipcode	string	No	ZIP code
candidates	number	No	Max results to return (1-10, default: 1)
match	string	No	Match strategy: "strict", "range", or "invalid" (default: "strict")

Response

{
  "success": true,
  "data": {
    "results": {
      "lookups": [
        {
          "street": "123 Main Street",
          "city": "San Francisco",
          "state": "CA",
          "zipCode": "94105",
          "result": [
            {
              "deliveryLine1": "123 Main St",
              "lastLine": "San Francisco CA 94105-1804",
              "deliveryPointBarcode": "941051804123",
              "components": {
                "primaryNumber": "123",
                "streetName": "Main",
                "streetSuffix": "St",
                "cityName": "San Francisco",
                "state": "CA",
                "zipCode": "94105",
                "plus4Code": "1804"
              },
              "metadata": {
                "latitude": 37.7749,
                "longitude": -122.4194,
                "precision": "Zip9",
                "countyFips": "06075",
                "countyName": "San Francisco",
                "timeZone": "Pacific",
                "utcOffset": -8,
                "obeysDst": true
              }
            }
          ]
        }
      ]
    }
  },
  "requestId": "prop-validate-1234567890abcdef"
}

POST

/property/principals-financials

Provides comprehensive property intelligence by first validating the address, then retrieving detailed property characteristics, financial data, and ownership information. This endpoint combines multiple data sources to deliver a complete property profile in a single request.

Request Example

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

{
  "street": "456 Oak Avenue",
  "city": "Springfield",
  "state": "IL",
  "zipcode": "62701"
}

Parameters

Uses the same parameters as the validate endpoint.

Parameter	Type	Required	Description
street	string	Yes	Primary street address
street2	string	No	Secondary address (apt, suite, etc.)
city	string	No	City name
state	string	No	State abbreviation
zipcode	string	No	ZIP code

Response

The response is organized into logical sections: address validation, property characteristics (physical features), financial data (assessments, taxes), and owner information (ownership details). Address and contact information is not duplicated across sections.

{
  "success": true,
  "data": {
    "address_validation": {
      "delivery_line_1": "456 Oak Ave",
      "last_line": "Springfield IL 62701-1234",
      "components": {
        "primary_number": "456",
        "street_name": "Oak",
        "street_suffix": "Ave",
        "city_name": "Springfield",
        "state_abbreviation": "IL",
        "zipcode": "62701",
        "plus4_code": "1234"
      },
      "metadata": {
        "county_fips": "17167",
        "county_name": "Sangamon",
        "carrier_route": "R032",
        "congressional_district": "13",
        "latitude": 39.7817,
        "longitude": -89.6501,
        "precision": "Zip9",
        "time_zone": "Central",
        "utc_offset": -6,
        "dst": true
      }
    },
    "property_characteristics": {
      "1st_floor_sqft": "1250",
      "acres": "0.2500000",
      "air_conditioner": "central",
      "bathrooms_total": "2.500",
      "bedrooms": "4",
      "building_sqft": "1850",
      "year_built": "1985",
      "stories_number": "2",
      "exterior_walls": "brick_veneer",
      "foundation": "full_basement",
      "garage": "attached",
      "gross_sqft": "2100",
      "heat": "forced_air",
      "heat_fuel_type": "natural_gas",
      "land_use_standard": "single_family_residence",
      "lot_sqft": "10890.00",
      "fireplace": "yes",
      "fireplace_number": "2",
      "flooring": "hardwood",
      "parking_spaces": "2",
      "porch_area": "120",
      "roof_cover": "asphalt_shingle",
      "rooms": "8",
      "structure_style": "colonial",
      "subdivision": "Maple Heights Subdivision",
      "zoning": "R-1"
    },
    "financial_data": {
      "assessed_improvement_value": "185000",
      "assessed_land_value": "45000",
      "assessed_value": "230000",
      "assessor_last_update": "2024-03-15",
      "market_improvement_value": "185000",
      "market_land_value": "45000",
      "market_value_year": "2024",
      "previous_assessed_value": "225000",
      "sale_amount": "210000",
      "sale_date": "2019-06-12",
      "tax_assess_year": "2024",
      "tax_billed_amount": "3450.75",
      "tax_fiscal_year": "2024",
      "total_market_value": "230000",
      "financial_history": [
        {
          "document_type_description": "deed_of_trust",
          "lender_name": "First National Bank of Springfield",
          "mortgage_amount": "168000",
          "mortgage_due_date": "2049-07-01",
          "mortgage_recording_date": "2019-07-15",
          "mortgage_term": "360",
          "mortgage_type": "conventional"
        }
      ]
    },
    "owner_information": {
      "owner_full_name": "Sarah M Johnson",
      "deed_owner_full_name": "Sarah M Johnson",
      "ownership_type": "individual",
      "owner_occupancy_status": "owner_occupied",
      "deed_sale_date": "2019-06-12",
      "deed_sale_price": "210000",
      "ownership_transfer_date": "2019-06-12"
    }
  },
  "requestId": "prop-principals-fin-1234567890abcdef"
}

Response Structure

Section	Description
address_validation	Standardized address components, coordinates, and delivery metadata
property_characteristics	Physical property details: square footage, bedrooms, bathrooms, building features
financial_data	Assessment values, tax information, sale history, and mortgage details
owner_information	Property ownership details, deed information, and transfer history

Error Codes

Status	Description
400	Bad Request - Missing required 'street' parameter
403	Forbidden - Invalid API Key or insufficient permissions
429	Too Many Requests - Rate limit exceeded
500	Server Error - Property data service temporarily unavailable