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.

Carrier Searches

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.

Customer Attributes

Request:

## Turn Carrier Data
curl "https://api.turning.io/v1/line_identity?account_info=True&name_and_address=True&device_info=True&obtained_worker_consent=True&mdn=<phone_number>&zipcode=<zipcode>" \
     -H 'Authorization: Bearer <jwt token>' \
     -H 'Content-Type: application/json; charset=utf-8'

Response:

{
    "carrier": {
        "original_name": "NEW CINGULAR WIRELESS PCS, LLC - GA",
        "name": "ATT"
    },
    "subscriber": {
        "last_name": "SMITH",
        "subscriber_id": "MND9004636444",
        "midddle_name": "L",
        "email": "smith55@GMAIL.COM",
        "first_name": "JOE"
    },
    "device": {
        "model": "IPHONE 6",
        "imei": "358373067744444",
        "make": "APPLE"
    },
    "account": {
        "primary_acct_holder": "true",
        "service_status": "active",
        "acct_type": "individual",
        "acct_activation_date": "2006-09-28",
        "line_activation_date": "2006-09-28",
        "line_type": "wireless",
        "billing_address": {
            "addr1": "127 JASMINE RD",
            "state": "IA",
            "zip": "52242",
            "city": "IOWA CITY",
            "country": "USA"
        },
        "service_type": "postpaid",
        "acct_tenure": {
            "min": "124"
        }
    },
    "mdn": "13125555555"
}

Request Parameters

Parameter Type Description
account_info boolean Return the account details for the mobile number including account type, account age etc.
name_and_address boolean Will return the name and address associated with the account. If this attributes is set to ‘false’ the billing zip code is not required
device_info boolean Will return device details including manufacturer, model and IMEI
zipcode integer The five digit billing zipcode associated with the mobile number. This is only required if requesting the name and address associate with the account
obtained_worker_consent boolean Consent is required in all cases to obtain this information from the carrier. If false, no data will be returned.

Error Codes

Code Info Message
9000 The request was not processed due to a server error SERVER_ERROR
9001 The request was not processed because the username and/or password was not valid INVALID_AUTH
9002 The request was not processed due to an external server EXT_SERVER_ERROR
9005 The request was not processed because the phone number could not be found MDN_NOT_RESOLVED
9006 The request was not processed because the information is not available from the carrier DATA_NOT_AVAILABLE
9007 Billing Postal Code does not match with carrier’s data INVALID_DATA

Person Searches

Person - Asynchronous

curl -X "POST" "https://api.turning.io/v1/person/search_async" \
     -H 'Authorization: Bearer <jwt_token>' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "email_candidate": "true",
  "redirect_url": "https://turning.io",
  "last_name": "Sadler",
  "reference_id": "ABC12345",
  "email": "contact@turning.io",
  "package_id": "P1234567890",
  "callback_url": "https://somedomain.com/response",
  "phone_number": "18884998876",
  "first_name": "Alec"
}'

Response:

200
{
  "candidate_consent_url": "https://partners.turning.io/consent/khioLNZJ3uSFzeoOa5yBSOFKwymf0A==?email_candidate=True&last_name=Sadler&first_name=Alec&email=contact%40turning.io&phone_number=18884998876&reference_id=ABC12345&redirect_url=https%3A%2F%2Fturning.io",
  "email": "contact@turning.io",
  "email_candidate": true,
  "email_status": {
    "message": "The notification email was delivered successfully",
    "status": 200
  },
  "first_name": "Alec",
  "last_name": "Sadler",
  "message": {
    "code": "9200",
    "message": "The operation completed successfully.",
    "request_uuid": "e4e43472-5a04-48c7-a513-5245f971ed9b"
  },
  "phone_number": "18884998876",
  "redirect_url": "https://turning.io",
  "reference_id": "ABC12345",
  "worker_id": "def4e44d-f3dd-4f02-972d-15fbacb412fe"
}

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
email true The email of the person to check
phone_number true Mobile phone number of the person to check
email_candidate true Boolean value to indicate whether Turn should send an email invitation
callback_url true A URL endpoint to which the response will be POSTed asynchronously
reference_id false An arbitrary metadata value that can be passed. It will be returned in the response and also visible on the background report
package_id false If you are configured with multiple packages of candidate checks, you can pass in the ID of the package here. The package_id is an 11 character string starting with a ‘P’ and followed by 10 digits. If no package_id is passed, the configured default package will be used.
redirect_url false After completion of the background check flow, a candidate will be redirected to the provided URL

