Mono Colombia
GuidesAPI reference

Discover target

Discovers a Bre-B key for a beneficiary from the data you already know about them, and returns a usable Target only when the key can be proven to belong to that same person and to point to that same bank account.

Both outcomes are 200:

  • state=discovered — a single-use Target was created for the requested bank and account. It can be used in exactly one outgoing transfer; repeating discovery produces a new Target.
  • state=not_discovered with state_reason=no_exact_target — no Target could be created for that destination. This does not necessarily mean the person has no other key.

Both carry same_person_keys, possibly empty: keys confirmed to belong to the same person that point somewhere else. Discovery stops at the first exact target, so in a discovered response this list only reflects matches observed before the winner and is not exhaustive. They are not Targets. To use one, pick it explicitly and call POST /api/v1/targets/resolve, then compare the bank and account ending of the fresh Target with the ones you showed the payer before authorizing the transfer — discovery neither reserves the key nor guarantees it still points to the observed destination.

Use GET /api/v1/banks to turn an approximate bank name into the canonical account.bank_code. Discovery only accepts the canonical ACH code.

The endpoint is rate limited per OAuth client and per tenant. Exceeding either limit answers 429 rate_limit_exceeded with a Retry-After header.

POST
/api/v1/targets/discover

Authorization

oauth target_discoveries
AuthorizationBearer <token>

In: header

Scope: target_discoveries

Request Body

application/json

Target discovery request

TypeScript Definitions

Use the request body type in TypeScript.

accountobject

The destination account the discovered key must point to.

personobject

The identity of the beneficiary as the client knows it.

tenant_account_idstring

The originating tenant account. A tenant may hold more than one, so it travels in the body and must belong to the authenticated tenant.

Match^[A-Za-z]{2,7}_[\w-]{22}$
Example"bbtacc_5tgliBmzjZ6mpQPRbQjfKj"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://breb-participant.sandbox.mono.la/api/v1/targets/discover" \  -H "Content-Type: application/json" \  -d '{    "account": {      "bank_code": "007",      "number": "0013123456789"    },    "person": {      "document_number": "1192793827",      "document_type": "CC"    },    "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj"  }'
{
  "attempts_count": 2,
  "resolution_id": "bbtgr_5tgliBmzjZ6mpQPRbQjfKj",
  "same_person_keys": [
    {
      "bank_code": "007",
      "creditor_account": {
        "currency_code": "COP",
        "number_last_four": "4321",
        "type": "savings_account"
      },
      "key_type": "alphanumeric",
      "key_value": "@BBVA3104838791",
      "participant_nit": "890903938",
      "resolution_required": true
    }
  ],
  "state": "discovered",
  "state_reason": null,
  "target": {
    "creditor": {
      "document_number": "1234567890",
      "document_type": "CC",
      "full_name": "Juan Pérez",
      "type": "natural"
    },
    "creditor_account": {
      "currency_code": "COP",
      "number": "1234567890",
      "type": "savings_account"
    },
    "id": "bbtgt_5tgliBmzjZ6mpQPRbQjfKj",
    "key_type": "identification",
    "key_value": "1234567890",
    "participant_nit": "900123456",
    "payment_id": "string",
    "resolution_type": "plain_key",
    "spbvi": "CRB",
    "transaction_amount": {
      "amount": 100000000,
      "currency": "COP"
    }
  }
}
{
  "code": "400 Bad Request",
  "errors": [
    {
      "error_code": "invalid_document_number",
      "message": "The document number is not in a comparable format",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Malformed request"
}
{
  "code": "401 Unauthorized",
  "errors": [
    {
      "error_code": "missing_authorization_header",
      "message": "`Authorization` header is missing.",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Authorization header is missing or invalid."
}
{
  "code": "403 Forbidden",
  "errors": [
    {
      "error_code": "not_authorized",
      "message": "Not authorized to have access to this resource.",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Not authorized to have access to this resource"
}
{
  "code": "404 Not Found",
  "errors": [
    {
      "error_code": "tenant_account_not_found",
      "message": "Tenant account not found",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Resource not defined"
}
{
  "code": "422 Unprocessable Content",
  "errors": [
    {
      "error_code": "unknown_bank",
      "message": "Unknown bank",
      "path": "#/path/to/field",
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Validation errors"
}
{
  "code": "429 Too Many Requests",
  "errors": [
    {
      "error_code": "rate_limit_exceeded",
      "message": "Too many requests. Retry after the indicated time.",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Too many requests"
}
{
  "code": "500 Internal Server Error",
  "errors": [
    {
      "error_code": "internal_error",
      "message": "An unexpected error occurred",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Something went wrong on the Server"
}
{
  "code": "503 Service Unavailable",
  "errors": [
    {
      "error_code": "service_is_unavailable",
      "message": "The service is unavailable, Please try again later",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Service unavailable"
}