Skip to main content
This page shows you how to use the TitanX Scoring API to score contacts.
Using the latest API? We recommend using the new v2 Contact Scoring API which provides enhanced responses, credit tracking, and better error handling.
The post operation does not currently support deduplication of contacts within a single job or across jobs.

​
Introduction

TitanX has a proprietary scoring algorithm that tells you who your reps should be calling based on the contacts propensity to be reached via the phone increasing connect rates to 25% on average. In practice, for each contact you submit via our API, we will:
  1. Annotate each phone number (phone, phone1, phone2, phone3, and phone4) for each contact with a status (phone_status, phone1_status, phone2_status, phone3_status, and phone4_status) indicating whether the number is high, medium, or low propensity to be reached, or if you have phone data that needs attention / is bad.
  2. Annotate each contact with an overall lead_status, which indicates the highest scoring status across all numbers for that contact.
  3. Return contacts to your callback URL as they are processed

​
Phone Statuses

Each phone number will be annotated with one of the following statuses:
​
phoneStatus
enum
The status of the phone number
IVR stands for Interactive Voice Response, which you may know as a dial tree

​
Lead Statuses

Each record / contact sent will be annotated with the highest scoring phone status across all numbers for that contact. The possible statuses are:
​
leadStatus
enum
The overall status of the contact based on the highest scoring phone status.

​
Scoring Contacts Response

The process of scoring contacts is not instant. When you submit a job, you will receive a response with the following fields:
  • jobId: The ID of the job that was created.
  • acceptedCount: The number of contacts that were accepted.
  • rejected: An array of contacts that were rejected.

​
Why is my contact rejected?

We require every contact to have a firstName, lastName, and at least one valid phone US number_. Any rejected records will include the reason for rejection.

​
Callback Response

When a contact is scored, the callback URL you provide will receive a response with the following fields:
​
contact
PrlContact Object

​
What about International Numbers?

We plan to offer support for international phone numbers in early Q2 2025.

​
Providing a callbackURL

The way you provide your callback URL will depend on how your results should be returned. There are two use cases:

​
Global Callback URL:

If you want all contacts to be returned to the same URL, simply set your callback URL when you generate your API Token. This global setting applies to every contact processed under that token.

​
Per-Contact Callback URL:

If you need contacts to be returned to different URLs, include a callbackURL in each individual contact record you submit. This allows you to override the global setting on a case-by-case basis.