List companies

curl --request GET \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "entities": [
    {}
  ]
}

GET

entities

List companies

curl --request GET \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "entities": [
    {}
  ]
}

Overview

Retrieves a list of companies with optional filtering by country, tax ID, or external ID. Returns up to 100 companies per request.

Endpoint

GET http://api.gu1.ai/entities?type=company

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

string

required

Must be set to company to retrieve only companies

string

Filter by ISO 3166-1 alpha-2 country code (e.g., “US”, “BR”, “AR”)

string

Filter by exact tax identification number

string

Filter by your external identifier

Response

array

Array of company objects, each containing:

id - gu1’s internal ID
externalId - Your external ID
organizationId - Your organization ID
type - Always “company”
name - Company name
taxId - Tax ID
countryCode - Country code
riskScore - Risk score (0-100)
riskFactors - Array of risk factors
status - Company status
kycVerified - KYB verification status
kycProvider - KYB provider name
kycData - KYB verification data
entityData - Company-specific data
attributes - Custom attributes
createdAt - Creation timestamp
updatedAt - Last update timestamp
deletedAt - Deletion timestamp (null if active)

Examples

List All Companies

curl -X GET "http://api.gu1.ai/entities?type=company" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('http://api.gu1.ai/entities?type=company', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(`Found ${data.entities.length} companies`);

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    params={'type': 'company'}
)

data = response.json()
print(f"Found {len(data['entities'])} companies")

Filter by Country

curl -X GET "http://api.gu1.ai/entities?type=company&country=BR" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities?type=company&country=BR',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Found ${data.entities.length} Brazilian businesses`);

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
        'type': 'company',
        'country': 'BR'
    }
)

brazilian_businesses = response.json()['entities']
print(f"Found {len(brazilian_businesses)} Brazilian businesses")

Find by External ID

curl -X GET "http://api.gu1.ai/entities?type=company&externalId=business_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities?type=company&externalId=business_12345',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
const company = data.entities[0]; // External IDs should be unique
console.log('Found company:', company.name);

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
        'type': 'company',
        'externalId': 'business_12345'
    }
)

entities = response.json()['entities']
if entities:
    print(f"Found company: {entities[0]['name']}")

Find by Tax ID

curl -X GET "http://api.gu1.ai/entities?type=company&taxId=20-12345678-9" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities?type=company&taxId=20-12345678-9',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
if (data.entities.length > 0) {
  console.log('Company found:', data.entities[0].name);
}

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
        'type': 'company',
        'taxId': '20-12345678-9'
    }
)

entities = response.json()['entities']
if entities:
    print(f"Company found: {entities[0]['name']}")

Response Example

{
  "entities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalId": "business_12345",
      "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
      "type": "company",
      "name": "María González",
      "taxId": "20-12345678-9",
      "countryCode": "AR",
      "riskScore": 25,
      "riskFactors": [
        {
          "factor": "new_business",
          "impact": 15,
          "description": "Business registered within last 30 days"
        }
      ],
      "status": "active",
      "kycVerified": true,
      "kycProvider": "gueno_ai",
      "kycData": {
        "verificationDate": "2024-10-03T14:30:00Z",
        "overallStatus": "approved"
      },
      "entityData": {
        "company": {
          "firstName": "María",
          "lastName": "González",
          "dateOfBirth": "1985-03-15",
          "nationality": "AR",
          "occupation": "Software Engineer",
          "income": 85000
        }
      },
      "attributes": {
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678"
      },
      "createdAt": "2024-10-03T14:30:00.000Z",
      "updatedAt": "2024-10-03T14:35:00.000Z",
      "deletedAt": null
    }
  ]
}

Use Cases

High Risk Business Monitoring

Query all companies and filter by risk score:

const response = await fetch('http://api.gu1.ai/entities?type=company', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
const highRiskBusinesses = data.entities.filter(e => e.riskScore > 70);

console.log(`Found ${highRiskBusinesses.length} high-risk businesses requiring review`);
highRiskBusinesses.forEach(company => {
  console.log(`- ${company.name} (Risk: ${company.riskScore})`);
});

KYB Compliance Dashboard

Get all unverified businesses for compliance dashboard:

import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'type': 'company'}
)

companies = response.json()['entities']
unverified = [p for p in companies if not p['kycVerified']]

print(f"Unverified businesses: {len(unverified)}")
for company in unverified:
    print(f"- {company['name']} ({company['externalId']})")

Error Responses

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to search entities"
}

Limits

Maximum results per request: 100 companies
Query parameters: Can be combined for advanced filtering
Rate limits: Apply based on your plan tier

Next Steps

Get Company Details - Retrieve complete information for a specific company
Create Company - Add new companies to your organization
Update Company - Modify company attributes

​Overview

​Endpoint

​Authentication

​Query Parameters

​Response

​Examples

​List All Companies

​Filter by Country

​Find by External ID

​Find by Tax ID

​Response Example

​Use Cases

​High Risk Business Monitoring

​KYB Compliance Dashboard

​Error Responses

​401 Unauthorized

​500 Internal Server Error

​Limits

​Next Steps

Overview

Endpoint

Authentication

Query Parameters

Response

Examples

List All Companies

Filter by Country

Find by External ID

Find by Tax ID

Response Example

Use Cases

High Risk Business Monitoring

KYB Compliance Dashboard

Error Responses

401 Unauthorized

500 Internal Server Error

Limits

Next Steps