# Verified Account

Verified Accounts let you confirm that a bank account really belongs to a given tax ID before you send money to it.

You can verify an account in two ways: by informing the receiver's Pix key, or by informing the receiver's full bank details. Either way, we send a R$0.01 verification transfer to the account and only mark it as "active" if that transfer succeeds.

Once a Verified Account is active, you can use its id to create **Verified Transfers**, which reuse the verified receiver data instead of asking you for it again.

### The Verified Account object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `bankCode` | STRING | Receiver bank code or ISPB. Empty while an account verified by Pix key has not been resolved. |
| `bankName` | STRING | Name of the receiver bank institution. We fill it in when we resolve a Pix key. It stays empty for accounts verified with bank details. |
| `branchCode` | STRING | Receiver bank account branch. Empty while an account verified by Pix key has not been resolved. |
| `created` | STRING | Creation datetime. Example: "2024-05-10T17:10:57.261868+00:00". |
| `id` | STRING | Unique id for the Verified Account. Use it to create Verified Transfers to this receiver. |
| `keyId` | STRING | Pix key used to verify the account. Empty when the account was verified with bank details. Example: "arya.stark@starkbank.com". |
| `name` | STRING | Receiver full name. Informed by you when verifying with bank details, or resolved by us from the Pix key. Example: "Arya Stark". |
| `number` | STRING | Receiver bank account number. Empty while an account verified by Pix key has not been resolved. |
| `status` | STRING | Current Verified Account status. Options: "creating", "created", "processing", "active", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the Verified Account. All tags are returned in lowercase. |
| `taxId` | STRING | Receiver CPF or CNPJ, as informed on creation. Example: "012.345.678-90". |
| `type` | STRING | Receiver bank account type. Options: "checking", "savings", "salary", "payment". Empty while an account verified by Pix key has not been resolved. |
| `updated` | STRING | Last update datetime. Example: "2024-05-10T17:11:43.108224+00:00". |

### Create Verified Accounts

`POST /v2/verified-account`

This route is used to verify that a bank account belongs to the informed tax ID before you send money to it.

For each account, inform either the receiver's Pix key or the receiver's full bank details. Sending both in the same account is not allowed, and sending neither is not allowed either.

You can create up to 100 Verified Accounts in a single request.

**NOTE:**Verification is done with a real R$0.01 transfer to the receiver. It appears in your Transfer list tagged with the Verified Account id and is charged your usual transfer fee.

**NOTE:**It is not possible to create more than three Verified Accounts for the same tax ID within 24 hours. Failed and canceled Verified Accounts do not count towards this limit.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `taxId` | REQUIRED | Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: "012.345.678-90" |
| `bankCode` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver bank ISPB (8 digits) or bank code (1 to 3 digits). Example: "20018183" or "341" |
| `branchCode` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver bank account branch. Use "-" in case there is a validation digit. Example: "1234-5" |
| `keyId` | CONDITIONALLY REQUIRED | Required when verifying with a Pix key. The receiver's Pix key, which can be a CPF, a CNPJ, an email, a phone or an EVP. Example: "arya.stark@starkbank.com" |
| `name` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver full name, with at least 3 characters. Example: "Arya Stark" |
| `number` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver bank account number. Use "-" before the validation digit. Example: "76543-8" |
| `type` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver bank account type. Options are "checking", "savings", "salary" and "payment". Example: "checking" |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. Each tag can have up to 100 characters and all tags will be converted to lowercase. Example: ["daenerys", "invoice/1234"] |

**Request**

```python
import starkbank

accounts = starkbank.verifiedaccount.create([
    starkbank.VerifiedAccount(
        tax_id="911.544.440-66",
        name="Daenerys Targaryen Stormborn",
        bank_code="341",
        branch_code="2201",
        number="76543-8",
        type="checking",
        tags=["daenerys", "invoice/1234"]
    ),
    starkbank.VerifiedAccount(
        tax_id="039.946.040-36",
        key_id="arya.stark@starkbank.com",
        tags=["arya"]
    )
])

for account in accounts:
    print(account)
```

**Response**

```python
VerifiedAccount(
    id=5155165527080960,
    tax_id=911.544.440-66,
    bank_code=341,
    branch_code=2201,
    key_id=,
    name=Daenerys Targaryen Stormborn,
    number=76543-8,
    type=checking,
    tags=['daenerys', 'invoice/1234'],
    bank_name=,
    status=creating,
    created=2024-05-10 17:10:57.261868,
    updated=2024-05-10 17:10:57.261868
)
VerifiedAccount(
    id=6244185527080960,
    tax_id=039.946.040-36,
    bank_code=,
    branch_code=,
    key_id=arya.stark@starkbank.com,
    name=,
    number=,
    type=,
    tags=['arya'],
    bank_name=,
    status=creating,
    created=2024-05-10 17:10:57.318402,
    updated=2024-05-10 17:10:57.318402
)
```

### List Verified Accounts

`GET /v2/verified-account`

