Fincore · API reference · Business Units

List Business Units

GET /v1/clients/{clientId}/customers

Base URL https://apicore.stg.finch.lat · operationId listCustomers

Returns the Customers/Business Units associated with a client. In production, use only customers where customerValidationStatus = VALIDATED.

Authorization

bearerAuth Bearer token

JWT bearer token created from client credentials. Use the Authentication guide to generate a token before calling protected endpoints.

Path parameters

clientId string (uuid) required

Client UUID.

Example c2d1d1e3-3340-4170-980e-e9269bbbc551

Query parameters

customer_status string

Filter Business Units by lifecycle status.

Example ACTIVE

ACTIVE INACTIVE BLOCKED

customer_alias string

Filter Business Units by alias. Matching behavior is backend-defined.

name string

Filter Business Units by legal or display name.

customer_validation_status string

Filter Business Units by validation status.

Example VALIDATED

PENDING VALIDATED REJECTED

page integer

Page number to return. The first page is 1.

per_page integer

Number of Business Units returned per page.

Responses

200 Business Units list. application/json

currentPage integer

Current page number.

perPage integer

Number of Business Units returned per page.

totalItems integer

Total number of Business Units matching the request.

data array of CustomerResponse required

Business Units returned for the client and filters.

id data[].id string (uuid) required

Business Unit UUID.

clientId data[].clientId string (uuid) required

Client UUID that owns the Business Unit.

name data[].name string required

Legal name of the Business Unit.

rfc data[].rfc string required

RFC tax identifier of the Business Unit.

legalRepresentativeName data[].legalRepresentativeName string required

Full name of the legal representative.

legalRepresentativeRfc data[].legalRepresentativeRfc string required

RFC tax identifier of the legal representative.

legalRepresentativePhone data[].legalRepresentativePhone string required

Contact phone number of the legal representative.

legalRepresentativeEmail data[].legalRepresentativeEmail string (email) required

Contact email of the legal representative.

website data[].website string (uri)

Business Unit website when available.

domain data[].domain string

Business Unit domain when available.

customerAlias data[].customerAlias string

Short alias used to identify the Business Unit.

customerStatus data[].customerStatus string

Business Unit lifecycle status.

ACTIVE INACTIVE BLOCKED

customerValidationStatus data[].customerValidationStatus string

Business Unit validation status.

PENDING VALIDATED REJECTED

audit data[].audit object

Business Unit lifecycle timestamps.

createdAt data[].audit.createdAt string (date-time)

Timestamp when the resource was created.

updatedAt data[].audit.updatedAt string (date-time)

Timestamp when the resource was last updated.

deletedAt data[].audit.deletedAt string | null

Timestamp when the resource was deleted. When it was never deleted the API returns the literal string "None", not JSON null. Do not test this field for null.

blockedAt data[].audit.blockedAt string | null

Timestamp when the resource was blocked. When it was never blocked the API returns the literal string "None", not JSON null. Do not test this field for null.

activatedAt data[].audit.activatedAt string | null

Timestamp when the resource was activated, or null.

suspendedAt data[].audit.suspendedAt string | null

Timestamp when the resource was suspended, or null.

400 Business Unit list request is invalid. Possible causes: malformed clientId, invalid status filter, or invalid pagination values. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

401 Missing, expired, invalid, or environment-mismatched API key or bearer token. See Authentication. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

500 Unexpected server error. See Error catalog before retrying non-idempotent operations. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

This request is in the Monato · Fincore Postman collection, folder Business Units.Download collection

Request

curl -X GET "https://apicore.stg.finch.lat/v1/clients/c2d1d1e3-3340-4170-980e-e9269bbbc551/customers" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://apicore.stg.finch.lat/v1/clients/c2d1d1e3-3340-4170-980e-e9269bbbc551/customers", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
  },
});
const data = await res.json();

import requests

res = requests.get(
    "https://apicore.stg.finch.lat/v1/clients/c2d1d1e3-3340-4170-980e-e9269bbbc551/customers",
    headers={
        "Authorization": f"Bearer {TOKEN}",
    },
)
data = res.json()

Response

{
  "currentPage": 1,
  "perPage": 50,
  "totalItems": 3,
  "data": [
    {
      "id": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
      "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
      "name": "Business Unit ABC",
      "rfc": "XAXX010101000",
      "legalRepresentativeName": "Jane Doe",
      "legalRepresentativeRfc": "XAXX010101000",
      "legalRepresentativePhone": "5555555555",
      "legalRepresentativeEmail": "legal@example.com",
      "website": "https://example.com",
      "domain": "example.com",
      "customerAlias": "BU ABC",
      "customerStatus": "ACTIVE",
      "customerValidationStatus": "VALIDATED",
      "audit": {
        "createdAt": "2025-03-05 11:00:56.264527-06:00",
        "updatedAt": "2025-03-05 11:00:56.264527-06:00",
        "deletedAt": "None",
        "blockedAt": "None",
        "activatedAt": null,
        "suspendedAt": null
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 16,
  "message": "API Error",
  "details": [
    {
      "reason": "UNAUTHORIZED",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid Credentials",
        "http_code": "401"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}