API Documentation

GraphQL API

Our GraphQL API provides flexible, efficient queries for spam report data with real-time capabilities and precise field selection.

🚀 Why GraphQL?

GraphQL allows you to request exactly the data you need, reducing bandwidth and improving performance. Perfect for mobile apps and complex integrations.

GraphQL Endpoint

POST https://api.numberintelligence.com/v1/graphql

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Schema Overview

The GraphQL schema provides access to spam reports, statistics, and carrier information.

Main Types

type SpamReport {
  id: ID!
  senderNumber: String!
  messageContent: String
  spamType: SpamType!
  reportedAt: DateTime!
  carrierInfo: CarrierInfo!
  confidenceScore: Float!
}

type CarrierInfo {
  name: String!
  country: String!
  networkType: String
}

enum SpamType {
  PHISHING
  SCAM
  MARKETING
  MALWARE
  OTHER
}

type Query {
  spamReports(filters: SpamReportFilters): SpamReportConnection!
  spamStats(metric: StatMetric!, period: DateRange): StatResult!
  topOffenders(limit: Int = 10, period: DateRange): [SpamReport!]!
}

type Subscription {
  newSpamReports(filters: SpamReportFilters): SpamReport!
}

Query Examples

Basic Spam Report Search

query SearchSpamReports {
  spamReports(
    filters: {
      senderNumber: "+15551234567"
      dateRange: {
        start: "2024-01-01T00:00:00Z"
        end: "2024-01-31T23:59:59Z"
      }
      limit: 50
    }
  ) {
    edges {
      node {
        id
        senderNumber
        messageContent
        spamType
        reportedAt
        carrierInfo {
          name
          country
        }
        confidenceScore
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Statistics Query

query GetSpamStats {
  spamStats(
    metric: TOP_SENDERS
    period: {
      start: "2024-01-01T00:00:00Z"
      end: "2024-01-31T23:59:59Z"
    }
  ) {
    metric
    period {
      start
      end
    }
    data {
      ... on TopSendersResult {
        senders {
          senderNumber
          reportCount
          spamTypes
          firstSeen
          lastSeen
        }
      }
    }
  }
}

Real-time Subscription

subscription NewSpamReports {
  newSpamReports(
    filters: {
      spamTypes: [PHISHING, SCAM]
      minConfidenceScore: 0.8
    }
  ) {
    id
    senderNumber
    spamType
    reportedAt
    confidenceScore
  }
}

Advanced Filtering

Use powerful filtering options to find exactly the data you need.

Filter Input Types

input SpamReportFilters {
  senderNumber: String
  senderNumbers: [String!]
  messageContent: String
  spamTypes: [SpamType!]
  carriers: [String!]
  countries: [String!]
  dateRange: DateRange
  minConfidenceScore: Float
  maxConfidenceScore: Float
  limit: Int
  offset: Int
}

input DateRange {
  start: DateTime!
  end: DateTime!
}

Complex Filter Example

query ComplexSearch {
  spamReports(
    filters: {
      spamTypes: [PHISHING, SCAM]
      carriers: ["Verizon", "AT&T"]
      countries: ["US", "CA"]
      minConfidenceScore: 0.9
      dateRange: {
        start: "2024-01-01T00:00:00Z"
        end: "2024-01-31T23:59:59Z"
      }
      messageContent: "urgent"
      limit: 100
    }
  ) {
    edges {
      node {
        senderNumber
        spamType
        confidenceScore
        carrierInfo {
          name
          country
        }
      }
    }
    totalCount
  }
}

Pagination

GraphQL uses cursor-based pagination for efficient data retrieval.

Forward Pagination

query PaginatedResults($after: String) {
  spamReports(
    filters: { limit: 50 }
    after: $after
  ) {
    edges {
      node {
        id
        senderNumber
        spamType
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Error Handling

GraphQL returns errors in a standardized format alongside partial data when possible.

Error Response Example

{
  "data": {
    "spamReports": null
  },
  "errors": [
    {
      "message": "Invalid phone number format",
      "locations": [
        {
          "line": 3,
          "column": 5
        }
      ],
      "path": ["spamReports"],
      "extensions": {
        "code": "INVALID_INPUT",
        "field": "senderNumber"
      }
    }
  ]
}

GraphQL Playground: Explore our interactive GraphQL playground at https://api.numberintelligence.com/v1/graphql/playground to test queries and browse the full schema.