API Endpoint: Request Details

This endpoint retrieves the details of a specific validation request, returning the original request and its results.

POST `/api/v1/request-details`

https://www.tincomply.com/api/v1/request-details

Returns the complete stored result of one earlier validation request: the original request and every result object, in the same shape as the validate response. GET with ?id= also works.

Request body

Field	Type	Description
`id`required	string	The request id returned by a validate call.

Returns 400 when the id is malformed and 404 when no request with that id belongs to your account, both in the url-and-errors format shown on the overview. Requires an API key with the History permission.

What to do with this result

When you see	Do this
A result still has completed false	That source has not answered yet. Call request-details again later.
404	The id is not on your account. Check that you are using a key for the account that made the request.

Sample request

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":"BZ5CF5Z2q0SwIBmhZylJggxp"}'

import requests

response = requests.post(
    "https://www.tincomply.com/api/v1/request-details",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "id": "BZ5CF5Z2q0SwIBmhZylJggxp",
    },
)
response.raise_for_status()
print(response.json())

using System.Text;

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

var body = """
{
  "id": "BZ5CF5Z2q0SwIBmhZylJggxp"
}
""";
var response = await client.PostAsync(
    "https://www.tincomply.com/api/v1/request-details",
    new StringContent(body, Encoding.UTF8, "application/json"));

Console.WriteLine(await response.Content.ReadAsStringAsync());

const response = await fetch("https://www.tincomply.com/api/v1/request-details", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "BZ5CF5Z2q0SwIBmhZylJggxp",
  }),
});
const data = await response.json();
console.log(data);

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 = """
            {
              "id": "BZ5CF5Z2q0SwIBmhZylJggxp"
            }
            """;
        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(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

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

package main

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

func main() {
	body := []byte(`{
	  "id": "BZ5CF5Z2q0SwIBmhZylJggxp"
	}`)

	req, err := http.NewRequest("POST", "https://www.tincomply.com/api/v1/request-details", 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)
}

$body = @'
{
  "id": "BZ5CF5Z2q0SwIBmhZylJggxp"
}
'@

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

$response

Sample response

{
  "id": "BZ5CF5Z2q0SwIBmhZylJggxp",
  "requestedBy": "ERP integration",
  "request": {
    "tin": "XXXXX1234",
    "name": "JOHN SMITH",
    "requestDate": "2026-10-01T20:23:41Z",
    "requestedServices": "irs-tin-name-matching"
  },
  "irsTinNameMatchingResult": {
    "message": "TIN and Name combination does not match IRS records",
    "result": 3,
    "completed": true
  }
}

POST `/api/v1/history`

https://www.tincomply.com/api/v1/history

Lists your previous validation requests, newest first, with a summary result for each service.

Request body

Field	Type	Description
`page`	int	Page number, starting at 1.
`count`	int	Page size.
`search`	string	Optional free-text filter, such as a name or TIN fragment.
`includeApi`	bool	Include requests made with API keys, not only portal requests.

Values for the *ResultType fields

Value	Meaning
`0`	Unrequested
`1`	Unprocessed
`2`	Bad
`3`	Good
`4`	Pending
`5`	Indifferent
`6`	Information

Each item includes a ResultType field only for the services that ran on that request. requestState: 0 unprocessed, 1 in process, 2 processed, 3 retry, 4 failure.

What to do with this result

When you see	Do this
requestState is 0, 1 or 3	Still working. Call request-details with the item's id later for the full result.
A ResultType is 2 (Bad)	Call request-details with the item's id to see exactly what failed.

Sample request

curl -X POST https://www.tincomply.com/api/v1/history \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"count":20,"search":"acme","includeApi":true}'

import requests

response = requests.post(
    "https://www.tincomply.com/api/v1/history",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "page": 1,
        "count": 20,
        "search": "acme",
        "includeApi": True,
    },
)
response.raise_for_status()
print(response.json())

using System.Text;

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

var body = """
{
  "page": 1,
  "count": 20,
  "search": "acme",
  "includeApi": true
}
""";
var response = await client.PostAsync(
    "https://www.tincomply.com/api/v1/history",
    new StringContent(body, Encoding.UTF8, "application/json"));

Console.WriteLine(await response.Content.ReadAsStringAsync());

const response = await fetch("https://www.tincomply.com/api/v1/history", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    page: 1,
    count: 20,
    search: "acme",
    includeApi: true,
  }),
});
const data = await response.json();
console.log(data);

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 = """
            {
              "page": 1,
              "count": 20,
              "search": "acme",
              "includeApi": true
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://www.tincomply.com/api/v1/history"))
            .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 the response.
        System.out.println(response.body());
    }
}

package main

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

func main() {
	body := []byte(`{
	  "page": 1,
	  "count": 20,
	  "search": "acme",
	  "includeApi": true
	}`)

	req, err := http.NewRequest("POST", "https://www.tincomply.com/api/v1/history", 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)
}

$body = @'
{
  "page": 1,
  "count": 20,
  "search": "acme",
  "includeApi": true
}
'@

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

$response

Sample response

{
  "results": {
    "page": 1,
    "count": 20,
    "total": 143,
    "lastPage": 8,
    "direction": "DESC",
    "items": [
      {
        "id": "BG5CF5Z2q0SwIBmhZylJggxp",
        "userName": "ERP integration",
        "customerName": "Acme Widgets Inc",
        "request": {
          "name": "ACME WIDGETS INC",
          "requestedServices": "irs-tin-name-matching,list-sanctions"
        },
        "requestedOn": "2026-10-01T14:02:11Z",
        "completedOn": "2026-10-01T14:02:12Z",
        "requestState": 2,
        "irsResultType": 3,
        "listResultType": 3
      }
    ]
  }
}

Errors

Requests that cannot be processed return HTTP 400 with an object keyed by field name, each listing what was wrong. Authentication, permission and other status codes are covered in Errors & service status.

This endpoint requires an API key with the History permission.

API Endpoint: Request Details

POST /api/v1/request-details

Request body

What to do with this result

Sample request

Sample response

POST /api/v1/history

Request body

Values for the *ResultType fields

What to do with this result

Sample request

Sample response

Errors

POST `/api/v1/request-details`

POST `/api/v1/history`