Response Details

Reponse Key Description
candidate_consent_url Unique URL to be provided to the candidate for completion of the report
worker_id The Turn ID for the candidate
request_uuid The unique ID for the request

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"
      }
    ],
    "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"
      }
    ],
    "location": {
      "lat": 0,
      "lon": 0,
      "source": "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 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.

Possible Webhook States

State Description
Emailed Candidate has been sent email invitation
Processing Background check is in process. County and/or MVR checks in progress
Consent Report has completed. Awaiting secondary consent from candidate
Approved Either auto-approved if report is clear, or manually approved
Pending__first_notice Pre-adverse action has been initiated
Pending__second_notice Adverse action has been initiated
Rejected The candidate has not disputed the adverse action and has been rejected
Review QA review by Turn team

Data Sharing

These endpoints allow Turn partners to share worker data with Turn. Data may be shared programmatically in two ways:

In each case, the entire data set will be validated before the import is begun. If errors are found in the data, an error code will be returned indicating the line or element number on which the error appears. See Error Codes below.

JSON

curl -X "POST" "https://pre-prod-turning-rest-api.herokuapp.com/v1/public/json_workers" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MjQ3NTU2OTUsInN1YiI6IkJEWEtmcG0ydkQwUDM5ZjJmN3I1alFNNWZRZWFYbUZCcnV5c0lKVkQyd1VpQWI4Tm8xRldhWERUOEUyQ2p5ZXUiLCJhdWQiOiJxZTlhaHE1aUc3ZFRvR3JtY1ZkOVU2cDJhOFdaVWZvPSIsImlzcyI6IiIsImV4cCI6MTU1NjI5MTY5NX0.ClGnkM1UZnETmUYAagpbwaQ1jTAqpxhjMuL9YdDGKDY' \
     -d $'[
     {
       "market": "Chicago",
       "email": "worker1@gmail.com",
       "phone": "312-555-3565",
       "created_on": "13/12/2018",
       "total_lifetime_actions": "1",
       "fullname": "Forrest Gump"
   },
   {
       "market": "Los Angeles",
       "phone": "213-555-6261",
       "rating": " 2.5 Stars",
       "total_lifetime_actions": "10",
       "last_action": "2/20/2018",
       "email": "worker1@gmail.com",
       "created_on": "1/15/2017",
       "fullname": "Jenny Gump"
     }
]'

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

import requests
import json


def send_request():
    # Data Sharing (JSON)
    # POST https://pre-prod-turning-rest-api.herokuapp.com/v1/public/json_workers

    try:
        response = requests.post(
            url="https://pre-prod-turning-rest-api.herokuapp.com/v1/public/json_workers",
            headers={
                "Accept": "application/json",
                "Content-Type": "application/json",
                "authorization": "Bearer <JWT Token>",
            },
            data=json.dumps([
                {
                  "market": "Chicago",
                  "email": "worker1@gmail.com",
                  "phone": "312-555-3565",
                  "created_on": "13/12/2018",
                  "total_lifetime_actions": "1",
                  "fullname": "Forrest Gump"
              },
              {
                  "market": "Los Angeles",
                  "phone": "213-555-6261",
                  "rating": " 2.5 Stars",
                  "total_lifetime_actions": "10",
                  "last_action": "2/20/2018",
                  "email": "worker1@gmail.com",
                  "created_on": "1/15/2017",
                  "fullname": "Jenny Gump"
                }
            ])
        )
        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')

HTTP Request

POST https://api.turning.io/v1/public/json_workers

Request Parameters

Parameter Required Type Description
market True Text The market or city in which the worker is working
fullname True Text The full name of the worker
email True Text (must be formatted as an email) The email address of the worker
phone True Text (Formatting will be stripped) The phone number of the worker
created_on True Date MM/DD/YYYY The date on which the worker was approved to work for your company
first_action False Date MM/DD/YYYY The date on which the worker completed their first task/job etc
last_ action False Date MM/DD/YYYY The data on which the worker completer their most recent taks/job etc
total_lifetime_actions True Date MM/DD/YYYY The total number of tasks/jobs the worker has completed (May be 0 if none)
rating False Text The rating the worker has on your platform (if any). Text ratings are allowed

Response

An HTTP 200 code returned if the request has been accepted.

"status: {code: 200, message: OK}"
"status: {code: 200, message: OK}"

Error Codes

An HTTP 422 code is returned if the payload has been rejected. A JSON message is returned with the specific errors. The key of each object returned is the index of the object with the error (starting at 0). For example see at right.

{
  "0": {
    "email": [
      "Not a valid email address."
    ],
    "phone": [
      "Phone number must be 11 digits and start with 1"
    ]
  },
  "1": {
    "total_lifetime_actions": [
      "Not a valid integer."
    ]
  }
}
{
  "0": {
    "email": [
      "Not a valid email address."
    ],
    "phone": [
      "Phone number must be 11 digits and start with 1"
    ]
  },
  "1": {
    "total_lifetime_actions": [
      "Not a valid integer."
    ]
  }
}

CSV

Worker data may be accepted as a CSV file. The file must follow an explicit format:

  1. market
  2. fullname
  3. email
  4. phone
  5. created_on
  6. first_action
  7. last_action
  8. total_lifetime_actions
  9. rating
curl -X "POST" "https://pre-prod-turning-rest-api.herokuapp.com/v1/public/json_workers" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MjQ3NTU2OTUsInN1YiI6IkJEWEtmcG0ydkQwUDM5ZjJmN3I1alFNNWZRZWFYbUZCcnV5c0lKVkQyd1VpQWI4Tm8xRldhWERUOEUyQ2p5ZXUiLCJhdWQiOiJxZTlhaHE1aUc3ZFRvR3JtY1ZkOVU2cDJhOFdaVWZvPSIsImlzcyI6IiIsImV4cCI6MTU1NjI5MTY5NX0.ClGnkM1UZnETmUYAagpbwaQ1jTAqpxhjMuL9YdDGKDY' \
     -d $'[
     {
       "market": "Chicago",
       "email": "worker1@gmail.com",
       "phone": "312-555-3565",
       "created_on": "13/12/2018",
       "total_lifetime_actions": "1",
       "fullname": "Forrest Gump"
   },
   {
       "market": "Los Angeles",
       "phone": "213-555-6261",
       "rating": " 2.5 Stars",
       "total_lifetime_actions": "10",
       "last_action": "2/20/2018",
       "email": "worker1@gmail.com",
       "created_on": "1/15/2017",
       "fullname": "Jenny Gump"
     }
]'

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

import requests
import json


def send_request():
    # Data Sharing (JSON)
    # POST https://pre-prod-turning-rest-api.herokuapp.com/v1/public/json_workers

    try:
        response = requests.post(
            url="https://pre-prod-turning-rest-api.herokuapp.com/v1/public/json_workers",
            headers={
                "Accept": "application/json",
                "Content-Type": "application/json",
                "authorization": "Bearer <JWT Token>",
            },
            data=json.dumps([
                {
                  "market": "Chicago",
                  "email": "worker1@gmail.com",
                  "phone": "312-555-3565",
                  "created_on": "13/12/2018",
                  "total_lifetime_actions": "1",
                  "fullname": "Forrest Gump"
              },
              {
                  "market": "Los Angeles",
                  "phone": "213-555-6261",
                  "rating": " 2.5 Stars",
                  "total_lifetime_actions": "10",
                  "last_action": "2/20/2018",
                  "email": "worker1@gmail.com",
                  "created_on": "1/15/2017",
                  "fullname": "Jenny Gump"
                }
            ])
        )
        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')

HTTP Request

POST https://api.turning.io/v1/public/csv_workers

Request Parameters

Parameter Required Type Description
market True Text The market or city in which the worker is working
fullname True Text The full name of the worker
email True Text (must be formatted as an email) The email address of the worker
phone True Text (Formatting will be stripped) The phone number of the worker
created_on True Date MM/DD/YYYY The date on which the worker was approved to work for your company
first_action False Date MM/DD/YYYY The date on which the worker completed their first task/job etc
last_ action False Date MM/DD/YYYY The data on which the worker completer their most recent taks/job etc
total_lifetime_actions True Integer The total number of tasks/jobs the worker has completed (May be 0 if none)
rating False Text The rating the worker has on your platform (if any). Text ratings are allowed

Response

"status: {code: 200, message: OK}"
"status: {code: 200, message: OK}"

An HTTP 200 code is returned if the payload has been accepted.

Error Codes

An HTTP 422 code is returned if the CSV has been rejected. A JSON message is returned with the specific errors. The key of each object returned is the row of the object with the error (starting at 0). For example see at right.

{
  "message": {
    "email": [
      "Not a valid email address."
    ]
  },
  "row": 0
}
{
  "message": {
    "email": [
      "Not a valid email address."
    ]
  },
  "row": 0
}