CRED Enterprise API Documentation

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
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 JWT Token (User Session Token)

Used only to create and rotate API keys. Short-lived; not used for application workloads.

HTTP

Authorization: Bearer <CRED_JWT_TOKEN>

3.2 API Key Creation

Endpoint: POST /auth/graphql

GraphQL

mutation {
  createApiKey(input: { name: "My API Key" })
}

Optional expiration:

mutation {
  createApiKey(input: { name: "My API Key", expiresInDays: 30 })
}

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
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 Filters (`InputCompanySearchFilters`)

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)

6. Examples

Person Search

query {
  personsConnection(
    first: 2
    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 {
  companiesConnection2(
    first: 3
    searchFilters: {
      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

Limit Type	Policy
API key rate limit	100 req per 60 seconds
Default key validity	14 days
Max custom validity	Deployment-configured maximum

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