# Card Programs
> A Card Program is a set of cards you offer to your users under a single brand. Increase submits each Card Program to the card network for approval before you can start issuing cards under it.

## The Card Program object
### Example
```json
{
  "created_at": "2020-01-31T23:59:59Z",
  "entity_id": "entity_n8y8tnk2p9339ti393yi",
  "id": "card_program_b9v1az87138o8lvw6fjy",
  "idempotency_key": null,
  "name": "Karat Business Credit",
  "network": "visa",
  "type": "card_program",
  "visa": {
    "description": "A credit card for small business owners.",
    "estimates": {
      "year_1": {
        "number_of_cards": 200,
        "usd_volume": 100
      },
      "year_2": {
        "number_of_cards": 200,
        "usd_volume": 100
      },
      "year_3": {
        "number_of_cards": 200,
        "usd_volume": 100
      },
      "year_4": {
        "number_of_cards": 200,
        "usd_volume": 100
      },
      "year_5": {
        "number_of_cards": 200,
        "usd_volume": 100
      }
    },
    "target_audience": "Small business owners in the United States."
  }
}
```
### Attributes
- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Card Program was created.

- `entity_id` (string)
  The identifier of the Entity that will offer the Card Program to its users.

- `id` (string)
  The Card Program identifier.

- `idempotency_key` (string, nullable)
  The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `name` (string)
  The name you chose for the Card Program.

- `network` (enum)
  The network the Card Program is offered on. Details specific to the network will be under the object with the same identifier as the network.
  Cases:
  * `visa` (Visa)

- `type` (string)
  A constant representing the object's type. For this resource it will always be `card_program`.

- `visa` (dictionary, nullable)
  The details Visa requires in order to approve the Card Program. This field will be present in the JSON response if and only if `network` is equal to `visa`.

  - `visa.description` (string)
    A detailed description of the Card Program's objectives and rationale: the program offering, its value proposition, the overall marketing strategy, and any other pertinent information.

  - `visa.estimates` (dictionary)
    Your projections for the first five years of the Card Program.

      - `visa.estimates.year_1` (dictionary)
        Projections for the first year.

            - `visa.estimates.year_1.number_of_cards` (integer)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_1.usd_volume` (integer)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

      - `visa.estimates.year_2` (dictionary)
        Projections for the second year.

            - `visa.estimates.year_2.number_of_cards` (integer)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_2.usd_volume` (integer)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

      - `visa.estimates.year_3` (dictionary)
        Projections for the third year.

            - `visa.estimates.year_3.number_of_cards` (integer)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_3.usd_volume` (integer)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

      - `visa.estimates.year_4` (dictionary)
        Projections for the fourth year.

            - `visa.estimates.year_4.number_of_cards` (integer)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_4.usd_volume` (integer)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

      - `visa.estimates.year_5` (dictionary)
        Projections for the fifth year.

            - `visa.estimates.year_5.number_of_cards` (integer)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_5.usd_volume` (integer)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

  - `visa.target_audience` (string)
    The audience you intend to offer the Card Program to.

## List Card Programs
GET /card_programs

### Example
```curl
curl \
  --url "${INCREASE_URL}/card_programs" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.
  Default: `100`

- `entity_id` (string, optional)
  Filter Card Programs to those offered by the specified Entity.

- `idempotency_key` (string, optional)
  Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

### Returns a Card Program List object:
```json
{
  "data": [
    {
      "created_at": "2020-01-31T23:59:59Z",
      "entity_id": "entity_n8y8tnk2p9339ti393yi",
      "id": "card_program_b9v1az87138o8lvw6fjy",
      "idempotency_key": null,
      "name": "Karat Business Credit",
      "network": "visa",
      "type": "card_program",
      "visa": {
        "description": "A credit card for small business owners.",
        "estimates": {
          "year_1": {
            "number_of_cards": 200,
            "usd_volume": 100
          },
          "year_2": {
            "number_of_cards": 200,
            "usd_volume": 100
          },
          "year_3": {
            "number_of_cards": 200,
            "usd_volume": 100
          },
          "year_4": {
            "number_of_cards": 200,
            "usd_volume": 100
          },
          "year_5": {
            "number_of_cards": 200,
            "usd_volume": 100
          }
        },
        "target_audience": "Small business owners in the United States."
      }
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Card Program
POST /card_programs

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/card_programs" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "entity_id": "entity_n8y8tnk2p9339ti393yi",
    "name": "Karat Business Credit",
    "network": "visa",
    "visa": {
      "description": "A credit card for small business owners.",
      "estimates": {
        "year_1": {
          "number_of_cards": 200,
          "usd_volume": 100
        },
        "year_2": {
          "number_of_cards": 200,
          "usd_volume": 100
        },
        "year_3": {
          "number_of_cards": 200,
          "usd_volume": 100
        },
        "year_4": {
          "number_of_cards": 200,
          "usd_volume": 100
        },
        "year_5": {
          "number_of_cards": 200,
          "usd_volume": 100
        }
      },
      "target_audience": "Small business owners in the United States."
    }
  }'
```

### Body Parameters
- `entity_id` (string, required)
  The identifier of the Entity that will offer the Card Program to its users.

- `name` (string, required)
  The name you choose for the Card Program.

- `network` (enum, required)
  The network the Card Program is offered on. Details specific to the network are required under the sub-object with the same identifier as the network.

  Cases:
  * `visa` (Visa)

- `visa` (dictionary, optional)
  The details Visa requires in order to approve the Card Program. Required if and only if `network` is `visa`.

  - `visa.description` (string, required)
    A detailed description of the Card Program's objectives and rationale: the program offering, its value proposition, the overall marketing strategy, and any other pertinent information.

  - `visa.estimates` (dictionary, required)
    Your projections for the first five years of the Card Program.

      - `visa.estimates.year_1` (dictionary, required)
        Projections for the first year.

            - `visa.estimates.year_1.number_of_cards` (integer, required)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_1.usd_volume` (integer, required)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

      - `visa.estimates.year_2` (dictionary, required)
        Projections for the second year.

            - `visa.estimates.year_2.number_of_cards` (integer, required)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_2.usd_volume` (integer, required)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

      - `visa.estimates.year_3` (dictionary, required)
        Projections for the third year.

            - `visa.estimates.year_3.number_of_cards` (integer, required)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_3.usd_volume` (integer, required)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

      - `visa.estimates.year_4` (dictionary, required)
        Projections for the fourth year.

            - `visa.estimates.year_4.number_of_cards` (integer, required)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_4.usd_volume` (integer, required)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

      - `visa.estimates.year_5` (dictionary, required)
        Projections for the fifth year.

            - `visa.estimates.year_5.number_of_cards` (integer, required)
              The projected number of cards outstanding at the end of the year.

            - `visa.estimates.year_5.usd_volume` (integer, required)
              The projected spend volume for the year in the minor unit of the US dollar, i.e. cents.

  - `visa.target_audience` (string, required)
    The audience you intend to offer the Card Program to.

## Retrieve a Card Program
GET /card_programs/{card_program_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/card_programs/card_program_b9v1az87138o8lvw6fjy" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `card_program_id` (string, required)
  The identifier of the Card Program.