Get a company by ID

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

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

fetch('http://api.gu1.ai/entities/{id}', 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/{id}",
  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/{id}"

	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/{id}")

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

{
  "id": "<string>",
  "externalId": "<string>",
  "organizationId": "<string>",
  "type": "<string>",
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "riskScore": 123,
  "riskFactors": [
    {}
  ],
  "status": "<string>",
  "kycVerified": true,
  "kycProvider": "<string>",
  "kycData": {},
  "entityData": {},
  "attributes": {},
  "currentEvaluation": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

GET

entities

{id}

Get a company by ID

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

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

fetch('http://api.gu1.ai/entities/{id}', 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/{id}",
  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/{id}"

	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/{id}")

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

{
  "id": "<string>",
  "externalId": "<string>",
  "organizationId": "<string>",
  "type": "<string>",
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "riskScore": 123,
  "riskFactors": [
    {}
  ],
  "status": "<string>",
  "kycVerified": true,
  "kycProvider": "<string>",
  "kycData": {},
  "entityData": {},
  "attributes": {},
  "currentEvaluation": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

Overview

Retrieves complete details for a specific company, including current evaluation status and risk assessment. You can fetch a company in three ways:

Method	Endpoint	Use when
By ID	`GET /entities/{id}`	You have gu1’s internal entity UUID
By external ID	`GET /entities/by-external-id/{externalId}`	You use your own identifier (e.g. `business_456`)
By tax ID	`GET /entities/by-tax-id/{taxId}`	You have the company’s tax ID (e.g. CUIT, CNPJ) and want to look them up

All three return the same company object. The organization scope is enforced by your API key.

Endpoints

Get by ID

GET http://api.gu1.ai/entities/{id}

string

required

The unique gu1 ID (UUID) of the company to retrieve

Get by external ID

GET http://api.gu1.ai/entities/by-external-id/{externalId}

string

required

Your external identifier for this company (e.g. the value you sent when creating the entity)

Get by tax ID

GET http://api.gu1.ai/entities/by-tax-id/{taxId}

string

required

The company’s tax identification number (format depends on country: CUIT for Argentina, CNPJ for Brazil, etc.). Must match the entity’s stored tax ID within your organization.

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Response

Returns the complete company object with the following fields:

string

gu1’s internal entity ID

string

Your external identifier for this company

string

Your organization ID

string

Always “company”

string

Company display name

string

Tax identification number

string

ISO 3166-1 alpha-2 country code

number

Calculated risk score from 0 (low risk) to 100 (high risk)

array

Array of identified risk factors contributing to the risk score

string

Company status: active, inactive, not_started, under_review, pending_verification, awaiting_information, rejected, suspended, blocked, expired, deleted

boolean

Whether KYB verification has been completed

string

Name of the KYB provider used (if applicable)

object

KYB verification data from the provider

object

Company-specific data structure

object

Custom attributes as key-value pairs

object

Latest AI evaluation results (null if no evaluation exists)

id - Evaluation ID
entityId - Entity ID
evaluationType - Type of evaluation performed
result - Evaluation result
confidence - Confidence score (0-1)
evaluatedAt - Timestamp of evaluation

string

ISO 8601 timestamp of company creation

string

ISO 8601 timestamp of last update

string

ISO 8601 timestamp of soft deletion (null if not deleted)

Examples

Get by ID (UUID)

curl -X GET http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const company = await response.json();
console.log(company);

import requests

response = requests.get(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

company = response.json()
print(company)

Get by external ID

curl -X GET "http://api.gu1.ai/entities/by-external-id/business_456" \
  -H "Authorization: Bearer YOUR_API_KEY"

const externalId = 'business_456';
const response = await fetch(
  `http://api.gu1.ai/entities/by-external-id/${encodeURIComponent(externalId)}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const company = await response.json();

import requests
external_id = "business_456"
response = requests.get(
    f"http://api.gu1.ai/entities/by-external-id/{external_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
company = response.json()

Get by tax ID

curl -X GET "http://api.gu1.ai/entities/by-tax-id/30-71234567-8" \
  -H "Authorization: Bearer YOUR_API_KEY"

const taxId = '30-71234567-8'; // e.g. CUIT (AR) or CNPJ (BR)
const response = await fetch(
  `http://api.gu1.ai/entities/by-tax-id/${encodeURIComponent(taxId)}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const company = await response.json();

import requests
tax_id = "30-71234567-8"  # e.g. CUIT (AR) or CNPJ (BR)
response = requests.get(
    f"http://api.gu1.ai/entities/by-tax-id/{tax_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
company = response.json()

Response Example

{
  "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"
    },
    {
      "factor": "high_income_occupation",
      "impact": -10,
      "description": "Professional occupation with verified income"
    }
  ],
  "status": "active",
  "kycVerified": true,
  "kycProvider": "gueno_ai",
  "kycData": {
    "verificationDate": "2024-10-03T14:30:00Z",
    "documentsVerified": ["national_id", "proof_of_address"],
    "livenessCheck": "passed",
    "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",
    "businessSince": "2024-01-15",
    "accountTier": "premium"
  },
  "currentEvaluation": {
    "id": "eval_abc123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "evaluationType": "risk_assessment",
    "result": {
      "overallRisk": "low",
      "amlRisk": "low",
      "fraudRisk": "low",
      "complianceScore": 95,
      "recommendation": "approve"
    },
    "confidence": 0.92,
    "evaluatedAt": "2024-10-03T14:35:00Z"
  },
  "createdAt": "2024-10-03T14:30:00.000Z",
  "updatedAt": "2024-10-03T14:35:00.000Z",
  "deletedAt": null
}

Error Responses

404 Not Found

{
  "error": "Entity not found"
}

401 Unauthorized

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

500 Internal Server Error

{
  "error": "Failed to fetch entity"
}

Use Cases

KYB Verification Check

Retrieve a business to check their KYB status before approving a transaction:

const company = await fetch(`http://api.gu1.ai/entities/${businessId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (company.kycVerified && company.status === 'active') {
  // Proceed with transaction
  console.log('Business verified, risk score:', company.riskScore);
} else {
  // Request additional verification
  console.log('KYB verification required');
}

Risk Score Monitoring

Check the current risk score and factors for ongoing monitoring:

company = requests.get(
    f'http://api.gu1.ai/entities/{company_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()

if company['riskScore'] > 70:
    # High risk - trigger enhanced due diligence
    print(f"High risk company detected: {company['riskScore']}")
    print("Risk factors:", company['riskFactors'])
elif company['riskScore'] > 40:
    # Medium risk - apply additional monitoring
    print(f"Medium risk company: {company['riskScore']}")

Next Steps

Update Company - Modify company attributes
List Companies - Query multiple companies
Create KYB Validation - Start identity verification

​Overview

​Endpoints

​Get by ID

​Get by external ID

​Get by tax ID

​Authentication

​Response

​Examples

​Get by ID (UUID)

​Get by external ID

​Get by tax ID

​Response Example

​Error Responses

​404 Not Found

​401 Unauthorized

​500 Internal Server Error

​Use Cases

​KYB Verification Check

​Risk Score Monitoring

​Next Steps

Overview

Endpoints

Get by ID

Get by external ID

Get by tax ID

Authentication

Response

Examples

Get by ID (UUID)

Get by external ID

Get by tax ID

Response Example

Error Responses

404 Not Found

401 Unauthorized

500 Internal Server Error

Use Cases

KYB Verification Check

Risk Score Monitoring

Next Steps