# List enrollments

## ▶️ Usage

With the List Enrollments method, you can:
  
  1. (Recommended) List enrollments related to a specific CPF (using the customer__identifier query parameter).
  2. List enrollments related to a specific customer.id and institution.id (using the customer and institution query parameters).
  3. List enrollments according to a specific status (using the status query parameter).
  4. [Not Recommended] List all enrollements related to your Belvo account (without using any query parameters).

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

Endpoint: GET /payments/br/enrollments/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `customer__identifier` (string)
    The CPF of the customer you want to get results for.
    Example: 23100299900

  - `customer` (string)
    The customer.id you want to get results for.
    Example: "24e5b3a5-19aa-40fe-91e5-4db7f22ecc2d"

  - `external_id` (string)
    Return objects with this external ID.
    Example: "295ebb46-65b8-47de-85cd-34ffbc327c09"

  - `external_id__in` (array)
    Return objects with these external IDs.
    Example: ["446bdd9f-5b3e-4c05-9159-7a5c87cfc810"]

  - `institution` (string)
    Return results only for this institution (use the Belvo-designated name, such as planet_mx_employment).
    Example: "planet_mx_retail"

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `status` (string)
    Return enrollments with the given status. Can be either:
  - PENDING
  - SUCCEEDED
  - CANCELED
  - FAILED
    Example: "PENDING"

  - `status__in` (array)
    Return enrollments with these statuses:
  - PENDING
  - SUCCEEDED
  - CANCELED
  - FAILED
    Example: ["PENDING"]

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908&page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    Array of enrollment objects.

  - `results.id` (string)
    Belvo's unique identifier of the enrollment.
    Example: "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0"

  - `results.created_by` (string)
    The Belvo ID of the merchant that created the enrollment.
    Example: "dbdce1e9-d089-4b7d-804b-51dd07748202"

  - `results.created_at` (string)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2024-11-26T11:20:57.389056Z"

  - `results.updated_at` (string)
    The ISO-8601 timestamp of when the enrollment was last updated.
    Example: "2024-11-26T11:20:57.389058Z"

  - `results.external_id` (string)
    An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %}
  We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes.
{% /admonition %}
    Example: "4b8a81a0-e33c-45a6-8567-479efb105f73"

  - `results.type` (string)
    The type of enrollment. For 🇧🇷 Brazil's OFPI, can be either:

  - open_finance_biometric_pix: For biometric payments using the PIX network.
    Enum: "open_finance_biometric_pix"

  - `results.status` (string)
    The status of the device enrollment. Can be either:

- PENDING: The enrollment is pending.
- SUCCEEDED: The enrollment was successful.
- CANCELED: The enrollment was canceled.
- FAILED: The enrollment failed.
    Enum: "PENDING", "SUCCEEDED", "CANCELED", "FAILED"

  - `results.status_reason_code` (string,null)
    A machine-readable code providing the reason for a failed enrollment. Only present when status is FAILED.

Possible values:
  - send_risk_signals_failed: Enrollment rejected due to timeout while sending risk signals.
  - redirection_to_institution_failed: Enrollment rejected because the redirection to the institution was not successfully completed.
  - biometric_registration_failed: Enrollment rejected because the biometric registration was not completed successfully within the allowed time.
  - too_many_device_registration_attempts: Enrollment rejected due to too many failed device registration attempts.
  - rejected_by_user: Enrollment was manually cancelled by the user.
  - device_not_supports_biometric_authentication: Enrollment rejected because the device is not compatible with biometric authentication.
  - institution_infra_failed: Enrollment rejected due to infrastructure issues at the institution.
  - blocked_by_institution_security_policy: Enrollment rejected due to the institution security policy decisions based on risk evaluation.
  - redirection_back_from_institution_failed: Enrollment rejected because the redirection back from the institution was not successfully completed.
  - biometric_validation_error: Enrollment failed due to biometric validation or public key registration issues.
  - rejected_other: Enrollment rejected for an unspecified reason.
  - canceled_due_to_expiration: Enrollment canceled due to expiration of validity period.
    Example: "biometric_registration_failed"

  - `results.status_reason_message` (string,null)
    A human-readable message providing more details about the reason for a failed enrollment. Only present when status is FAILED. Please see status_reason_code for example messages for each reason code.
    Example: "Enrollment rejected because the biometric registration was not completed successfully within the allowed time."

  - `results.details` (object)
    Details regarding the enrollment

  - `results.details.status` (string)
    The status of the Biometric payments enrollment. Can be either:

  - AWAITING_ACCOUNT_HOLDER_VALIDATION: The account holder needs to validate the enrollment by sending their biometric data.
  - AWAITING_ENROLLMENT: The enrollment information has been sent to the institution and is being evaluated.
  - AUTHORIZED: The enrollment has been authorized.
  - REJECTED: The institution has rejected the enrollment.
  - REVOKED: The user or the institution has revoked the enrollment.
    Enum: "AWAITING_ACCOUNT_HOLDER_VALIDATION", "AWAITING_ENROLLMENT", "AUTHORIZED", "REJECTED", "REVOKED"

  - `results.details.customer` (string)
    Belvo's unique ID to reference the customer.
    Example: "c860809f-e96d-4d50-9588-f40ffab77302"

  - `results.details.institution` (string)
    Belvo's unique ID to reference the institution the device is enrolled at.
    Example: "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0"

  - `results.details.platform` (string)
    The platform of the device to be enrolled. Can be either:

  - ANDROID: For Android devices.
  - BROWSER: For web browsers.
  - CROSS_PLATFORM: For cross-platform devices.
  - IOS: For iOS devices.
    Enum: "ANDROID", "BROWSER", "CROSS_PLATFORM", "IOS"

  - `results.details.name` (string,null)
    An internal name for this device enrollment.
    Example: "600f1b4a-Mobile"

  - `results.details.callback_url` (string)
    The URL to redirect your user to after the enrollment process is completed.
    Example: "https://example.com/enrollment-in-progress"

  - `results.details.redirect_url` (string)
    The URL to redirect the user to complete their enrollment at the institution.
    Example: "https://www.acmecorp.com/checkout/3487321"

  - `results.details.risk_signals` (string)
    An obfuscated string () used to indicate that risk signals have been provided.
    Example: "******"

  - `results.details.expires_at` (string)
    The ISO-8601 timestamp of when the enrollment will expire. After this time, the enrollment will no longer be valid and the status will transition to CANCELED and the status_reason_code will be set to canceled_due_to_expiration.
    Example: "2026-12-26T11:20:57.389056Z"

  - `results.metadata` (object)
    Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the enrollment.


⚠️ Note: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.
    Example: {"internal_reference_id":"GGq73487w2"}

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"