> ## Documentation Index
> Fetch the complete documentation index at: https://docs.titanx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Score contacts

> Submit contacts for scoring. Scoring is asynchronous: this call returns a `jobId` plus accepted and total record counts and credit usage, not the scores themselves. Scored contacts are delivered later via the `job.contact.scored` webhook. Supports up to 1000 contacts per request.



## OpenAPI

````yaml /api-reference/openapi.json post /api/public/v2/contacts/score
openapi: 3.1.0
info:
  version: 2.0.0
  title: TitanX API
  description: |-
    # TitanX API Documentation

    Welcome to the TitanX API!

    ## Base URL

    ```
    https://app.titanx.io/api/public/v2
    ```

    ## Authentication

    All endpoints require Bearer token authentication:

    ```http
    Authorization: Bearer YOUR_API_KEY
    ```

    ## Response Format

    All endpoints return responses in this consistent format:

    ```json
    {
      "data": { /* Your requested data */ },
      "credits": {
        "creditsCharged": 5,
        "creditsRemaining": 995,
        "costPerPhone": 0.05,
        "phoneCount": 100
      },
      "error": null
    }
    ```
servers:
  - url: https://app.titanx.io
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: v2
    description: ✅ Version 2 API (Current)
    externalDocs:
      description: V2 API Guide
      url: https://docs.titanx.io/api/v2
  - name: v2-contacts
    description: V2 Contact operations - scoring and enrichment with credit tracking
  - name: v2-jobs
    description: V2 Job operations - job management and contact retrieval
  - name: v2-account
    description: V2 Account operations - credits and billing information
  - name: v2-webhooks
    description: >-
      V2 Webhook operations - manage webhook subscriptions for real-time contact
      event notifications
paths:
  /api/public/v2/contacts/score:
    post:
      tags:
        - v2
        - v2-contacts
      summary: Score contacts
      description: >-
        Submit contacts for scoring. Scoring is asynchronous: this call returns
        a `jobId` plus accepted and total record counts and credit usage, not
        the scores themselves. Scored contacts are delivered later via the
        `job.contact.scored` webhook. Supports up to 1000 contacts per request.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2ContactScoreRequestDoc'
      responses:
        '200':
          description: Successful response with contact scores and credit information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ContactScoreResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    V2ContactScoreRequestDoc:
      type: object
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/ScoringContactDoc'
          maxItems: 1000
        scoringType:
          type: string
          enum:
            - lightning
            - titan
          default: lightning
      required:
        - contacts
    V2ContactScoreResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ScoringApiResponse'
        credits:
          $ref: '#/components/schemas/ScoringCreditTransaction'
        error:
          $ref: '#/components/schemas/ScoringErrorInfo'
      required:
        - data
    ScoringContactDoc:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        phone2:
          type: string
        phone3:
          type: string
        phone4:
          type: string
        phone5:
          type: string
        phoneExt:
          type: string
        phoneType:
          type: string
        phone2Type:
          type: string
        phone3Type:
          type: string
        phone4Type:
          type: string
        phone5Type:
          type: string
        title:
          type: string
        companyAccount:
          type: string
        linkedInUrl:
          type: string
        contactCrmId:
          type: string
      required:
        - firstName
        - lastName
      additionalProperties: {}
    ScoringApiResponse:
      type: object
      properties:
        totalRecordCount:
          type: integer
          minimum: 0
        acceptedRecordCount:
          type: integer
          minimum: 0
        jobId:
          type: string
          format: uuid
      required:
        - totalRecordCount
        - acceptedRecordCount
        - jobId
    ScoringCreditTransaction:
      type: object
      properties:
        creditsCharged:
          type: integer
          minimum: 0
        creditsRemaining:
          type: integer
          minimum: 0
        costPerPhone:
          type: number
          minimum: 0
        phoneCount:
          type: integer
          minimum: 0
      required:
        - creditsCharged
        - creditsRemaining
        - costPerPhone
        - phoneCount
    ScoringErrorInfo:
      type: object
      properties:
        rejectedRecordCount:
          type: integer
          minimum: 0
        records:
          type: array
          items:
            $ref: '#/components/schemas/ScoringRejectedDoc'
      required:
        - rejectedRecordCount
        - records
    ScoringRejectedDoc:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        phone2:
          type: string
        phone3:
          type: string
        phone4:
          type: string
        phone5:
          type: string
        phoneExt:
          type: string
        phoneType:
          type: string
        phone2Type:
          type: string
        phone3Type:
          type: string
        phone4Type:
          type: string
        phone5Type:
          type: string
        title:
          type: string
        companyAccount:
          type: string
        linkedInUrl:
          type: string
        contactCrmId:
          type: string
        rejectedReason:
          type: string
      required:
        - rejectedReason
      additionalProperties: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````