# Issuing Holder

The Issuing Holder resource represents the card holder entity in your workspace.

A holder is associated with one or more issuing cards and defines who can use the cards issued.

You can set rules on the holder level to control spending limits and merchant restrictions.

### The Issuing Holder object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing holder. |
| `name` | STRING | Full name of the holder. |
| `taxId` | STRING | Holder CPF (11 digits) or CNPJ (14 digits). |
| `externalId` | STRING | Your external reference for this holder. Must be unique per workspace to prevent duplicates. |
| `status` | STRING | Current holder status. Options: "active", "blocked", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the holder. |
| `rules` | LIST OF OBJECTS | List of spending rule objects applied to the holder. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Issuing Holders

`POST /v2/issuing-holder`

Use this route to create up to 100 new issuing holders at a time.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | Full name of the holder. Example: "Tony Stark". |
| `taxId` | REQUIRED | Holder CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: "012.345.678-90". |
| `externalId` | REQUIRED | Your unique identifier for this holder, used to prevent duplicates. Example: "my-holder-id-1234". |
| `rules` | OPTIONAL | List of spending rule objects to apply to the holder. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules". |

**Request**

```python
import starkinfra

holders = starkinfra.issuingholder.create([
    starkinfra.IssuingHolder(
        name="Tony Stark",
        tax_id="012.345.678-90",
        external_id="my-holder-id-1234",
        tags=["department: tech", "team: backend"],
        rules=[
            starkinfra.IssuingRule(
                name="max-spend",
                interval="day",
                amount=10000,
                currency_code="BRL"
            )
        ]
    )
])

for holder in holders:
    print(holder)
```

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=active,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Holders

`GET /v2/issuing-holder`

Get a list of issuing holders in chunks of at most 100.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `status` | OPTIONAL | Filter holders by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules". |

**Request**

```python
import starkinfra

holders = starkinfra.issuingholder.query(
    limit=10,
    status="active"
)

for holder in holders:
    print(holder)
```

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=active,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Holder

`GET /v2/issuing-holder/:id`

Get a single issuing holder by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the issuing holder entity. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules". |

**Request**

```python
import starkinfra

holder = starkinfra.issuingholder.get("5715709195239424")

print(holder)
```

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=active,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update an Issuing Holder

`PATCH /v2/issuing-holder/:id`

Update the properties of an existing issuing holder.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the issuing holder entity. |
| `status` | OPTIONAL | Status to update the holder to. Options: "active", "blocked". |
| `name` | OPTIONAL | New full name of the holder. |
| `rules` | OPTIONAL | New list of spending rule objects to apply to the holder. |
| `tags` | OPTIONAL | New array of strings to tag the holder. |

**Request**

```python
import starkinfra

holder = starkinfra.issuingholder.update(
    "5715709195239424",
    status="blocked"
)

print(holder)
```

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=blocked,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### Cancel an Issuing Holder

`DELETE /v2/issuing-holder/:id`

Cancel an issuing holder. This action is irreversible.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the issuing holder entity to cancel. |

**Request**

```python
import starkinfra

holder = starkinfra.issuingholder.cancel("5715709195239424")

print(holder)
```

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=canceled,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Issuing Holder Logs

`GET /v2/issuing-holder/log`

Get a paged list of issuing holder logs.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `types` | OPTIONAL | Filter logs by log types. |
| `holderIds` | OPTIONAL | Array of holder ids to filter logs. |
| `ids` | OPTIONAL | List of strings to get specific log entities by ids. |

**Request**

```python
import starkinfra

logs = starkinfra.issuingholder.log.query(limit=10)

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

**Response**

```python
Log(
    id=5715709195239424,
    type=created,
    holder=IssuingHolder(id=5715709195239424, name=Tony Stark, status=active),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Holder Log

`GET /v2/issuing-holder/log/:id`

Get a single issuing holder log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity. |

**Request**

```python
import starkinfra

log = starkinfra.issuingholder.log.get("5715709195239424")

print(log)
```

**Response**

```python
Log(
    id=5715709195239424,
    type=created,
    holder=IssuingHolder(id=5715709195239424, name=Tony Stark, status=active),
    created=2022-01-01 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/issuing-holder-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/issuing-holder-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/issuing-holder-php.md)
- [Java](https://docs.starkinfra.com/api/v2/issuing-holder-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/issuing-holder-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/issuing-holder-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/issuing-holder-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/issuing-holder-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/issuing-holder-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/issuing-holder-curl.md)