# Corporate Holder

The Corporate Holder resource describes a card holder that may group several corporate cards.

Holders support spending rules that apply to every card bound to them, so you can cap how much a person or a team spends in a given interval without touching each card.

You can also grant access to a holder to specific members or projects of your Workspace through the permissions array, and bind the holder to a cost center to organize your corporate expenses.

After a holder is created, issue its cards with the Corporate Card resource.

### The Corporate Holder object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the corporate holder. Example: "5155165527080960". |
| `name` | STRING | Card holder name. Example: "Iron Bank S.A.". |
| `status` | STRING | Current corporate holder status. Options: "active", "blocked", "canceled". |
| `centerId` | STRING | Id of the cost center the holder is bound to. Returned as an empty string when the holder has no cost center. Example: "5656565656565656". |
| `tags` | LIST OF STRINGS | Tags associated with the corporate holder. Example: ["traveler employee"]. |
| `updated` | STRING | Latest update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `permissions` | LIST OF OBJECTS | List of permission objects representing the access granted to members and projects of your Workspace for this particular card holder. |
| `rules` | LIST OF OBJECTS | List of holder spending rule objects. Pass "rules" in the expand parameter to also receive the counters and the currency and merchant details of each rule. |
| `centerName` | STRING | Name of the cost center the holder is bound to. Only returned when "centerName" is passed in the expand parameter. |

### Create Corporate Holders

`POST /v2/corporate-holder`

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

**NOTE:**Holder names must be unique among the active holders of your Workspace. Creating a holder with the name of another active holder will be rejected.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | Card holder name. Example: "Iron Bank S.A.". |
| `centerId` | OPTIONAL | Id of the target cost center. Example: "5656565656565656". |
| `permissions` | OPTIONAL | Array of permission objects granting access to this holder. Each object requires an ownerType and an ownerId. Example: ``` [{"ownerType": "project", "ownerId": "6253551860842496"}, {"ownerType": "member", "ownerId": "6227829385592832"}] ``` |
| `rules` | OPTIONAL | Array of rule objects with the spending rules that will apply to every card bound to this holder. Example: ``` [{"name": "General USD", "interval": "day", "amount": 100000, "currencyCode": "USD"}] ``` |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. All tags will be converted to lowercase. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "centerName". |

**Request**

```python
import starkbank

holders = starkbank.corporateholder.create([
    starkbank.CorporateHolder(
        name="Iron Bank S.A.",
        tags=["Traveler Employee"],
        permissions=[
            starkbank.corporateholder.Permission(
                owner_id="6253551860842496",
                owner_type="project"
            )
        ],
        rules=[
            starkbank.CorporateRule(
                name="General USD",
                interval="day",
                amount=100000,
                currency_code="USD",
                categories=[starkbank.MerchantCategory(code="fastFoodRestaurants")],
                countries=[starkbank.MerchantCountry(code="USA")],
                methods=[starkbank.CardMethod(code="token")]
            )
        ]
    )
])

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

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=active,
    tags=['traveler employee'],
    permissions=[
        Permission(
            owner_email=,
            owner_id=6253551860842496,
            owner_name=Iron Bank Sandbox,
            owner_picture_url=,
            owner_status=active,
            owner_type=project,
            created=2022-01-01 00:00:00
        )
    ],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-01 00:00:00,
    created=2022-01-01 00:00:00
)
```

### List Corporate Holders

`GET /v2/corporate-holder`

Get a list of corporate holders 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. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "centerName". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of up to 100 strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `names` | OPTIONAL | List of up to 100 exact holder names to filter retrieved entities. Not available in the SDKs. |
| `search` | OPTIONAL | String used to search holders by name. When it is informed, no cursor is returned. Not available in the SDKs. |
| `status` | OPTIONAL | Filter holders by the specified status. Options: "active", "blocked", "canceled". |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

