CRED Enterprise API Documentation

Commercial Data Platform – Integration Guide

1. Overview

The CRED Commercial Platform exposes a secure, high-availability GraphQL API designed for enterprise-scale data enrichment, identity resolution, and commercial intelligence workflows.

This guide provides an end-to-end implementation blueprint covering:

Authentication
API key lifecycle management
Filtering and search capabilities
Schema reference

This documentation is optimized for:

Platform engineering teams
Solution architects
Enterprise IT stakeholders

2. Environments

Environment	Base URL	Purpose
Staging	`https://api-staging.external.credplatform.com/graphql`	Live datasets, testing calls
Production	`https://api.external.credplatform.com/graphql`	Live datasets, production workloads

All functionality is consistent across environments except dataset size and SLA guarantees.

3. Authentication & Access Control

The platform supports a two-step authentication model designed for enterprise governance.

3.1 User Authentication (Login)

First, authenticate with your credentials to obtain a JWT token.

Mutation:

mutation AuthenticateUser($input: AuthenticateUserInput!) {
  authenticateUser(input: $input) {
    token
  }
}

Variables:

{
  "input": {
    "email": "your.email@example.com",
    "password": "your_password"
  }
}

Response:

{
  "data": {
    "authenticateUser": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

3.2 API Key Creation

Use the JWT token from authentication to create an API key.

HTTP Header:

Authorization: Bearer <JWT_TOKEN>

Mutation:

mutation CreateApiKey($input: CreateApiKeyInput!) {
  createApiKey(input: $input)
}

Note: The expiresInDays field is optional. If not specified, the API key will default to 14 days validity (see Rate Limiting & Governance for details).

Variables:

{
  "input": {
    "name": "My API Key",
    "expiresInDays": 30
  }
}

Example without expiration (uses default 14 days):

{
  "input": {
    "name": "My API Key"
  }
}

Response:

{
  "data": {
    "createApiKey": "cred_xxxxx..."
  }
}

!!! warning "API Key Security" API keys are shown only once — store securely.

4. Authorization for API Requests

Endpoint: POST /graphql

HTTP

Authorization: Bearer cred_<YOUR_API_KEY>
Content-Type: application/json

5. Filter Fields

Use these fields in searchFilters:

Comparison Operators

IS_ANY_OF - Matches any of the provided values (default for inclusion filters)
IS_NOT_ANY_OF - Excludes any of the provided values
IS_ALL_OF - Matches all of the provided values
BETWEEN - Matches values within a range (requires 2 values)
MORE_THAN - Greater than
MORE_OR_EQUALS_THAN - Greater than or equal to
LESS_THAN - Less than
LESS_OR_EQUALS_THAN - Less than or equal to

Person Filters (`InputPersonsSearchFilters`)

Identity:

identity - Search by name or role
name - Search by full name

Demographics:

age - Filter by age range
birthDate - Filter by birth date
gender - Filter by gender

Location:

location - Filter by location
country - Filter by country
regionId - Filter by region ID

Salary:

salary - Filter by salary (maps to grossSalary)
grossSalary - Filter by gross salary
netSalary - Filter by net salary

Skills & Education:

skills - Filter by skills
educationLevel - Filter by education level

Other:

languageIds - Filter by language IDs

Company Connection Filters

`searchFilters` (`InputCompanySearchFilters`)

keywords - Text-based search across company data (string)
country - Filter by country (accepts country names or IDs: ["United States", "USA"] or [234])
headquarters - Filter by headquarters location (accepts location names or IDs: ["Silicon Valley"] or [234])
industry - Filter by industry (array of strings: ["IT", "Technology"])
location - Filter by location (accepts location names or IDs: ["New York"] or [234])
region - Filter by region (accepts region names or IDs: ["California"] or [1])
numberOfEmployees - Filter by number of employees (integer)
employeeCount - Filter by number of employees - friendly name (integer, can be used with BETWEEN)
revenue - Filter by revenue (integer, can be used with BETWEEN)

`topMarkets`

Filter companies by their top markets (regions where they operate). Accepts region names (e.g., ["United States", "France"]). Uses IS_ANY_OF (default) or IS_NOT_ANY_OF comparison.

`officeLocation`

Filter companies by office locations (regions where they have offices). Accepts region names (e.g., ["United States", "France"]). Uses IS_ANY_OF (default) or IS_NOT_ANY_OF comparison.

Note: Both topMarkets and officeLocation accept region names as strings, which are automatically converted to internal region IDs. The comparison field is optional and defaults to IS_ANY_OF if not specified.

6. Examples

Person Search

query {
  personConnection(
    searchFilters: {
      identity: [{ values: ["John"], comparison: "IS_ANY_OF" }]
      name: [{ values: ["John"], comparison: "IS_ANY_OF" }]
      gender: [{ values: ["MALE", "FEMALE"], comparison: "IS_ANY_OF" }]
      age: [{ values: ["1980-01-01", "2024-12-31"], comparison: "BETWEEN" }]
      birthDate: [{ values: ["1980-01-01", "2024-12-31"], comparison: "BETWEEN" }]
      location: [{ values: [234, 235], comparison: "IS_ANY_OF" }]
      regionId: [{ values: [234, 235], comparison: "IS_ANY_OF" }]
      country: [{ values: [234], comparison: "IS_ANY_OF" }]
      languageIds: [{ values: [1, 2], comparison: "IS_ANY_OF" }]
      salary: [{ values: [50000000, 500000000], comparison: "BETWEEN" }]
      grossSalary: [{ values: [50000000], comparison: "MORE_OR_EQUALS_THAN" }]
      netSalary: [{ values: [40000000], comparison: "MORE_OR_EQUALS_THAN" }]
      skills: [{ values: ["JavaScript", "TypeScript"], comparison: "IS_ANY_OF" }]
      educationLevel: [{ values: ["POSTGRADUATE_MASTERS", "PHD"], comparison: "IS_ANY_OF" }]
    }
  ) {
    edges {
      node {
        id
        name
        firstName
        lastName
        skills
        gender
        categoryIds
        age
        languages {
          id
          name
        }
        identifiers {
          name
          value
        }
        salary {
          grossSalary {
            value
            currency
            multiplier
            isVerified
            localCurrency
            localCurrencyValue
            localCurrencyValueMultiplier
          }
          grossSalaryLowerRange {
            value
            currency
            multiplier
            isVerified
            localCurrency
            localCurrencyValue
            localCurrencyValueMultiplier
          }
          grossSalaryUpperRange {
            value
            currency
            multiplier
            isVerified
            localCurrency
            localCurrencyValue
            localCurrencyValueMultiplier
          }
        }
      }
      cursor
    }
    totalCount
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Company Search

query {
  companiesConnection(
    topMarkets: [
      {
        comparison: IS_ANY_OF
        values: ["United States", "Canada"]
      }
    ]
    officeLocation: [
      {
        comparison: IS_NOT_ANY_OF
        values: ["China"]
      }
    ]
    searchFilters: {
      keywords: "software development"
      revenue: [{ values: [1000000000, 5000000000], comparison: "BETWEEN" }]
      numberOfEmployees: [{ values: [500], comparison: "MORE_THAN" }]
      employeeCount: [{ values: [100, 1000], comparison: "BETWEEN" }]
      industry: [{ values: ["IT", "Technology"], comparison: "IS_ANY_OF" }]
      country: [{ values: ["United States", "USA"], comparison: "IS_ANY_OF" }]
      region: [{ values: ["California"], comparison: "IS_ANY_OF" }]
      location: [{ values: ["New York"], comparison: "IS_ANY_OF" }]
      headquarters: [{ values: ["Silicon Valley"], comparison: "IS_ANY_OF" }]
    }
  ) {
    edges {
      node {
        id
        name
        websiteUrl
        parentCompanyId
        isPublic
        hasSubsidiary
        imageUrl
        marketCap {
          value
          currency
          multiplier
          isVerified
          localCurrency
          localCurrencyValue
          localCurrencyValueMultiplier
        }
        marketingBudget {
          value
          currency
          multiplier
          isVerified
          localCurrency
          localCurrencyValue
          localCurrencyValueMultiplier
        }
        fundingRaised {
          value
          currency
          multiplier
          isVerified
          localCurrency
          localCurrencyValue
          localCurrencyValueMultiplier
        }
        revenue {
          value
          currency
          multiplier
          isVerified
          localCurrency
          localCurrencyValue
          localCurrencyValueMultiplier
        }
        industry {
          id
          name
        }
        sector {
          id
          name
        }
        country {
          id
          name
          imageUrl
          alpha1Code
          alpha2Code
          alpha3Code
        }
        headquarters
        description
        ticker
        exchange
        foundedYear
        lastFundingDate
        numberOfEmployees
      }
    }
  }
}

7. GraphQL Playground

Creating API Keys

{
  "Authorization": "Bearer <CRED_JWT_TOKEN>"
}

Running Queries

{
  "Authorization": "Bearer cred_<YOUR_API_KEY>"
}

8. API Schema Reference

8.1 Company Object

Field	Description
`id`	Unique company ID
`name`	Name of the company
`imageUrl`	Logo or brand image
`websiteUrl`	Public website
`description`	Corporate description
`headquarters`	HQ location
`ticker`	Stock ticker symbol
`exchange`	Exchange code
`foundedYear`	Founding year
`lastFundingDate`	Date of last funding round
`isPublic`	Public/private flag
`hasSubsidiary`	Subsidiary flag
`parentCompanyId`	Parent entity ID
`numberOfEmployees`	Number of employees
`industry.id`	Industry identifier
`industry.name`	Industry name
`sector.id`	Sector identifier
`sector.name`	Sector name
`country.id`	Country identifier
`country.name`	Country name
`country.imageUrl`	Country flag image URL
`country.alpha1Code`	ISO 3166-1 alpha-1 code (e.g., "US")
`country.alpha2Code`	ISO 3166-1 alpha-2 code
`country.alpha3Code`	ISO 3166-1 alpha-3 code (e.g., "USA")
`revenue.value`	Revenue value
`revenue.currency`	Currency code
`revenue.multiplier`	Value multiplier (e.g., "MILLIONS")
`revenue.isVerified`	Whether the value is verified
`revenue.localCurrency`	Local currency code
`revenue.localCurrencyValue`	Value in local currency
`revenue.localCurrencyValueMultiplier`	Local currency multiplier
`marketCap`	Market capitalization (same structure as revenue)
`marketingBudget`	Marketing budget (same structure as revenue)
`fundingRaised`	Total funding raised (same structure as revenue)

8.2 Person Object

Field	Description
`id`	Person ID
`firstName`	First name
`lastName`	Last name
`name`	Full name
`gender`	Gender
`age`	Age
`skills`	List of skills
`categoryIds`	Category identifiers
`languages.id`	Language identifier
`languages.name`	Language name
`identifiers.name`	Identifier name (e.g., "LinkedIn", "Twitter")
`identifiers.value`	Identifier value (URL or handle)
`salary.grossSalary.value`	Gross salary value
`salary.grossSalary.currency`	Currency code
`salary.grossSalary.multiplier`	Value multiplier (e.g., "THOUSANDS")
`salary.grossSalary.isVerified`	Whether the value is verified
`salary.grossSalary.localCurrency`	Local currency code
`salary.grossSalary.localCurrencyValue`	Value in local currency
`salary.grossSalary.localCurrencyValueMultiplier`	Local currency multiplier
`salary.grossSalaryLowerRange`	Lower range of gross salary (same structure as grossSalary)
`salary.grossSalaryUpperRange`	Upper range of gross salary (same structure as grossSalary)

9. Error Handling

Scenario	Error Type	Resolution
Missing/expired API key	`UNAUTHENTICATED`	Supply valid API key
Invalid JWT	`FORBIDDEN`	Refresh user session
Invalid GraphQL query	`GRAPHQL_VALIDATION_FAILED`	Fix syntax
Rate limit exceeded	`RATE_LIMIT_EXCEEDED`	Lower frequency

10. Rate Limiting & Governance

API Key Validity

Limit Type	Policy
Default key validity	14 days (if `expiresInDays` is not specified when creating the API key)
Custom validity	Can be set via `expiresInDays` parameter when creating the API key

Rate Limits by Environment

Environment	Policy
Development	All calls (including data queries): 100 req per 60 seconds
Staging	• Non-data calls (queries and mutations): 100 req per 60 seconds • Data query results per call: 1 search result per call • Data query daily limit: 10 calls per day

11. Security & Compliance

Keys have prefix cred_ and are user-scoped
JWTs use strict expiration
API keys must be stored in secret vaults
Production requires TLS
Full audit logs for key activity