List instruments for a client

GET /v1/clients/{clientId}/instruments

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

Returns a paginated list of instruments belonging to the specified client and its customers.

Without customer_id, it returns instruments for the client and all associated customers.
With customer_id, it returns only instruments for that customer.

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 identifier (UUID).

Query parameters

customer_id string (uuid)

Optional customer UUID. When provided, filters instruments for this customer only.

page integer

Page number (1-based).

per_page integer

Number of items per page.

instrument_number string

Optional CLABE or debit-card number filter.

bank_id string (uuid)

Optional destination bank UUID filter.

instrument_name string

Optional holder-name filter.

Responses

200 List of instruments for the client (and optionally a specific customer). application/json

data array of InstrumentResponse required

Registered instruments returned for the client and filters.

id data[].id string (uuid) required

Instrument UUID.

bankId data[].bankId string (uuid) required

Destination bank UUID associated with the instrument.

clientId data[].clientId string (uuid) required

Client UUID associated with the instrument.

ownerId data[].ownerId string (uuid) required

Identifier of the entity that owns this instrument (client or customer). When the instrument belongs to a customer, ownerId and customerId will be the same.

alias data[].alias string required

Human-friendly label for the instrument.

type data[].type string required

Instrument usage type.

RECEIVER SENDER_RECEIVER

audit data[].audit object required

Instrument lifecycle timestamps.

createdAt data[].audit.createdAt string required

Timestamp when the instrument was created.

updatedAt data[].audit.updatedAt string required

Timestamp when the instrument was last updated.

deletedAt data[].audit.deletedAt string | null required

Timestamp when the instrument was deleted, or null.

blockedAt data[].audit.blockedAt string | null required

Timestamp when the instrument was blocked, or null.

rfc data[].rfc string required

RFC associated with the instrument holder.

customerId data[].customerId string (uuid)

Customer who owns the instrument when applicable. Present when the instrument belongs to a customer; omitted for client-level instruments.

instrumentDetail data[].instrumentDetail CardInstrumentDetail | ClabeInstrumentDetail required

Payment method details. Card instruments return card fields; CLABE instruments return account and CLABE fields.

One of CardInstrumentDetail

Debit-card instrument details returned by Fincore.

cardNumber data[].instrumentDetail.cardNumber string required

Debit card number associated with the instrument.

expirationDate data[].instrumentDetail.expirationDate string | null

Card expiration date when available; null otherwise.

holderName data[].instrumentDetail.holderName string required

Debit-card holder name.

One of ClabeInstrumentDetail

CLABE instrument details returned by Fincore.

accountNumber data[].instrumentDetail.accountNumber string required

Account number without bank prefix.

clabeNumber data[].instrumentDetail.clabeNumber string required

Full 18-digit CLABE.

holderName data[].instrumentDetail.holderName string required

CLABE account holder name.

currentPage integer required

Current page number.

perPage integer required

Number of instruments returned per page.

totalItems integer required

Total number of instruments matching the request.

400 Instrument list request is invalid. Possible causes: malformed clientId, malformed filter UUIDs, invalid pagination values, or unsupported instrument filter 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.

404 Client or filtered customer was not found. 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 Instruments.Download collection

Request

curl -X GET "https://apicore.stg.finch.lat/v1/clients/{clientId}/instruments" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://apicore.stg.finch.lat/v1/clients/{clientId}/instruments", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
  },
});
const data = await res.json();

import requests

res = requests.get(
    "https://apicore.stg.finch.lat/v1/clients/{clientId}/instruments",
    headers={
        "Authorization": f"Bearer {TOKEN}",
    },
)
data = res.json()

Response

{
  "data": [
    {
      "id": "dd7f8d89-94dd-43ca-871b-720fde378b52",
      "bankId": "d3435bd9-998d-4e8a-9067-6b71d5fd3ac7",
      "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
      "ownerId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
      "alias": "Instrumento base",
      "type": "RECEIVER",
      "audit": {
        "createdAt": "2025-05-19 19:03:51.084659-06:00",
        "updatedAt": "2025-05-19 19:03:51.084668-06:00",
        "deletedAt": null,
        "blockedAt": null
      },
      "rfc": "XAXX010101000",
      "customerId": "bb1e8fde-e68e-48e9-a483-d32153c752c2",
      "instrumentDetail": {
        "cardNumber": "5579072268574100",
        "expirationDate": null,
        "holderName": "John Smith"
      }
    }
  ],
  "currentPage": 1,
  "perPage": 50,
  "totalItems": 17
}

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

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