---
title: "Create a site"
description: "Add a subdomain or a custom domain for your campaigns."
canonical: https://www.charitips.com/docs/api-reference/create-site
---

# Create a site

`POST /v1/sites`

Add a subdomain or a custom domain for your campaigns.

**Authentication**: Bearer access token.

## Body

- `subdomain` (string): Subdomain to register. Required if customDomain not provided.
- `customDomain` (string): Custom domain to register. Required if subdomain not provided.
- `accountId` (string, UUID): Only required to link the created entity to a child account instead of the current one.

## Response 201

- `siteId` (string, required)
- `subdomain` (string)
- `customDomain` (string)
- `accountId` (string, required)
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

## Errors

- 400 `At least one of subdomain and customDomain is required.`: Send `subdomain`, `customDomain`, or both. See https://www.charitips.com/docs/api-reference/create-site.md.
- 400 `Invalid customDomain`: A custom domain cannot contain a Charitips domain (charitips.com, charitips.net, charitips.org, charitips.tech, chari.tips). Use a domain you own, or `subdomain` for an address under Charitips. See https://www.charitips.com/docs/api-reference/create-site.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.
- 402 `Plan upgrade required`: Your plan does not include this feature. Upgrade the plan from the dashboard, then retry. See https://www.charitips.com/docs/overview/plans.md.
- 403 `New subdomain site can't be created`: Accounts with account hierarchy cannot create a subdomain site. Create the site with `customDomain`; for a child account, the parent sets its subdomain with update-account. See https://www.charitips.com/docs/api-reference/update-account.md.
- 403 `Account not validated`: The account behind your credentials has not finished onboarding. Complete it in the dashboard, or contact us. See https://www.charitips.com/docs/api-reference/troubleshooting.md#calls-answer-403-account-not-active-account-not-validated-or-account-closed.
- 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.

## Example

```bash
curl -X POST https://api.sandbox.charitips.com/v1/sites \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "donations"
  }'
```

```javascript
const response = await fetch('https://api.sandbox.charitips.com/v1/sites', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHARITIPS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "subdomain": "donations"
  }),
});
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/sites",
    headers={"Authorization": f"Bearer {os.environ['CHARITIPS_TOKEN']}"},
    json={
      "subdomain": "donations"
    },
)
response.raise_for_status()
data = response.json()
```

## Response example (201, placeholder values)

```json
{
  "siteId": "<siteId>",
  "subdomain": "<subdomain>",
  "customDomain": "<customDomain>",
  "accountId": "<accountId>",
  "createdAt": "<createdAt>",
  "updatedAt": "<updatedAt>"
}
```