NAV Navbar
Logo
shell python

Introduction

Welcome to the Turn API. Our API is designed to make it easy for you to identify and check individuals for risk management or background check purposes. Our API is a modern REST API and can easily be consumed with any programming language. Examples are included in Python and Javascript, but any language may be used.

Authorization

Turn uses JSON Web Tokens (JWT) keys to allow access to the API. Before making any requests to the API you must request a token. Please request a token by contacting sales.

All API requests to the Turn API must include the JWT in an Authorization header. The format of the header is described below:

Authorization: Bearer <jwt_token>

Where Authorization is the header name, and Bearer jwt_token is the header value.

Location

## Carrier Location
curl -X "POST" "http://api.turning.io/v1/v1/location/carrier" \
     -H "authorization: Bearer <jwt_token>" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
  "obtained_worker_consent": true,
  "phone_number": "3125551212"
}'

# Install the Python Requests library:
# `pip install requests`

import requests
import json


def send_request():
    # Carrier Location
    # POST http://api.turning.io/v1/location/carrier

    try:
        response = requests.post(
            url="http://api.turning.io/v1/location/carrier",
            headers={
                "authorization": "Bearer <jwt_token>",
                "Content-Type": "application/json; charset=utf-8",
            },
            data=json.dumps({
                "obtained_worker_consent": True,
                "phone_number": "(312) 555-1212"
            })
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')


The location endpoint will return the latitude and longitude for a mobile phone number retrieved from the mobile network operator (MNO).

HTTP Request

POST https://api.turning.io/v1/location/carrier

Request Parameters

Parameter Type Description
obtained_worker_consent Boolean Boolean value indicating that you have received consent from the device owner prior to making this request
phone_number string The mobile phone to be checked. This can be passed as a 10 ot 11 digit string with or without formatting.

Person Searches

Person - Asynchronous

curl -X "POST" "https://api.turning.io/v1/person/search" \
     -H "authorization: Bearer <jwt_token>" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
  "first_name": "alec",
  "last_name": "sadler",
  "phone_number": "16045551212",
  "ssn": "100101000",
  "email": "alec@sadler.ca"
  "callback_url": "https://my_unique_url.my_domain.com/turn_response",
}'

Response:

200
{
  "uuid": "e6b58c00-de7a-4ad1-b162-e22d7798f990"
}

The Asynchronous Person Search endpoint operates similarly to the synchronous search but should be used for most production requests. Rather than returning an inline response, requests made with this endpoint will return a unique UUID as a response. The full person response will then be returned asynchronously via HTTP POST to an endpoint that is specified as an additional callback_url parameter in the original requrest. The UUID will be included as an additional key:value pair in the response, in order to tie requests back to their responses.

HTTP Request

POST https://api.turning.io/v1/person/search_async

Request Parameters

Parameter Required Description
first_Name true Legal first name of the person to check
last_name true Legal last name of the person to check
phone_number true Mobile phone number of the person to check
ssn false Social security number of the person to check
email true The email of the person to check

Asynchronous Callback Response

