RealValidation API Reference

Application Object

class realvalidation.RealValidation(workbooks=None, token=None, output='json', url='', phone_regex='^\d{10}$', staging=False)[source]

RealValidation Application Object

  • workbooks (list) – List of workbook paths to validate against RealValidation DNC API
  • token (str) – RealValidation API Token. Defaults to environmental variable RV_TOKEN
  • output (str) – RealValidation API Output. Defaults to json
  • url (str) – RealValidation API URL. Defaults to
  • phone_regex (str) – Regex to use when validating phone numbers. Defaults to r'^\d{10}$'
  • staging (bool) – If True RealValidation utilizes the Mock API, overrides url parameter

Makes a request to the RealValidation DNC API

Parameters:phone (str) – 10 numerical digits representing a phone number.
Returns:Dictionary representing JSON response from RealValidation DNC API.
Return type:dict
lookup_phone_from_row(row, phone_column_index)[source]

Lookup phone from row at index

  • row (list) – List of strings containing phone
  • phone_column_index (int) – Index/Position of phone in row list

True/False value whether phone is on dnc or not

Return type:



Validates Workbooks against RealValidation DNC API

Returns:Dictionary with values of valid and invalid rows
Return type:dict



Enumerates the phone column from a given row. Uses Regexs

Parameters:row (list) – list of cell values from row
Returns:phone column index enumerated from row
Return type:int

Returns string representation of cell values from row in a list

Parameters:row (list) – list of values
Returns:string representation of cell values from row in a list
Return type:list

Determines if json response from DNC API is on dnc

Parameters:response (dict) – dictionary response from RealValidation DNC API
Returns:True/False value whether response is on DNC or not
Return type:bool

Returns True/False whether value is [Pp]hone or 10 numerical digits only

Parameters:value (str) – Value to determine if phone identifier
Returns:True/False value whether phone is a valid identifier
Return type:bool
realvalidation.utils.sanitize_phone(phone, regex='[^0-9]')[source]

Uses regex sub to sanitize characters from phone

  • phone (str) – Phone string to sanitize
  • regex (regex) – Regex to use to sub characters from string. Defaults to r'[^0-9]'

sanitized phone string

Return type:


realvalidation.utils.write_rows_to_workbook(rows, workbook_path, workbook_name)[source]

Writes row to workbook

  • rows (list) – list of rows to write to workbook
  • workbook_path (str) – Path to write workbook to
  • workbook_name (str) – Name of the workbook


exception realvalidation.errors.InvalidJSONResponseError[source]

Raised when we couldn’t decode a JSON response from a RealValidation API Request

exception realvalidation.errors.InvalidPhoneFormatError[source]

Raised when a phone string doesn’t match PHONE_REGEX

exception realvalidation.errors.InvalidTokenError[source]

Raised when a token couldn’t be enumerated. Tokens can passed as a parameter when initializing a RealValidation object or by setting the RV_TOKEN environmental variable before execution.

exception realvalidation.errors.RealValidationError[source]

Base class for exceptions in this module.

exception realvalidation.errors.ResponseCodeNotOkError[source]

Raised when RESPONSECODE in a RealValidation JSON response does not equal OK