Skip to main content
Version: 1.0.0

banca.me Partners API

The banca.me Partners API provides endpoints for creating and managing PartnerEntities. This API is designed for Partners who want to manage their partner entities in order to have a level of isolation for leads evaluated through Risk Policies for each PartnerEntity in order to satisfy their private B2B customers. Moreover this model reflects Merchants (bnpl), Projects (Real State) and Real State (Real State Brokers).

Features​

This usage provides a Partner the capabilities of managing their own B2B customer relationships by:

  • Enabling them to interact with the platform (make their own evaluations or purchases) using their own id (referenced to banca.me as externalEntityId). Reference POST endpoint.
  • Getting all of the PartnerEntities a Partner has created. Reference GET endpoint.
  • Updating a PartnerEntity values in order to update the name o if the PartnerEntity is no longer active. Reference PATCH endpoint.

The API also exposes read endpoints over your own leads and their evaluations: look an evaluation up by lead id or by RUT, page through your leads, read a lead's contact details, and get a download link for the evaluation report. These reads never change your leads or their evaluations.

Pushing rather than polling? The same evaluations are delivered as the pre_approve webhook event — see the event catalog.

Finally, you can re-evaluate a lead: check again the risk of a person you have a mortgage pre-approval for, without them going through Clave Única again. Unlike the reads, it creates a new lead. See Lead Re-evaluation.

Reads are scoped to your own leads​

Every read endpoint is bounded to the leads that belong to you.

On the lead and evaluation reads — by lead id, by RUT, the lead list and the lead detail — a lead that does not exist, one that belongs to another partner, and one that is out of scope all return the same 404 with the same body, so those endpoints cannot be used to enumerate leads you do not hold. The one input-format exception: a path id that is not 36 characters long is rejected before any lookup with 422 and ERR_INVALID_UUID_ID.

The report endpoint does not collapse its errors this way: an unknown preApproveId returns 404, while a pre-approval that belongs to another partner returns 401. Treat both as "not available to you" rather than inferring anything from the difference.

The evaluation reads (by lead id and by RUT), the lead list and the lead detail require the evaluation module; a partner without it is rejected with 403. On the per-lead reads the lead is resolved first, so a lead that is not yours still answers 404. The report endpoints do not check the module.

Base URL​

The base URL for production API requests is:

https://api.banca.me

For integration and testing use https://beta.api.banca.me (development) or https://automation.api.banca.me (automation). See Environments.

Authentication​

Send your API token as Authorization: Bearer <token> on every endpoint except Open the evaluation report from its link.

  • A missing or malformed token returns 401.
  • A well-formed token that is not your partner's current API token returns 400.
  • A token whose partner is inactive returns 403.

Rate Limiting​

The read endpoints — the evaluation reads, the lead list, the lead detail and both report endpoints — and the lead re-evaluation are rate limited. The PartnerEntity endpoints are not.

  • 2 requests per second, measured over a one-second window. It is a burst limit, not a per-minute quota: a third call inside the same window returns 429 even if the minute is nearly idle. Space out bulk operations rather than batching them.
  • The budget is shared by all rate-limited endpoints, not counted per endpoint.
  • The 429 response has a plain-text body and carries Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

Error Handling​

The API uses standard HTTP status codes. Codes you can receive:

  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 409: Conflict — lead re-evaluation only
  • 422: Unprocessable Entity
  • 428: Precondition Required
  • 429: Too Many Requests
  • 500: Internal Server Error
  • 502: Bad Gateway — lead re-evaluation only
  • 503: Service Unavailable — infrastructure failures are usually reported as 503 rather than 500

Error bodies are JSON with this shape:

{
  "data": {
    "status": 404,
    "url": "/partner/lead/3f1a9c2e-8b47-4d51-9e6a-2c7d0b5f8a13",
    "ip": "203.0.113.10",
    "partnerId": "5b0e7c41-2d93-4f8a-a1c6-9e47d2b80f35"
  }
}

status repeats the HTTP status and url the request path; the remaining keys are request context. Only 422 and 500 responses carry an error code, in message (for example "message": "ERR_INVALID_UUID_ID"). Every other status carries no code, so branch on the HTTP status. The 429 response is the exception to this shape: its body is plain text.

The lead re-evaluation adds one key to every error it returns: details.motivo, the reason — see Re-evaluate a lead.

Data Formats​

Best Practices​

  1. Entity Management
  • Create entities with meaningful names
  • Keep track of external IDs
  • Update entity information when needed
  • Monitor entity status
  1. Error Handling
  • Implement proper error handling
  • Check HTTP status codes
  • Parse error messages from responses
  • Implement retry logic for temporary failures
  1. Security
  • Keep your API token secure
  • Never expose tokens in client-side code
  • Validate all input data
  • Use HTTPS for all requests
  1. Performance
  • Cache entity information when appropriate
  • Monitor rate limits
  • Implement proper error recovery
  • Optimize API calls

Authentication​

Partner access token provided by banca.me

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer