> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcarbon.co/llms.txt > Use this file to discover all available pages before exploring further. # Fetch Accounts > Retrieve a list of accounts with pagination and optional filtering. ## Overview This endpoint retrieves a list of accounts with pagination. It fetches a specified number of accounts per page, as per the provided `page` and `limit` parameters. You can also filter results by `account_number` or `account_name`. ### Request **Method:** `GET`\ **URL:** `/v1/accounts` #### Parameters | Name | In | Type | Required | Description | | ---------------- | ------ | --------- | -------- | ------------------------------------------------- | | `x-carbon-key` | Header | `string` | Yes | API key for authentication. | | `page` | Query | `integer` | No | Page number for pagination. | | `limit` | Query | `integer` | No | Number of accounts per page. | | `account_number` | Query | `string` | No | Filter accounts by a specific account number. | | `account_name` | Query | `string` | No | Filter accounts by account name (partial match). | | `customer_id` | Query | `string` | No | Filter accounts belonging to a specific customer. | ### Response **Status Code:** `200 OK`\ **Content-Type:** `application/json` #### Example Response ```json theme={null} { "status": "success", "message": "Accounts fetched successfully", "data": [ { "id": "3529237a-8ae1-4d63-a6ad-419fae3b9f5e", "account": { "bank_name": "CARBON", "account_name": "Ola Ajayi", "account_number": "6009490194", "balance": 350833340, "available_balance": 350833340, "locked": false }, "owner": { "id": "965c4bf7-e86b-45ca-b286-1ee6f32e991b", "first_name": "Ola", "last_name": "Ajayi", "email": "ola@yahoo.com", "phone": "08071000030" }, "is_static": true, "mode": "sandbox", "created_at": "2024-02-28T01:01:29.000Z", "updated_at": "2024-02-28T01:01:29.000Z" } ], "total": "1" } ``` ## OpenAPI ````yaml GET /v1/accounts openapi: 3.0.0 info: title: Carbon Business API description: >- ## Welcome to our API Developer Documentation Carbon aims to unlock the full potential of your business with a feature-rich account designed for growth. ## Integrations We aim to provide our APIs for developers and businesses to offer financial services to their existing customer base through REST APIs without doing the heavy lifting. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ### Authentication `Authorization : API Key` Header `x-carbon-key : value` `x-carbon-key` can be generated via developer page on Carbon Business | Environment | URL | | --- | --- | | Live | | | Sandbox | [https://carbonapistagingsecure.getcarbon.co/baas/api](https://carbonapistagingsecure.getcarbon.co/baas/api) | ### **Handling Errors** We use the conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with our servers. | Error | Description | | --- | --- | | 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 - Unauthorized | Not a valid API key was provided. | | 402 - Request Failed | The parameters were valid but the request failed. | | 403 - Forbidden | The API key doesn't have permission to perform the request. | | 404 - Not Found | The requested resource doesn't exist. | | 429 - Too Many Requests | Too many requests hit the API | | 500, 502, 503, 504 - Server Errors | System Error | version: 1.0.0 servers: - url: https://carbonapistagingsecure.getcarbon.co/baas/api description: >- Replace {{base_url}} with your API base URL (e.g., https://api.example.com) security: - apikeyAuth: [] tags: - name: Accounts description: >- Virtual accounts are generated account details (account number and bank) that allow Carbon Business merchants to receive payments from customers via NGN bank transfer. This is currently only available in naira (NGN). Virtual accounts are either dynamic (temporary) or static (permanent). A dynamic account number expires after handling a transaction, while a static account number doesn't expire. **Static Account** Creating static accounts can be useful when receiving recurring payments through bank transfers. The process involves generating a static virtual account with customer information. Once payment is made, we will send you a webhook notification, which you can then manage. **Dynamic Account** Creating dynamic accounts can be useful when receiving one-time payments through bank transfers. The process involves generating a dynamic virtual account with a set amount for the customer during checkout. Once payment is made, we will send you a webhook notification, which you can then manage. Key things you can do with these endpoints: - Create an account - Retreive an account - Verify Transaction - Retreive a list of transactions - name: Accounts > Transactions - name: Banks description: |- - Get a list of banks and financial institutions - Verify/resolve account details - name: Customers description: >- This collection contains a set of API endpoints to manage customer-related operations for an application. The endpoints allow for creating a new customer, retrieving a list of all customers, and fetching details of a single customer. - Create Customer - Fetch Customer/Customers - name: Payout description: |- - Make Transfer - Verify Transfer - name: Status description: '- Service Health check' - name: Verification - name: Webhook description: |- ## EVENTS `account.incoming-transaction` ``` json { "event": "account.incoming-transaction", "data": { "id": "string", "amount": "float", "currency": "string", "transactionType": "string", "entryDate": "datetime", "uniqueRef": "string", "account": { "id": "string", "bankAccount": { "accountName": "string", "accountNumber": "string", "bank": { "code": "string", "name": "string" } }, "static": boolean, "currency": "string", "clientId": "string" } } } ``` `account.outgoing-transaction` ``` json { "event": "account.outgoing-transaction", "data": { "id": "string", "amount": "float", "currency": "string", "transactionType": "string", "entryDate": "datetime", "uniqueRef": "string", "account": { "id": "string", "bankAccount": { "accountName": "string", "accountNumber": "string", "bank": { "code": "string", "name": "string" } }, "static": boolean, "currency": "string", "clientId": "string" } } } ``` - name: Loans description: >- Partner lending API. Enables fintech partners to originate business loans for their end-customers. - Enroll customers for lending and trigger KYC - Submit loan applications and supporting documents - Manage offer acceptance, disbursement account, and post-offer steps - Charge repayments and retrieve repayment schedules paths: /v1/accounts: get: tags: - Accounts summary: Fetch Accounts description: >- This endpoint makes an HTTP GET request to retrieve a list of accounts with pagination. It fetches a specified number of accounts per page, as per the provided page and limit parameters. The response to the request returns a status code of 200 and a JSON object with the following structure: - status: Indicates the status of the response. - message: A message related to the response status. - data: An array containing account information, including bank details, owner information, account type, mode, and timestamps. - account: Details of the account including bank name, bank code, account name, and account number. - owner: Information about the account owner, such as ID, first name, last name, email, and phone. - account_type: Type of the account. - mode: Mode of the account. - created_at: Timestamp indicating the creation time of the account. - updated_at: Timestamp indicating the last update time of the account. - total: Indicates the total number of accounts available. Example responses for this request include: 1. A response with an array of account details and owner information. parameters: - name: x-carbon-key in: header schema: type: string required: true example: '{{access_token}}' - name: page in: query schema: type: integer example: '0' - name: limit in: query schema: type: integer example: '2' - name: account_number in: query description: Filter accounts by a specific account number. required: false schema: type: string example: '6009490194' - name: account_name in: query description: Filter accounts by account name (partial match supported). required: false schema: type: string example: Ola Ajayi - name: customer_id in: query description: Filter accounts belonging to a specific customer. required: false schema: type: string example: 965c4bf7-e86b-45ca-b286-1ee6f32e991b responses: '200': description: OK headers: Content-Security-Policy: schema: type: string example: >- default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests Cross-Origin-Opener-Policy: schema: type: string example: same-origin Cross-Origin-Resource-Policy: schema: type: string example: same-origin Origin-Agent-Cluster: schema: type: string example: '?1' Referrer-Policy: schema: type: string example: no-referrer Strict-Transport-Security: schema: type: string example: max-age=15552000; includeSubDomains X-Content-Type-Options: schema: type: string example: nosniff X-DNS-Prefetch-Control: schema: type: string example: 'off' X-Download-Options: schema: type: string example: noopen X-Frame-Options: schema: type: string example: SAMEORIGIN X-Permitted-Cross-Domain-Policies: schema: type: string example: none X-XSS-Protection: schema: type: integer example: '0' RateLimit-Policy: schema: type: string example: 100;w=900 RateLimit-Limit: schema: type: integer example: '100' RateLimit-Remaining: schema: type: integer example: '99' RateLimit-Reset: schema: type: integer example: '900' Content-Type: schema: type: string example: application/json; charset=utf-8 Content-Length: schema: type: integer example: '536' ETag: schema: type: string example: W/"218-YUj9GR8TFXvUAKuaoK6BauoaHlM" Date: schema: type: string example: Wed, 28 Feb 2024 00:07:20 GMT Connection: schema: type: string example: keep-alive Keep-Alive: schema: type: string example: timeout=5 content: application/json: schema: type: object examples: example-0: summary: Account value: status: success message: Account fetched successfully data: id: 3529237a-8ae1-4d63-a6ad-419fae3b9f5e account: bank_name: CARBON bank_code: '565' account_name: Ola Ajayi account_number: '6009490194' balance: 350833340 available_balance: 350833340 locked: false owner: id: 965c4bf7-e86b-45ca-b286-1ee6f32e991b first_name: ola last_name: ajayi email: ola@yahoo.com phone: '08071000030' is_static: true mode: sandbox created_at: '2024-02-28T01:01:29.000Z' updated_at: '2024-02-28T01:01:29.000Z' example-1: summary: '200' value: status: success message: Accounts fetched successfully data: - account: bank_name: CARBON bank_code: '565' account_name: Ola Ajayi account_number: '6009490194' owner: id: 965c4bf7-e86b-45ca-b286-1ee6f32e991b first_name: null last_name: null email: ola@yahoo.com phone: '08071000030' account_type: static mode: sandbox created_at: '2024-02-28T01:01:29.000Z' updated_at: '2024-02-28T01:01:29.000Z' total: '1' components: securitySchemes: apikeyAuth: type: apiKey in: header name: apikey description: Provide your API key in the 'apikey' header. ````