Get a list of Verified Accounts in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. Maximum of 100 ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default value = 100. |
| `status` | OPTIONAL | Filter Verified Accounts by the specified status. Options: "creating", "created", "processing", "active", "failed", "canceled". |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `taxId` | OPTIONAL | Filter Verified Accounts created for the specified tax ID. Not available in the SDKs. Example: "012.345.678-90" |

**Request**

```python
import starkbank

accounts = starkbank.verifiedaccount.query(
    limit=10,
    status="active",
    after="2024-05-01",
    before="2024-05-30"
)

for account in accounts:
    print(account)
```

**Response**

```python
VerifiedAccount(
    id=6244185527080960,
    tax_id=039.946.040-36,
    bank_code=20018183,
    branch_code=0001,
    key_id=arya.stark@starkbank.com,
    name=Arya Stark,
    number=6341320293482496,
    type=checking,
    tags=['arya'],
    bank_name=Stark Bank S.A.,
    status=active,
    created=2024-05-10 17:10:57.318402,
    updated=2024-05-10 17:12:31.904771
)
```

### Get a Verified Account

`GET /v2/verified-account/:id`

Get a single Verified Account by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Verified Account you want to retrieve. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

account = starkbank.verifiedaccount.get("5155165527080960")

print(account)
```

**Response**

```python
VerifiedAccount(
    id=5155165527080960,
    tax_id=911.544.440-66,
    bank_code=341,
    branch_code=2201,
    key_id=,
    name=Daenerys Targaryen Stormborn,
    number=76543-8,
    type=checking,
    tags=['daenerys', 'invoice/1234'],
    bank_name=,
    status=active,
    created=2024-05-10 17:10:57.261868,
    updated=2024-05-10 17:12:30.117633
)
```

### Cancel a Verified Account

`DELETE /v2/verified-account/:id`

Cancel a Verified Account so it can no longer be used as a receiver in Verified Transfers.

**NOTE:**Only Verified Accounts with status "creating", "created" or "active" can be canceled. Accounts that are already "processing", "failed" or "canceled" will be rejected.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Verified Account you want to cancel. |

**Request**

```python
import starkbank

account = starkbank.verifiedaccount.cancel("5155165527080960")

print(account)
```

**Response**

```python
VerifiedAccount(
    id=5155165527080960,
    tax_id=911.544.440-66,
    bank_code=341,
    branch_code=2201,
    key_id=,
    name=Daenerys Targaryen Stormborn,
    number=76543-8,
    type=checking,
    tags=['daenerys', 'invoice/1234'],
    bank_name=,
    status=canceled,
    created=2024-05-10 17:10:57.261868,
    updated=2024-05-11 13:04:12.552019
)
```

### List Verified Account Logs

`GET /v2/verified-account/log`

Get a list of Verified Account Logs in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountIds` | OPTIONAL | Array of Verified Account ids that are linked to the logs you desire. Maximum of 100 ids. |
| `after` | OPTIONAL | Filter logs created after this date. |
| `before` | OPTIONAL | Filter logs created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default value = 100. |
| `types` | OPTIONAL | Filters logs by log types. Options: "creating", "created", "processing", "active", "failed", "canceled". |

**Request**

```python
import starkbank

logs = starkbank.verifiedaccount.log.query(
    limit=10,
    types=["failed"],
    after="2024-05-01",
    before="2024-05-30"
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id=5662318377566208,
    type=failed,
    errors=[{'code': 'keyNotFound', 'message': 'The key is not registered'}],
    account=VerifiedAccount(
        id=6244185527080960,
        tax_id=039.946.040-36,
        bank_code=,
        branch_code=,
        key_id=arya.stark@starkbank.com,
        name=,
        number=,
        type=,
        tags=['arya'],
        bank_name=,
        status=failed,
        created=2024-05-10 17:10:57.318402,
        updated=2024-05-10 17:11:43.108224
    ),
    created=2024-05-10 17:11:43.108224
)
```

### Get a Verified Account Log

`GET /v2/verified-account/log/:id`

Get a single Verified Account Log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Verified Account Log you want to retrieve. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

log = starkbank.verifiedaccount.log.get("5662318377566208")

print(log)
```

**Response**

```python
Log(
    id=5662318377566208,
    type=failed,
    errors=[{'code': 'keyNotFound', 'message': 'The key is not registered'}],
    account=VerifiedAccount(
        id=6244185527080960,
        tax_id=039.946.040-36,
        bank_code=,
        branch_code=,
        key_id=arya.stark@starkbank.com,
        name=,
        number=,
        type=,
        tags=['arya'],
        bank_name=,
        status=failed,
        created=2024-05-10 17:10:57.318402,
        updated=2024-05-10 17:11:43.108224
    ),
    created=2024-05-10 17:11:43.108224
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/verified-account-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/verified-account-node.md)
- [PHP](https://docs.starkbank.com/api/v2/verified-account-php.md)
- [Java](https://docs.starkbank.com/api/v2/verified-account-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/verified-account-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/verified-account-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/verified-account-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/verified-account-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/verified-account-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/verified-account-curl.md)