200
{
  "request_uuid": "string",
  "checks": {
    "addresses": [
      {
        "address1": "string",
        "address2": "string",
        "city": "string",
        "first_seen": "string",
        "last_seen": "string",
        "state": "string",
        "zip": "string"
      }
    ],
    "aliases": [
      {
        "first_name": "string",
        "last_name": "string",
        "middle_name": "string"
      }
    ],
    "bankruptcies": [
      {
        "assets_available": "string",
        "case_number": "string",
        "case_status": "string",
        "case_status_date": "string",
        "claim_date": "string",
        "closed_date": "string",
        "converted_date": "string",
        "court_district": "string",
        "court_id": "string",
        "discharge_date": "string",
        "dismissal_date": "string",
        "file_date": "string",
        "law_firm": "string",
        "notice_type": "string",
        "objection_date": "string",
        "reopened_date": "string",
        "report_date": "string",
        "status_date": "string",
        "transferred_date": "string",
        "trustee_name": "string",
        "voluntary": "string",
        "withdrawn_date": "string"
      }
    ],
    "criminal": [
      {
        "a_k_as": "string",
        "arrest_date": "string",
        "arresting_agency": "string",
        "birth_address": "string",
        "birth_place": "string",
        "build": "string",
        "business_name": "string",
        "business_token": "string",
        "case_number": "string",
        "case_type": "string",
        "charges_filed_date": "string",
        "citizenship": "string",
        "classification": "string",
        "complexion": "string",
        "conviction_date": "string",
        "conviction_place": "string",
        "counts": "string",
        "county": "string",
        "court": "string",
        "crime_county": "string",
        "crime_type": "string",
        "current_age": "string",
        "degree_of_offense": "string",
        "disposition": "string",
        "disposition_date": "string",
        "drivers_license_issuing_state": "string",
        "drivers_license_number": "string",
        "employer": "string",
        "employer_address": "string",
        "ethnicity": "string",
        "eyes": "string",
        "f_e_i_number": "string",
        "fines": "string",
        "gender": "string",
        "hair": "string",
        "hair_length": "string",
        "height": "string",
        "is_sex_offender": "string",
        "marital_status": "string",
        "military_service": "string",
        "occupation": "string",
        "offense_code": "string",
        "offense_date": "string",
        "offense_description1": "string",
        "other_addresses": "string",
        "other_dates_of_birth": "string",
        "picture_url": "string",
        "plea": "string",
        "predator": "string",
        "probation": "string",
        "registration_date": "string",
        "registration_end_date": "string",
        "report_token": "string",
        "scars_marks": "string",
        "sentence": "string",
        "skin_tone": "string",
        "source_state": "string",
        "status": "string",
        "status_date": "string",
        "victim": "string",
        "victim_age": "string",
        "victim_gender": "string",
        "victim_is_minor": "string",
        "violation": "string",
        "violation_date": "string",
        "weight": "string"
      }
    ],
    "judgements": [
      {
        "abstract_issued_date": "string",
        "action": "string",
        "alias_name_type": "string",
        "alt_court_case_number": "string",
        "attorney_business_name": "string",
        "attorney_business_token": "string",
        "attorney_report_token": "string",
        "back_support_amount": "string",
        "business_name": "string",
        "business_token": "string",
        "claim_date": "string",
        "closed_date": "string",
        "converted_date": "string",
        "court_case_number": "string",
        "court_name": "string",
        "creditor_name": "string",
        "damar_document_type": "string",
        "deed_category_type": "string",
        "discharge_date": "string",
        "dismissal_date": "string",
        "driver_license_number": "string",
        "driver_license_state": "string",
        "filing_date": "string",
        "filing_location": "string",
        "filing_type": "string",
        "installment_judgment_indicator": "string",
        "interest_rate": "string",
        "objection_date": "string",
        "plaintiff_name": "string",
        "recording_book_number": "string",
        "recording_date": "string",
        "recording_number": "string",
        "recording_page_number": "string",
        "release_date": "string",
        "reopened_date": "string",
        "report_date": "string",
        "stay_ordered_date": "string",
        "stay_ordered_indicator": "string",
        "total_judgment_amount": "string",
        "transferred_date": "string",
        "withdrawn_date": "string"
      }
    ],
    "liens": [
      {
        "amount": "string",
        "case_number": "string",
        "court": "string",
        "damar_document_type": "string",
        "deed_category_type": "string",
        "filing_date": "string",
        "filing_location": "string",
        "filing_type": "string",
        "kind_of_tax": "string",
        "lien_issuing_agency": "string",
        "plaintiff": "string",
        "recording_date": "string",
        "release_date": "string",
        "tax_lien_date": "string",
        "tax_lien_serial_lien_certificate_number": "string",
        "tax_period_maximum": "string",
        "tax_period_minimum": "string"
      }
    ],
    "location": {
      "lat": 0,
      "lon": 0,
      "source": "string"
    },
    "vehicles": [
      {
        "make": "string",
        "model": "string",
        "tag": "string",
        "vin": "string",
        "year": "string"
      }
    ]
  },
  "current_address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "first_seen": "string",
    "last_seen": "string",
    "state": "string",
    "zip": "string"
  },
  "date_of_birth": "string",
  "device": {
    "account_type": "string",
    "carrier": {
      "accountType": "string",
      "activationDate": "string",
      "name": "string",
      "primaryAccount": true,
      "serviceType": "string"
    },
    "imei": "string",
    "make": "string",
    "model": "string"
  },
  "disclaimer": "string",
  "first_name": "string",
  "last_name": "string",
  "ssn": "string"
}

When making an async request, the response will be returned to the url specified in the callback_url parameter. The value in the request_uuid key will match the UUID returned in the response to the original request.

Person - Synchronous

