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
{
  "checks": {
    "addresses": [
      {
        "county": "COOK",
        "zip4": "1111",
        "city": "CHICAGO",
        "state": "IL",
        "address1": "1234 MAIN ST",
        "zip": "60601"
      }
    ],
    "criminal": "clear",
    "mvr": null,
    "sex_offender": "clear",
    "watchlist": "clear",
    "ssn": {
      "status": "valid",
      "name_status": "matched",
      "issue_date": "IN THE YEAR 1996-1997",
      "issue_state": "IL",
      "deceased_date": null,
      "dob_status": "matched",
      "is_deceased": false,
      "is_random": false,
      "number": "*****1111"
    }
  },
  "current_address": {
    "city": "CHICAGO",
    "state": "IL",
    "last_seen": "2019-04-01",
    "first_seen": "2002-09-01",
    "address1": "1234 MAIN ST",
    "zip": "60647"
  },
  "date_of_birth": "1994-01-01",
  "name": "David Lee",
  "license_number": "",
  "license_state": "",
  "email": "david@turning.io",
  "partner_worker_status": "approved",
  "dashboard_url": "https://partners.turning.io/workers/a1e714e8-f839-4f8d-b4ec-1a50db08ffef",
  "turn_id": "C1751582767",
  "reference_id": "0987-ABDC",
  "callback_uuid": "f9285ee8-11dd-4c67-a1b4-693bad15c130",
  "worker_uuid": "a1e714e8-f839-4f8d-b4ec-1a50db08ffef"
}

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.

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",
 "reference_id": "candidate_97455633",
 "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.

Resend Email Invite

curl -X "POST" "https://api.turning.io/v1/fcra/<turn_id>/email/consent/resend" \
     -H 'Authorization: Bearer <jwt_token>'

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

import requests


def send_request():
    # Resend Invite
    # POST https://api.turning.io/v1/fcra/<turn_id>/email/consent/resend

    try:
        response = requests.post(
            url="https://api.turning.io/v1/fcra/<turn_id>/email/consent/resend",
            headers={
                "Authorization": "Bearer <jwt_token>",
            },
        )
        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')

A candidate may miss or not respond to the email invitation to complete a background check. In this case it is possible to programmatically resend the email invitation. Pass in the Turn ID in the endpoint URL above. A 200 Success response will be returned when successful.

200

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.

Possible Webhook States

State Description
Initiated Check has been started via the API but an automated email was NOT sent to the candidate by Turn
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
Pending The candidate is awaiting a hiring decision
Approved Either auto-approved if report is clear, or manually approved
Withdrawn The background check has been abandoned because the candidate did not respond to the Turn Compliance team, or for other reasons. A check can be withdrawn for any reason from the Partner Dashboard
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
Withdrawn The candidate has been removed from the background check process
shell python