Skip to main content
GET
/
entities
List Payment Methods
curl --request GET \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "entities": [
    {
      "id": "<string>",
      "entityType": "<string>",
      "entityData": {},
      "relationships": [
        {}
      ],
      "riskScore": 123,
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ],
  "pagination": {
    "total": 123,
    "limit": 123,
    "offset": 123,
    "hasMore": true
  }
}

​
Overview

Retrieves a list of payment method entities with optional filtering by owner, type, or other criteria.

​
Endpoint

GET http://api.gu1.ai/entities?entityType=payment_method

​
Authentication

Requires a valid API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Query Parameters

​
entityType
string
required
Must be "payment_method" to filter for payment methods
​
relationshipWith
string
Filter by relationship to another entity (e.g., person or company owner UUID)
​
limit
number
Number of results to return (default: 50, max: 100)
​
offset
number
Number of results to skip for pagination (default: 0)
​
sortBy
string
Field to sort by: createdAt, updatedAt, riskScore
​
sortOrder
string
Sort order: asc or desc (default: desc)

​
Example Requests

​
List All Payment Methods

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

​
List Payment Methods for a Person

curl -X GET "http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=person-uuid-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
List with Pagination

curl -X GET "http://api.gu1.ai/entities?entityType=payment_method&limit=25&offset=0&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
success
boolean
Whether the request was successful
​
entities
array
Array of payment method entities
​
pagination
object
Pagination information

​
Response Example

{
  "success": true,
  "entities": [
    {
      "id": "payment-method-uuid-123",
      "entityType": "payment_method",
      "entityData": {
        "paymentMethod": {
          "type": "credit_card",
          "last4": "4242",
          "brand": "visa",
          "expiryMonth": "12",
          "expiryYear": "2025",
          "holderName": "John Doe",
          "issuerCountry": "BR",
          "funding": "credit"
        }
      },
      "relationships": [
        {
          "targetEntityId": "person-uuid-123",
          "relationshipType": "owns",
          "strength": 1.0
        }
      ],
      "riskScore": 15,
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-12-23T10:00:00.000Z"
    },
    {
      "id": "payment-method-uuid-456",
      "entityType": "payment_method",
      "entityData": {
        "paymentMethod": {
          "type": "bank_account",
          "accountType": "checking",
          "bank": "Banco do Brasil",
          "currency": "BRL",
          "holderName": "John Doe"
        }
      },
      "relationships": [
        {
          "targetEntityId": "person-uuid-123",
          "relationshipType": "owns",
          "strength": 1.0
        }
      ],
      "riskScore": 5,
      "createdAt": "2024-02-10T14:30:00.000Z",
      "updatedAt": "2024-12-23T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

​
Use Cases

​
Find All Credit Cards for a Person

async function findPersonCreditCards(personId) {
  const response = await fetch(
    `http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=${personId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entities } = await response.json();

  // Filter for credit cards only
  const creditCards = entities.filter(
    e => e.entityData.paymentMethod.type === 'credit_card'
  );

  return creditCards;
}

​
Find High-Risk Payment Methods

async function findHighRiskPaymentMethods(minRiskScore = 70) {
  let allHighRisk = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `http://api.gu1.ai/entities?` + new URLSearchParams({
        entityType: 'payment_method',
        limit,
        offset,
        sortBy: 'riskScore',
        sortOrder: 'desc'
      }),
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const { entities, pagination } = await response.json();

    // Filter by risk score
    const highRisk = entities.filter(e => e.riskScore >= minRiskScore);
    allHighRisk = allHighRisk.concat(highRisk);

    // If we got entities with risk score below threshold, stop
    if (entities.length > 0 && entities[entities.length - 1].riskScore < minRiskScore) {
      break;
    }

    hasMore = pagination.hasMore;
    offset += limit;
  }

  return allHighRisk;
}

​
Group Payment Methods by Type

async function groupPaymentMethodsByType(personId) {
  const response = await fetch(
    `http://api.gu1.ai/entities?entityType=payment_method&relationshipWith=${personId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entities } = await response.json();

  const grouped = entities.reduce((acc, pm) => {
    const type = pm.entityData.paymentMethod.type;
    if (!acc[type]) {
      acc[type] = [];
    }
    acc[type].push(pm);
    return acc;
  }, {});

  return grouped;
}

// Usage
const grouped = await groupPaymentMethodsByType('person-uuid-123');
console.log(`Credit cards: ${grouped.credit_card?.length || 0}`);
console.log(`Bank accounts: ${grouped.bank_account?.length || 0}`);
console.log(`PIX keys: ${grouped.pix?.length || 0}`);

​
Error Responses

​
400 Bad Request

{
  "error": "Invalid query parameters",
  "details": {
    "limit": "Must be between 1 and 100"
  }
}

​
401 Unauthorized

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

​
See Also