## Person Search - Sync
curl -X "POST" "https://api.turning.io/v1/person/search" \
     -H "authorization: Bearer <jwt_token>" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d $'{
  "first_name": "alec",
  "last_name": "sadler",
  "phone_number": "13125551212",
  "ssn": "100101000",
  "email": "alec@sadtech.ca"
}'
# Install the Python Requests library:
# `pip install requests`

import requests
import json


def send_request():
    # Person Search - Sync
    # POST https://api.turning.io/v1/person/search

    try:
        response = requests.post(
            url="https://api.turning.io/v1/person/search",
            headers={
                "authorization": "Bearer <jwt_token>",
                "Content-Type": "application/json; charset=utf-8",
            },
            data=json.dumps({
                "first_name": "alec",
                "last_name": "sadler",
                "phone_number": "13122036261",
                "ssn": "123-45-6789",
                "email": "alec@sadtech.ca"
            })
        )
        print('Response HTTP Status Code: {status_code}'.format(
            status_code=response.status_code))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

The Person Search endpoint will identify a person via name, phone number and social security number. The specific checks you want to have performed can be passed as additional parameters. This synchronous endpoint should be used primarily for testing purposes, or one-off requests. For production and high volume requests please use the Asynchronous endpoint. These checks are described below:

HTTP Request

POST https://api.turning.io/v1/person/search

Response:


200
OK
        Example Value
        Model
{
  "checks": {
    "addresses": [
      {
        "address1": "string",
        "address2": "string",
        "city": "string",
        "first_seen": "string",
        "last_seen": "string",
        "state": "string",
        "zip": "string"
      }
    ],
    "aliases": [
      {
        "first_name": "string",
        "last_name": "string",
        "middle_name": "string"
      }
    ],
    "bankruptcies": [
      {
        "assets_available": "string",
        "case_number": "string",
        "case_status": "string",
        "case_status_date": "string",
        "claim_date": "string",
        "closed_date": "string",
        "converted_date": "string",
        "court_district": "string",
        "court_id": "string",
        "discharge_date": "string",
        "dismissal_date": "string",
        "file_date": "string",
        "law_firm": "string",
        "notice_type": "string",
        "objection_date": "string",
        "reopened_date": "string",
        "report_date": "string",
        "status_date": "string",
        "transferred_date": "string",
        "trustee_name": "string",
        "voluntary": "string",
        "withdrawn_date": "string"
      }
    ],
    "criminal": [
      {
        "a_k_as": "string",
        "arrest_date": "string",
        "arresting_agency": "string",
        "birth_address": "string",
        "birth_place": "string",
        "build": "string",
        "business_name": "string",
        "business_token": "string",
        "case_number": "string",
        "case_type": "string",
        "charges_filed_date": "string",
        "citizenship": "string",
        "classification": "string",
        "complexion": "string",
        "conviction_date": "string",
        "conviction_place": "string",
        "counts": "string",
        "county": "string",
        "court": "string",
        "crime_county": "string",
        "crime_type": "string",
        "current_age": "string",
        "degree_of_offense": "string",
        "disposition": "string",
        "disposition_date": "string",
        "drivers_license_issuing_state": "string",
        "drivers_license_number": "string",
        "employer": "string",
        "employer_address": "string",
        "ethnicity": "string",
        "eyes": "string",
        "f_e_i_number": "string",
        "fines": "string",
        "gender": "string",
        "hair": "string",
        "hair_length": "string",
        "height": "string",
        "is_sex_offender": "string",
        "marital_status": "string",
        "military_service": "string",
        "occupation": "string",
        "offense_code": "string",
        "offense_date": "string",
        "offense_description1": "string",
        "other_addresses": "string",
        "other_dates_of_birth": "string",
        "picture_url": "string",
        "plea": "string",
        "predator": "string",
        "probation": "string",
        "registration_date": "string",
        "registration_end_date": "string",
        "report_token": "string",
        "scars_marks": "string",
        "sentence": "string",
        "skin_tone": "string",
        "source_state": "string",
        "status": "string",
        "status_date": "string",
        "victim": "string",
        "victim_age": "string",
        "victim_gender": "string",
        "victim_is_minor": "string",
        "violation": "string",
        "violation_date": "string",
        "weight": "string"
      }
    ],
    "judgements": [
      {
        "abstract_issued_date": "string",
        "action": "string",
        "alias_name_type": "string",
        "alt_court_case_number": "string",
        "attorney_business_name": "string",
        "attorney_business_token": "string",
        "attorney_report_token": "string",
        "back_support_amount": "string",
        "business_name": "string",
        "business_token": "string",
        "claim_date": "string",
        "closed_date": "string",
        "converted_date": "string",
        "court_case_number": "string",
        "court_name": "string",
        "creditor_name": "string",
        "damar_document_type": "string",
        "deed_category_type": "string",
        "discharge_date": "string",
        "dismissal_date": "string",
        "driver_license_number": "string",
        "driver_license_state": "string",
        "filing_date": "string",
        "filing_location": "string",
        "filing_type": "string",
        "installment_judgment_indicator": "string",
        "interest_rate": "string",
        "objection_date": "string",
        "plaintiff_name": "string",
        "recording_book_number": "string",
        "recording_date": "string",
        "recording_number": "string",
        "recording_page_number": "string",
        "release_date": "string",
        "reopened_date": "string",
        "report_date": "string",
        "stay_ordered_date": "string",
        "stay_ordered_indicator": "string",
        "total_judgment_amount": "string",
        "transferred_date": "string",
        "withdrawn_date": "string"
      }
    ],
    "liens": [
      {
        "amount": "string",
        "case_number": "string",
        "court": "string",
        "damar_document_type": "string",
        "deed_category_type": "string",
        "filing_date": "string",
        "filing_location": "string",
        "filing_type": "string",
        "kind_of_tax": "string",
        "lien_issuing_agency": "string",
        "plaintiff": "string",
        "recording_date": "string",
        "release_date": "string",
        "tax_lien_date": "string",
        "tax_lien_serial_lien_certificate_number": "string",
        "tax_period_maximum": "string",
        "tax_period_minimum": "string"
      }
    ],
    "location": {
      "lat": 0,
      "lon": 0,
      "source": "string"
    },
    "vehicles": [
      {
        "make": "string",
        "model": "string",
        "tag": "string",
        "vin": "string",
        "year": "string"
      }
    ]
  },
  "current_address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "first_seen": "string",
    "last_seen": "string",
    "state": "string",
    "zip": "string"
  },
  "date_of_birth": "string",
  "device": {
    "account_type": "string",
    "carrier": {
      "accountType": "string",
      "activationDate": "string",
      "name": "string",
      "primaryAccount": true,
      "serviceType": "string"
    },
    "imei": "string",
    "make": "string",
    "model": "string"
  },
  "disclaimer": "string",
  "first_name": "string",
  "last_name": "string",
  "ssn": "string"
}

