Retrieve a single instrument

GET /v1/clients/{clientId}/instruments/{instrumentId}

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

Retrieves an instrument for the specified client. The instrument must belong to the client or to one of its customers; otherwise an error is returned.

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).

instrumentId string (uuid) required

Instrument identifier (UUID).

Responses

200 Instrument details. application/json

id string (uuid) required

Instrument UUID.

bankId string (uuid) required

Destination bank UUID associated with the instrument.

clientId string (uuid) required

Client UUID associated with the instrument.

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 string required

Human-friendly label for the instrument.

type string required

Instrument usage type.

RECEIVER SENDER_RECEIVER

audit object required

Instrument lifecycle timestamps.

createdAt audit.createdAt string required

Timestamp when the instrument was created.

updatedAt audit.updatedAt string required

Timestamp when the instrument was last updated.

deletedAt audit.deletedAt string | null required

Timestamp when the instrument was deleted, or null.

blockedAt audit.blockedAt string | null required

Timestamp when the instrument was blocked, or null.

rfc string required

RFC associated with the instrument holder.

customerId string (uuid)

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

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 instrumentDetail.cardNumber string required

Debit card number associated with the instrument.

expirationDate instrumentDetail.expirationDate string | null

Card expiration date when available; null otherwise.

holderName instrumentDetail.holderName string required

Debit-card holder name.

One of ClabeInstrumentDetail

CLABE instrument details returned by Fincore.

accountNumber instrumentDetail.accountNumber string required

Account number without bank prefix.

clabeNumber instrumentDetail.clabeNumber string required

Full 18-digit CLABE.

holderName instrumentDetail.holderName string required

CLABE account holder name.

400 Instrument lookup request is invalid. Possible causes: malformed clientId or instrumentId. 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 Instrument was not found or does not belong to the 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.

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/{instrumentId}" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://apicore.stg.finch.lat/v1/clients/{clientId}/instruments/{instrumentId}", {
  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/{instrumentId}",
    headers={
        "Authorization": f"Bearer {TOKEN}",
    },
)
data = res.json()

Response

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

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