# Pix Claim

A Pix Claim is used to port or own a Pix key from another institution to your workspace.

Here we will show you how to create and manage them.

### The Pix Claim Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix claim. |
| `type` | STRING | Type of the claim. Options: "ownership", "portability". |
| `keyType` | STRING | Type of the Pix key being claimed. Options: "cpf", "cnpj", "phone", "email", "evp". |
| `keyId` | STRING | Value of the Pix key being claimed. |
| `status` | STRING | Current status. Options: "created", "failed", "delivered", "confirmed", "success", "canceled". |
| `flow` | STRING | Direction of the Pix claim. Options: "out" (you are claiming a key from another institution), "in" (another institution is claiming a key from you). |
| `name` | STRING | Name of the account holder. |
| `taxId` | STRING | CPF or CNPJ of the account holder. |
| `bacenId` | STRING | Central Bank ID for this Pix claim. |
| `tags` | LIST OF STRINGS | Tags associated with the Pix claim. |
| `claimerBankCode` | STRING | Bank ISPB code of the institution claiming the Pix key. |
| `claimedBankCode` | STRING | Bank ISPB code of the institution that currently owns the Pix key. |
| `branchCode` | STRING | Branch code of the linked bank account. |
| `accountNumber` | STRING | Account number of the linked bank account. |
| `accountType` | STRING | Type of the linked bank account. Options: "checking", "savings", "salary", "payment", "other". |
| `accountCreated` | STRING | Creation date of the linked bank account. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create a Pix Claim

`POST /v2/pix-claim`

Initiate a Pix key portability or ownership claim.

An ownership claim changes the holder of a Pix Key (only phone keyType). A portability claim changes the linked account without changing the holder (phone, email or taxId keyTypes).

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountCreated` | REQUIRED | Creation date of your linked bank account. |
| `accountNumber` | REQUIRED | Your bank account number. |
| `accountType` | REQUIRED | Your bank account type. Options: "checking", "savings", "salary", "payment". |
| `branchCode` | REQUIRED | Your bank account branch code. |
| `name` | REQUIRED | Name of the account holder. |
| `taxId` | REQUIRED | CPF or CNPJ of the account holder. |
| `keyId` | REQUIRED | Value of the Pix key being claimed. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

**Request**

```python
import starkinfra

claim = starkinfra.pixclaim.create(
    starkinfra.PixClaim(
        account_created="2022-01-01",
        account_number="10000-0",
        account_type="checking",
        branch_code="0001",
        name="Jon Snow",
        tax_id="012.345.678-90",
        key_id="jon.snow@starkinfra.com",
        tags=["claim", "portability"]
    )
)