holders = starkbank.corporateholder.query(
    limit=10,
    status=["active"]
)

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

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=active,
    tags=['traveler employee'],
    permissions=[
        Permission(
            owner_email=,
            owner_id=6253551860842496,
            owner_name=Iron Bank Sandbox,
            owner_picture_url=,
            owner_status=active,
            owner_type=project,
            created=2022-01-01 00:00:00
        )
    ],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-01 00:00:00,
    created=2022-01-01 00:00:00
)
```

### Get a Corporate Holder

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

Get a single corporate holder by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate holder entity. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "centerName". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

holder = starkbank.corporateholder.get(
    "5155165527080960",
    expand=["rules"]
)

print(holder)
```

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=active,
    tags=['traveler employee'],
    permissions=[
        Permission(
            owner_email=,
            owner_id=6253551860842496,
            owner_name=Iron Bank Sandbox,
            owner_picture_url=,
            owner_status=active,
            owner_type=project,
            created=2022-01-01 00:00:00
        )
    ],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            currency_symbol=US$,
            currency_name=American Dollar,
            counter_amount=0,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=food)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-01 00:00:00,
    created=2022-01-01 00:00:00
)
```

### Update a Corporate Holder

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

Update a single corporate holder. At least one updatable parameter must be informed.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate holder entity. |
| `centerId` | OPTIONAL | Id of the new target cost center. Example: "5656565656565656". |
| `name` | OPTIONAL | New card holder name. It must be unique among the active holders of your Workspace. Example: "Iron Bank S.A.". |
| `permissions` | OPTIONAL | New array of permission objects. It replaces the current permissions of the holder. Example: ``` [{"ownerType": "project", "ownerId": "6253551860842496"}] ``` |
| `rules` | OPTIONAL | New array of rule objects with the spending rules of the holder. Example: ``` [{"name": "General USD", "interval": "day", "amount": 100000, "currencyCode": "USD"}] ``` |
| `status` | OPTIONAL | You may block the holder by passing "blocked" in the status, and unblock it by passing "active". |
| `tags` | OPTIONAL | New array of up to 100 strings to tag the holder. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

holder = starkbank.corporateholder.update(
    "5155165527080960",
    status="blocked"
)

print(holder)
```

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=blocked,
    tags=['traveler employee'],
    permissions=[
        Permission(
            owner_email=,
            owner_id=6253551860842496,
            owner_name=Iron Bank Sandbox,
            owner_picture_url=,
            owner_status=active,
            owner_type=project,
            created=2022-01-01 00:00:00
        )
    ],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-02 00:00:00,
    created=2022-01-01 00:00:00
)
```

### Cancel a Corporate Holder

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

Cancel a single corporate holder by its id. Canceling a holder also removes every permission granted on it. This action is irreversible.

**Parameters**

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

**Request**

```python
import starkbank

holder = starkbank.corporateholder.cancel("5155165527080960")

print(holder)
```

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=canceled,
    tags=['traveler employee'],
    permissions=[],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-03 00:00:00,
    created=2022-01-01 00:00:00
)
```

### List Corporate Holder Logs

`GET /v2/corporate-holder/log`

Get a paged list of corporate holder logs. A log tracks a change in the corporate holder entity according to its life cycle.

**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. |
| `holderIds` | OPTIONAL | Array of up to 30 corporate holder ids that are linked to the logs you desire. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. Options: "created", "blocked", "unblocked", "updated", "canceled". |

**Request**

```python
import starkbank

logs = starkbank.corporateholder.log.query(
    limit=10,
    types=["blocked"]
)

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

**Response**

```python
Log(
    id=6299741604282368,
    type=blocked,
    holder=CorporateHolder(
        id=5155165527080960,
        name=Iron Bank S.A.,
        center_id=,
        status=blocked,
        tags=['traveler employee'],
        permissions=[],
        rules=[],
        updated=2022-01-02 00:00:00,
        created=2022-01-01 00:00:00
    ),
    created=2022-01-02 00:00:00
)
```

### Get a Corporate Holder Log

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

Get a single corporate holder 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 starkbank

log = starkbank.corporateholder.log.get("6299741604282368")

print(log)
```

**Response**

```python
Log(
    id=6299741604282368,
    type=blocked,
    holder=CorporateHolder(
        id=5155165527080960,
        name=Iron Bank S.A.,
        center_id=,
        status=blocked,
        tags=['traveler employee'],
        permissions=[],
        rules=[],
        updated=2022-01-02 00:00:00,
        created=2022-01-01 00:00:00
    ),
    created=2022-01-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.starkbank.com/api/v2/corporate-holder-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/corporate-holder-node.md)
- [PHP](https://docs.starkbank.com/api/v2/corporate-holder-php.md)
- [Java](https://docs.starkbank.com/api/v2/corporate-holder-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/corporate-holder-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/corporate-holder-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/corporate-holder-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/corporate-holder-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/corporate-holder-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/corporate-holder-curl.md)