Checks & Pending Results

How API calls are counted, and what to do when a result comes back before its source has answered.

How Checks Are Counted

Each call to a per-service endpoint, such as validate/irs-tin-name-matching, uses one check.
A call to validate also uses one check, whether it runs one service or several.
An EIN lookup by name includes one reveal-ein call for the candidate you choose, at no extra check.
request-details and history return results you already have and do not run anything again.

When a Result Is Not Ready

Almost every result comes back in the same response. When an upstream source, such as the IRS, is unavailable, that service's result has completed: false and TIN Comply retries it automatically. Keep the id from the response and call request-details with it later. Once the result shows completed: true, it is final.

The cURL and Java tabs show the request-details call on its own; the others show the whole flow. request-details needs a key with the History permission.

curl -X POST https://www.tincomply.com/api/v1/request-details \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "BG5CF5Z2q0SwIBmhZylJggxp" }'

import requests

API = "https://www.tincomply.com/api/v1/"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

data = requests.post(API + "validate/irs-tin-name-matching", headers=HEADERS,
                     json={"tin": "123-12-1234", "name": "JOHN SMITH"}).json()
result = data["irsTinNameMatchingResult"]

if not result["completed"]:
    # Store data["id"] with your record. Later, for example in your next scheduled job:
    data = requests.post(API + "request-details", headers=HEADERS, json={"id": data["id"]}).json()
    result = data["irsTinNameMatchingResult"]
    if result["completed"]:
        print(result["result"], result["message"])

using System.Net.Http.Json;
using System.Text.Json;

const string api = "https://www.tincomply.com/api/v1/";
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var response = await client.PostAsJsonAsync(api + "validate/irs-tin-name-matching",
    new { tin = "123-12-1234", name = "JOHN SMITH" });
var data = await response.Content.ReadFromJsonAsync<JsonElement>();
var result = data.GetProperty("irsTinNameMatchingResult");

if (!result.GetProperty("completed").GetBoolean())
{
    // Store the id with your record. Later, for example in your next scheduled job:
    var id = data.GetProperty("id").GetString();
    response = await client.PostAsJsonAsync(api + "request-details", new { id });
    data = await response.Content.ReadFromJsonAsync<JsonElement>();
    result = data.GetProperty("irsTinNameMatchingResult");
    if (result.GetProperty("completed").GetBoolean())
    {
        Console.WriteLine($"{result.GetProperty("result")} {result.GetProperty("message")}");
    }
}

const api = "https://www.tincomply.com/api/v1/";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };
const post = async (path, body) =>
  (await fetch(api + path, { method: "POST", headers, body: JSON.stringify(body) })).json();

let data = await post("validate/irs-tin-name-matching", { tin: "123-12-1234", name: "JOHN SMITH" });
let result = data.irsTinNameMatchingResult;

if (!result.completed) {
  // Store data.id with your record. Later, for example in your next scheduled job:
  data = await post("request-details", { id: data.id });
  result = data.irsTinNameMatchingResult;
  if (result.completed) console.log(result.result, result.message);
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        // The id you stored from the original validate response
        HttpRequest request = HttpRequest.newBuilder(
                URI.create("https://www.tincomply.com/api/v1/request-details"))
            .header("X-API-Key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("{ \"id\": \"BG5CF5Z2q0SwIBmhZylJggxp\" }"))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        // Parse with your JSON library; the result is final once completed is true.
        System.out.println(response.body());
    }
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

const api = "https://www.tincomply.com/api/v1/"

func post(path string, body any) map[string]any {
	payload, err := json.Marshal(body)
	if err != nil {
		log.Fatal(err)
	}
	req, err := http.NewRequest("POST", api+path, bytes.NewReader(payload))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
	return data
}

func main() {
	data := post("validate/irs-tin-name-matching", map[string]string{"tin": "123-12-1234", "name": "JOHN SMITH"})
	result := data["irsTinNameMatchingResult"].(map[string]any)

	if result["completed"] != true {
		// Store data["id"] with your record. Later, for example in your next scheduled job:
		data = post("request-details", map[string]any{"id": data["id"]})
		result = data["irsTinNameMatchingResult"].(map[string]any)
		if result["completed"] == true {
			fmt.Println(result["result"], result["message"])
		}
	}
}

$api = "https://www.tincomply.com/api/v1/"
$headers = @{ "X-API-Key" = "YOUR_API_KEY" }

$data = Invoke-RestMethod -Method Post -Uri ($api + "validate/irs-tin-name-matching") -Headers $headers `
    -ContentType "application/json" -Body '{ "tin": "123-12-1234", "name": "JOHN SMITH" }'
$result = $data.irsTinNameMatchingResult

if (-not $result.completed) {
    # Store $data.id with your record. Later, for example in your next scheduled job:
    $data = Invoke-RestMethod -Method Post -Uri ($api + "request-details") -Headers $headers `
        -ContentType "application/json" -Body (@{ id = $data.id } | ConvertTo-Json)
    $result = $data.irsTinNameMatchingResult
    if ($result.completed) { "$($result.result) $($result.message)" }
}