print(claim)
```

**Response**

```python
PixClaim(
    id="5656565656565656",
    type="portability",
    key_type="email",
    key_id="jon.snow@starkinfra.com",
    status="created",
    flow="out",
    name="Jon Snow",
    tax_id="012.345.678-90",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["claim", "portability"],
    claimer_bank_code="20018183",
    claimed_bank_code="60701190",
    branch_code="0001",
    account_number="10000-0",
    account_type="checking",
    account_created="2022-01-01T00:00:00+00:00",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### List Pix Claims

`GET /v2/pix-claim`

List and filter all Pix claims. Results are paged.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `bacenId` | OPTIONAL | Filter by the Central Bank ID of the Pix claim. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `flow` | OPTIONAL | Filter by claim flow. Options: "in" (incoming claims), "out" (outgoing claims). |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `keyId` | OPTIONAL | Filter by the Pix key value. |
| `keyType` | OPTIONAL | Filter by the type of the Pix key being claimed. Options: "cpf", "cnpj", "phone", "email", "evp". |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter by status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `type` | OPTIONAL | Filter by claim type. |

**Request**

```python
import starkinfra

claims = starkinfra.pixclaim.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["delivered"],
    type="portability",
    flow="out"
)

for claim in claims:
    print(claim)
```

**Response**

```python
<generator object query at 0x...>

PixClaim(
    id="5656565656565656",
    type="portability",
    key_type="email",
    key_id="jon.snow@starkinfra.com",
    status="delivered",
    flow="out",
    name="Jon Snow",
    tax_id="012.345.678-90",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["claim", "portability"],
    claimer_bank_code="20018183",
    claimed_bank_code="60701190",
    branch_code="0001",
    account_number="10000-0",
    account_type="checking",
    account_created="2022-01-01T00:00:00+00:00",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Claim

`GET /v2/pix-claim/:id`

Get a single Pix claim by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix claim entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

claim = starkinfra.pixclaim.get("5656565656565656")

print(claim)
```

**Response**

```python
PixClaim(
    id="5656565656565656",
    type="portability",
    key_type="email",
    key_id="jon.snow@starkinfra.com",
    status="delivered",
    flow="out",
    name="Jon Snow",
    tax_id="012.345.678-90",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["claim", "portability"],
    claimer_bank_code="20018183",
    claimed_bank_code="60701190",
    branch_code="0001",
    account_number="10000-0",
    account_type="checking",
    account_created="2022-01-01T00:00:00+00:00",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Update a Pix Claim

`PATCH /v2/pix-claim/:id`

Confirm or cancel an incoming Pix claim.

You must answer an inbound Pix Claim within 7 days of its status changing to delivered. If unanswered, a portability claim is rejected by default and an ownership claim is accepted by default, both with reason defaultBehavior.

You can only confirm Pix Claims with delivered status; confirming deletes the referenced Pix Key from Stark Infra and the Central Bank.

You can only cancel Pix Claims with delivered or confirmed status.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix claim entity. |
| `status` | REQUIRED | New status for the claim. Options: "confirmed", "canceled". |
| `reason` | OPTIONAL | Reason for the status change. Options: "userRequested", "accountClosure", "fraud". Defaults to "userRequested". |

**Request**

```python
import starkinfra

claim = starkinfra.pixclaim.update(
    "5656565656565656",
    status="confirmed",
    reason="userRequested"
)

print(claim)
```

**Response**

```python
PixClaim(
    id="5656565656565656",
    type="portability",
    key_type="email",
    key_id="jon.snow@starkinfra.com",
    status="confirmed",
    flow="out",
    name="Jon Snow",
    tax_id="012.345.678-90",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["claim", "portability"],
    claimer_bank_code="20018183",
    claimed_bank_code="60701190",
    branch_code="0001",
    account_number="10000-0",
    account_type="checking",
    account_created="2022-01-01T00:00:00+00:00",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:02:00+00:00"
)
```

### List Pix Claim Logs

`GET /v2/pix-claim/log`

Get a paged list of all Pix claim logs.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `claimIds` | OPTIONAL | List of strings to filter logs by their Pix claim ids. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | Filter by Pix claim ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filter logs by log types. |

**Request**

```python
import starkinfra

logs = starkinfra.pixclaim.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["confirmed"],
    claim_ids=["5656565656565656"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    claim=PixClaim(
        id="5656565656565656",
        type="portability",
        key_type="email",
        key_id="jon.snow@starkinfra.com",
        status="delivered",
        flow="out",
        name="Jon Snow",
        tax_id="012.345.678-90",
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        tags=["claim", "portability"],
        claimer_bank_code="20018183",
        claimed_bank_code="60701190",
        branch_code="0001",
        account_number="10000-0",
        account_type="checking",
        account_created="2022-01-01T00:00:00+00:00",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    type="confirmed",
    errors=[],
    reason="userRequested",
    created="2022-01-01T00:02:00+00:00"
)
```

### Get a Pix Claim Log

`GET /v2/pix-claim/log/:id`

Get a single Pix claim log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

log = starkinfra.pixclaim.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    claim=PixClaim(
        id="5656565656565656",
        type="portability",
        key_type="email",
        key_id="jon.snow@starkinfra.com",
        status="delivered",
        flow="out",
        name="Jon Snow",
        tax_id="012.345.678-90",
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        tags=["claim", "portability"],
        claimer_bank_code="20018183",
        claimed_bank_code="60701190",
        branch_code="0001",
        account_number="10000-0",
        account_type="checking",
        account_created="2022-01-01T00:00:00+00:00",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    type="confirmed",
    errors=[],
    reason="userRequested",
    created="2022-01-01T00:02:00+00:00"
)
```

## Available Languages

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

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