---
title: "Create a client"
method: POST
path: "/v1/clients"
tags: ["Clients"]
---

# Create a client

`POST /v1/clients`

## Request

- Base URL: `https://api.magnetictax.com`
- URL: `https://api.magnetictax.com/v1/clients`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- CreateClientRequest
  - `friendly_name` string, required
  - `taxpayer_tin` integer, nullable

## Response `201`

Created

- Client
  - `created_at` string, date-time
  - `friendly_name` string
  - `id` integer
  - `taxpayer_tin` integer, nullable

## Other responses

- `400`: Bad request
- `409`: Idempotency-Key conflict — reused for a different request (`idempotency_key_reuse`), or the original request is still running (`idempotency_request_in_progress`)
- `429`: Rate limited — retry after the `Retry-After` delay

---

[API](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api.md) - [All operations](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api/llms.txt) - [OpenAPI document](https://skmtc.dev/magnetictax/apis/magnetic-integrations-api/revisions/11854873aa89?raw)