---
title: "Create a file generation request"
description: "Request the generation of a file."
canonical: https://www.charitips.com/docs/api-reference/create-file-generation-request
---

# Create a file generation request

`POST /v1/files/file-generation-requests`

Request the generation of a file. The request will be queued and processed asynchronously. ⚠️ This endpoint is rate limited.

**Authentication**: Bearer access token.

## Body

- `type` (string, required) One of `PRINT_PHYSICAL_CARDS_PDF`.
- `params` (FileGenerationRequestParams, required): File generation request parameters. For PRINT_PHYSICAL_CARDS_PDF, campaignId is required.
  - `fileRefs` (string[])
  - `campaignId` (string, UUID)

## Response 200

- `fileGenerationRequestId` (string, required)
- `hash` (string, required)
- `slug` (string, required)
- `type` (FileGenerationType, required) One of `ZIP`, `PRINT_PHYSICAL_CARDS_PDF`.
- `status` (FileGenerationStatus, required) One of `PENDING`, `DONE`, `FAILED`.
- `accountId` (string)
- `userId` (string)
- `charityId` (string)
- `charityUserId` (string)
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

## Errors

- 400 `Missing params in createFileGenerationRequest`: `params` must carry `campaignId` (required for PRINT_PHYSICAL_CARDS_PDF) or `fileRefs`. Send one of them. See https://www.charitips.com/docs/api-reference/create-file-generation-request.md.
- 400 `A field is missing, has the wrong type, or is not part of the request schema.`: `message` lists every problem. Unknown fields are rejected, not ignored: remove them rather than sending extra data. See https://www.charitips.com/docs/api-reference/errors.md.
- 401 `Unauthorized`: The access token is missing, expired or invalid. Create a new one with your client id and secret, send it as `Authorization: Bearer <accessToken>`, then retry once. Sandbox tokens only work on api.sandbox.charitips.com. See https://www.charitips.com/docs/get-started/authentication.md.
- 403 `Account closed`: The account behind these credentials is closed: no token is issued and every call is refused, reads included. Contact Charitips to reopen it. See https://www.charitips.com/docs/api-reference/troubleshooting.md#calls-answer-403-account-not-active-account-not-validated-or-account-closed.
- 429 `Rate limit exceeded`: Wait the number of seconds given in the `Retry-After` header, then send the call once more. Do not retry in a loop. See https://www.charitips.com/docs/api-reference/errors.md.

## Example

```bash
curl -X POST https://api.sandbox.charitips.com/v1/files/file-generation-requests \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PRINT_PHYSICAL_CARDS_PDF",
    "params": {
      "campaignId": "<campaignId>"
    }
  }'
```

```javascript
const response = await fetch('https://api.sandbox.charitips.com/v1/files/file-generation-requests', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHARITIPS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "PRINT_PHYSICAL_CARDS_PDF",
    "params": {
      "campaignId": "<campaignId>"
    }
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();
```

```python
import os, requests

response = requests.post(
    "https://api.sandbox.charitips.com/v1/files/file-generation-requests",
    headers={"Authorization": f"Bearer {os.environ['CHARITIPS_TOKEN']}"},
    json={
      "type": "PRINT_PHYSICAL_CARDS_PDF",
      "params": {
        "campaignId": "<campaignId>"
      }
    },
)
response.raise_for_status()
data = response.json()
```

## Response example (200, placeholder values)

```json
{
  "fileGenerationRequestId": "<fileGenerationRequestId>",
  "hash": "<hash>",
  "slug": "<slug>",
  "type": "ZIP",
  "status": "PENDING",
  "accountId": "<accountId>",
  "userId": "<userId>",
  "charityId": "<charityId>"
}
```