API Authentication

Every request carries an API key in the X-API-Key header. Each key has its own permissions, so every integration can have exactly the access it needs.

Creating an API Key

Sign in to the portal and go to Admin › API Key Management.
Add a key, give it a name you will recognize, and choose its permissions.
Copy the key. It is shown only once, when it is created, so store it in your secrets manager straight away.

Give each integration its own key. You can then revoke or replace one without touching the others.

Sending Your Key

Send the key in the X-API-Key header on every request, over HTTPS, with a JSON content type:

curl -X POST https://www.tincomply.com/api/v1/validate/irs-tin-name-matching \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tin": "123-12-1234", "name": "JOHN SMITH" }'

import requests

response = requests.post(
    "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"tin": "123-12-1234", "name": "JOHN SMITH"},
)
result = response.json()["irsTinNameMatchingResult"]
print(result["result"], result["message"])

using System.Net.Http.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

var response = await client.PostAsJsonAsync(
    "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching",
    new { tin = "123-12-1234", name = "JOHN SMITH" });

var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

const response = await fetch(
  "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ tin: "123-12-1234", name: "JOHN SMITH" }),
  }
);
const { irsTinNameMatchingResult } = await response.json();
console.log(irsTinNameMatchingResult.result, irsTinNameMatchingResult.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 {
        String body = """
            {
              "tin": "123-12-1234",
              "name": "JOHN SMITH"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://www.tincomply.com/api/v1/validate/irs-tin-name-matching"))
            .header("X-API-Key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        // Parse with your JSON library (Jackson, Gson) and read irsTinNameMatchingResult.
        System.out.println(response.body());
    }
}

package main

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

func main() {
	body := []byte(`{
	  "tin": "123-12-1234",
	  "name": "JOHN SMITH"
	}`)

	req, err := http.NewRequest("POST", "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching", bytes.NewReader(body))
	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
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		log.Fatal(err)
	}
	fmt.Println(data["irsTinNameMatchingResult"])
}

$body = @'
{
  "tin": "123-12-1234",
  "name": "JOHN SMITH"
}
'@

$response = Invoke-RestMethod -Method Post `
    -Uri "https://www.tincomply.com/api/v1/validate/irs-tin-name-matching" `
    -Headers @{ "X-API-Key" = "YOUR_API_KEY" } `
    -ContentType "application/json" `
    -Body $body

$response.irsTinNameMatchingResult

Always send Content-Type: application/json (and ideally Accept: application/json). Without one of them the same URL responds with an HTML page instead of JSON.

Permissions

Permission	Grants access to
Validate	`validate` and every per-service validation endpoint
History	`history` and `request-details`

A key that only submits checks needs Validate. Add History when the same integration reads results back later, for example to pick up a pending result or to reveal an EIN.

Authentication Errors

Every authentication problem returns HTTP 401 with a message that says which one it is:

Message	Cause
`API key required. Send your key in the X-API-Key header.`	No key, or an empty one, was sent.
`Invalid API Key`	The key is not recognized. It may have been mistyped or revoked.
`API key does not have permissions to view this endpoint`	The key is valid but lacks the permission this endpoint needs.

Other status codes are on the Errors & service status page.