Request Parameters

Parameter Required Description
first_Name true Legal first name of the person to check
last_name true Legal last name of the person to check
phone_number true Mobile phone number of the person to check
ssn false Social security number of the person to check
bankruptcy false Returns an array of bankruptcies associated with the persion (if any)
criminal false Returns an array of crimes associated with the person (if any)
liens false Returns an array of liens associated with the person (if any)
location false Returns the latitude/longitude of the mobile phone number provided in the request
mobile_phone false Retrieves carrier and device details for the provided mobile phone number
judgments false Returns an array of judgments against the person (if any)
vehicles false Returns an array of vehicles owned by the person (if any)
watchlist true Returns an array of watchlists the person appears on and associated details

Person Search Errors

404
{
  "error": {"code":"10", "message":"the text of the error message"}
}

See below on the right for errors that will be displayed in certain circumstances.

Error Code HTTP Code Description
10 404 SSN was not provided and the worker could not be identified from the elements included. Please retry with the SSN as an added parameter.
11 404 The worker could not be uniquely identified.
12 422 Missing required parameter. Please retry the request including the attribute(s) referenced in the error message.

Dashboard Webhook Response

Response:

200
{
 "team_member_email": "contact@turning.io",
 "original_state": "pending",
 "dashboard_url": "http://partners.turning.io/workers/623580e8-9a76-462f-acc9-2a190be182fa",
 "event_id": "11c42854-364e-481e-8e9b-22c21e9edeea",
 "state": "approved",
 "timestamp": 1527800278.0,
 "worker_email": "alec@sadtech.ca",
 "worker_id": "623580e8-9a76-462f-acc9-2a190be182fa"
}

After an automatic or manual change of candidate state on the Turn Partner Dashboard, a webhook will be POSTed to any configured endpoint. The format of that endpoint is described here. Of particular note is the ‘original_state’ and ‘state’ or current state of the candidate. If an candidate is manually approved or rejected by a team member in the dashboard, the webook will also be sent allowing furuther automation of your onboarding process.