Add an instrument to the trusted whitelist

POST /v1/clients/{clientId}/instruments/{instrumentId}/whitelist

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

Marks a destination instrument as trusted so that high-value Money Out transactions to it skip the manual operator review. The instrument must belong to the client and meet the age and transaction-history requirements. This operation is not idempotent: adding an instrument that is already whitelisted returns a conflict.

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 that owns the instrument.

instrumentId string (uuid) required

UUID of the instrument to add to the whitelist.

Responses

200 Instrument added to the whitelist. application/json

id string (uuid) required

Unique identifier of the whitelist entry.

instrumentId string (uuid) required

Instrument that was added to the whitelist.

clientId string (uuid) required

Client that owns the whitelist entry.

instrumentWhitelistStatus string required

Lifecycle status of the whitelist entry. New entries are created as ACTIVE.

ACTIVE INACTIVE BLOCKED EXPIRED DELETED CANCELLED

audit object

Creation and update timestamps of the whitelist entry.

createdAt audit.createdAt string (date-time)

updatedAt audit.updatedAt string (date-time)

400 The supplied clientId or instrumentId is not a valid UUID, or a whitelist rule was not met: the instrument is already whitelisted, the client reached the maximum of 10 active whitelisted instruments, the instrument was created less than 72 hours ago, or it does not have at least 3 liquidated transactions as destination. Rule failures are returned as FAILED_PRECONDITION with error code 20-E4120. 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 The bearer token is missing, expired, invalid, or not valid for the environment. 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 No active instrument was found for the supplied 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. 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 POST "https://apicore.stg.finch.lat/v1/clients/{clientId}/instruments/{instrumentId}/whitelist" \
  -H "Authorization: Bearer $TOKEN"

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

import requests

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

Response

{
  "id": "8f14e45f-ceea-467a-9f0a-1b2c3d4e5f60",
  "instrumentId": "d3fdb481-2058-46c8-807d-4eaf866ae1ec",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "instrumentWhitelistStatus": "ACTIVE",
  "audit": {
    "createdAt": "2026-09-21T13:03:36.194761-06:00",
    "updatedAt": "2026-09-21T13:03:36.194761-06:00"
  }
}

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

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