Fincore · API reference · Business Units

Create a Business Unit

POST /v1/clients/{clientId}/customers

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

Creates a Customer/Business Unit that can own instruments and private accounts. Business Units are useful when sub-accounts need their own RFC and legal identity on payment receipts.

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

Request body application/json · required

client_id string (uuid) required

Client UUID that will own the Business Unit.

name string required

Legal name of the Business Unit.

rfc string required

RFC tax identifier for the Business Unit.

legal_representative_name string required

Full name of the Business Unit legal representative.

legal_representative_rfc string required

RFC tax identifier of the legal representative.

legal_representative_phone string required

Contact phone number of the legal representative.

legal_representative_email string (email) required

Contact email of the legal representative.

website string (uri)

Business Unit website when available.

domain string

Business Unit domain when available.

customer_alias string

Short alias used to identify the Business Unit.

customer_status string

Business Unit lifecycle status.

ACTIVE INACTIVE BLOCKED

customer_validation_status string

Business Unit validation status.

PENDING VALIDATED REJECTED

client_bank_adapter_id string (uuid)

Bank adapter configuration UUID associated with the Business Unit.

Responses

200 Business Unit created. application/json

id string (uuid) required

Business Unit UUID.

clientId string (uuid) required

Client UUID that owns the Business Unit.

name string required

Legal name of the Business Unit.

rfc string required

RFC tax identifier of the Business Unit.

legalRepresentativeName string required

Full name of the legal representative.

legalRepresentativeRfc string required

RFC tax identifier of the legal representative.

legalRepresentativePhone string required

Contact phone number of the legal representative.

legalRepresentativeEmail string (email) required

Contact email of the legal representative.

website string (uri)

Business Unit website when available.

domain string

Business Unit domain when available.

customerAlias string

Short alias used to identify the Business Unit.

customerStatus string

Business Unit lifecycle status.

ACTIVE INACTIVE BLOCKED

customerValidationStatus string

Business Unit validation status.

PENDING VALIDATED REJECTED

audit object

Business Unit lifecycle timestamps.

createdAt audit.createdAt string (date-time)

Timestamp when the resource was created.

updatedAt audit.updatedAt string (date-time)

Timestamp when the resource was last updated.

deletedAt 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 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 audit.activatedAt string | null

Timestamp when the resource was activated, or null.

suspendedAt audit.suspendedAt string | null

Timestamp when the resource was suspended, or null.

400 Business Unit creation request is invalid. Possible causes: missing legal representative fields, invalid RFC, invalid email, malformed client_id, or unsupported customer status. It also fails when the Business Unit conflicts with an existing record for this client. 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 POST "https://apicore.stg.finch.lat/v1/clients/c2d1d1e3-3340-4170-980e-e9269bbbc551/customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "name": "Business Unit ABC",
  "rfc": "XAXX010101000",
  "legal_representative_name": "Jane Doe",
  "legal_representative_rfc": "XAXX010101000",
  "legal_representative_phone": "5555555555",
  "legal_representative_email": "legal@example.com",
  "customer_alias": "BU ABC",
  "customer_status": "ACTIVE"
}'

const body = JSON.stringify({
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "name": "Business Unit ABC",
  "rfc": "XAXX010101000",
  "legal_representative_name": "Jane Doe",
  "legal_representative_rfc": "XAXX010101000",
  "legal_representative_phone": "5555555555",
  "legal_representative_email": "legal@example.com",
  "customer_alias": "BU ABC",
  "customer_status": "ACTIVE"
});

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

import requests

payload = {
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "name": "Business Unit ABC",
  "rfc": "XAXX010101000",
  "legal_representative_name": "Jane Doe",
  "legal_representative_rfc": "XAXX010101000",
  "legal_representative_phone": "5555555555",
  "legal_representative_email": "legal@example.com",
  "customer_alias": "BU ABC",
  "customer_status": "ACTIVE"
}

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

Response

{
  "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"
      }
    }
  ]
}