# Set up the SFTP account

Page: https://sandbox.myclaimhouse.com/docs/api/setUpSftpAccount

`POST /api/v1/sftp-account`

Makes the organization's SFTP account: a user name chosen from the organization's name and a generated password. An organization has one account, for test and live files; setting up again is refused with CONFLICT: rotate the password instead. If a request is lost after the account was made, rotate the password to get one. Send an empty JSON object as the body. The response carries the password (password). It is shown only in this response and cannot be read again: store it now. A request repeated with the same Idempotency-Key gets the stored reply without the password (password_available is false): rotate the password to get a new one. Needs an Idempotency-Key header and a key with the submit permission.

Needs a key with `submit` permission.

## Request

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | Yes | Makes the request safe to repeat: a request with the same key and body returns the first answer (the reply has an idempotent-replayed header), and the same key with a different request is refused. 1 to 255 printable characters; a UUID is a good choice. At least 1 character. At most 255 characters. Matches `^[\x21-\x7e]{1,255}$`. |

## Response

The account, with its password. Status `201`.

| Name | Type | Description |
| --- | --- | --- |
| `id` | string | An ID that starts with sftp_. |
| `object` | string | Always `sftp_account`. |
| `status` | string | A disabled account is refused at login; its files stay where they are. One of: `active`, `disabled`. |
| `username` | string | The user name to log in with. |
| `host` | value | The host to connect to; null in an environment that has no SFTP host. |
| `port` | integer or null | The port to connect to; null in an environment that has no SFTP host. At least -9007199254740991. |
| `host_key_fingerprint` | value | The SHA256 fingerprint of the server's host key: check it the first time you connect. Null in an environment that has no SFTP host. |
| `folders` | object | The folders of the account. A file dropped in a folder under TEST is a test file; the folder is the mode. |
| `folders.test` | object |  |
| `folders.test.in` | string | Always `TEST/IN`. |
| `folders.test.out` | string | Always `TEST/OUT`. |
| `folders.live` | object |  |
| `folders.live.in` | string | Always `IN`. |
| `folders.live.out` | string | Always `OUT`. |
| `keys` | array of object | The public keys that may log in, at most 5. At most 5 items. |
| `keys[].id` | string | An ID that starts with sfk_. |
| `keys[].object` | string | Always `sftp_key`. |
| `keys[].label` | string | The name you gave the key. At most 64 characters. |
| `keys[].fingerprint` | string | The key's SHA256 fingerprint, as ssh-keygen -l shows it. |
| `keys[].added_at` | string (date-time) |  |
| `last_login_at` | string (date-time) or null |  |
| `last_file_at` | string (date-time) or null | When the last file dropped on the account was taken. |
| `created_at` | string (date-time) |  |
| `password` | string | The password to log in with. Shown only in the response that made it: store it now. Absent when password_available is false. |
| `password_available` | boolean | False in the stored reply an Idempotency-Key replay returns: the password is never stored for replay. Rotate the password to get a new one. |

## Errors

| HTTP status | Code | What it means |
| --- | --- | --- |
| 401 | `UNAUTHORIZED` | A valid API key is required. Send it as "Authorization: Bearer <key>". |
| 403 | `PERMISSION_DENIED` | This API key is not allowed to do that. |
| 422 | `INVALID_REQUEST` | The request is not valid. |
| 400 | `IDEMPOTENCY_KEY_REQUIRED` | POST and PATCH requests need an Idempotency-Key header. |
| 422 | `IDEMPOTENCY_KEY_REUSED` | That Idempotency-Key was already used with a different request. |
| 409 | `IDEMPOTENCY_KEY_IN_USE` | A request with that Idempotency-Key is still running. Retry shortly. |
| 413 | `PAYLOAD_TOO_LARGE` | The request body is larger than 1 MB. |
| 504 | `TIMEOUT` | The request took too long to finish. It may still have taken effect: look it up before sending it again with a new Idempotency-Key. What it made is found with GET /api/v1/eligibility?request_id=<this request_id>, and the same filter on /api/v1/claims and /api/v1/attachments (a key with read permission). |
| 409 | `CONFLICT` | The resource is not in a state that allows this, or it changed while the request was handled. Read it, then decide whether to send the request again. |
| 500 | `INTERNAL` | Something went wrong on our side. Quote the request ID if you contact us. |

## Example

### Example request

```bash
curl -X POST "https://sandbox.myclaimhouse.com/api/v1/sftp-account" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Example response: 201

```json
{
  "id": "sftp_01JM000000E00800000000008G",
  "object": "sftp_account",
  "status": "active",
  "username": "example-dental-group",
  "host": "sftp.example.com",
  "port": 22,
  "host_key_fingerprint": "SHA256:3rJq0nX1m2Yw8dVf5uQ7bT9kLz4cE6hA1sPoGvNxYdI",
  "folders": {
    "test": {
      "in": "TEST/IN",
      "out": "TEST/OUT"
    },
    "live": {
      "in": "IN",
      "out": "OUT"
    }
  },
  "keys": [],
  "last_login_at": null,
  "last_file_at": null,
  "created_at": "2026-09-24T15:00:00+00:00",
  "password": "k3Vq9xT1mZ8wRb4nJc7YdLfH2sGpA6uE",
  "password_available": true
}
```