# Create a document for a member

`POST /api/members/{memberId}/documents`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`), Consumer (`CONSUMER`) (any one of these products, not all)
- **Features:** Online Bookings (`ONLINEBOOK`), Online Joining (`ONLINEJOIN`), Front of House Generic Access (`FOHGENERIC`) (any one of these features, not all)

HTML version: [Create a document for a member](https://support.gladstonesoftware.cloud/reference/members/create-a-document-for-a-member)

## Overview

Uploads a file you already hold — a signed form, a photo of an ID card, a scanned letter — and
files it against a member's record. The request is `multipart/form-data` and must carry exactly
two parts: `file`, the bytes of the document, and `json`, a JSON object describing it. On success
you get `200 OK` and the body is a single JSON string containing a read-only link to the stored
file.

Reach for this endpoint when the finished file already exists on your side. If instead you want
Gladstone to build the file for you by stamping values into a stored PDF template, use
[Create a templated document for a member](create-a-templated-document-for-a-member.md),
which takes no file at all.

The `json` part must be a JSON object with these fields — anything that fails to parse
as JSON is rejected with `400` carrying the parser's own message:

- `name` (string, required, max 255 characters) — the document's title. It is what
  [Retrieves all documents associated with a member](retrieves-all-documents-associated-with-a-member.md)
  returns as the document `name`; the uploaded file's own filename is kept separately.
- `documentTypeId` (integer, required) — the category the document is filed under, taken from
  [Returns all document types](../configuration/returns-all-document-types.md). It must
  already exist, and must not be negative.
- `fileType` (required) — `PDF`, `JPG`, `JPEG` or `PNG`, sent as the name (matched
  case-insensitively) or as its numeric value. Anything unrecognised is treated as absent
  and rejected with `The type of the file must be provided and be valid`.
- `isSensitive` (boolean) — marks the document as sensitive. Defaults to `false` when omitted, but
  it is a floor rather than a switch: if the document type itself is configured as sensitive, the
  stored document is forced to sensitive regardless of what you send.
- `expiryDate` (date-time, optional) — the date the document stops being valid, returned as the
  document's valid-to date. A date earlier than today is rejected with `Date must not be in the
  past`. Omit it for a document that never expires.

Two things routinely surprise integrators. First, the declared `fileType` is checked against the
file's actual binary signature, not its extension, so a `.pdf` that is really a JPEG fails.
Second, documents created here are **not visible to the member**: this request has no field
to change that, and when a member's own token lists their documents, only member-visible ones
are returned, so the member will not see what you uploaded.

The URL you get back is a short-lived signed link — valid for 20 minutes, plus 20 minutes' allowance
for clock skew — so treat it as single-use and do not store it.
To get a fresh link later, call
[Retrieve a document associated with a member](retrieve-a-document-associated-with-a-member.md).

Access is checked first: when your token carries a member id it must equal
`{memberId}` or the request is rejected with `403` and `The given member ID of {memberId} does not
belong to the logged in member`. This route does **not** accept linked members, so a parent's token
cannot upload against a child's record here. Tokens with no member id in them (staff and
integration tokens) are not subject to that check.

Be aware that a Cloudflare managed challenge sits in front of this route in some environments and
can return `403` to non-browser clients posting multipart form data before the request ever reaches
the API. If you see an unexplained `403` with an HTML body, that is the likely cause.

## Endpoint

`POST {base_url}/api/members/{memberId}/documents`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `memberId` | integer (int32) | Yes | The member the document is filed against. The member must exist, or the call fails with `404` and `The member with the ID {memberId} doesn't exist`. It is also the id you pass to [Retrieves all documents associated with a member](retrieves-all-documents-associated-with-a-member.md) to read the document back. When your token carries a member id, this value must equal it — linked members are not accepted on this route. |

## Sample request

```bash title="cURL"
curl -X POST '{base_url}/api/members/{memberId}/documents' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Sample response

```json title="200 OK"
"string"
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | The form data did not carry exactly one file — `A document must be provided when uploading`; the `json` part was missing or empty — `A json request must be provided when uploading`; the `json` part did not parse, in which case the parser's message is returned verbatim; the first failing field validation, such as `The type of the file must be provided and be valid`, `Document type ID must be a non-negative number` or `Date must not be in the past`; the file exceeded 10MB — `The file size is larger than 10MB and can not be uploaded. Current file size: {size}MB`; or the file's real format did not match the declared `fileType` — `The file was not valid for the given type of {fileType} - the actual type was {actualType} (blank if type was unrecognizable)`. |
| `404` | Not found | No member has the id in the path — `The member with the ID {memberId} doesn't exist` — or the `documentTypeId` in the JSON part matches no configured document type — `The document type with the ID {documentTypeId} doesn't exist`. |
| `500` | Internal server error | Storing the file failed, or another unexpected server-side failure occurred. The document record is created before the file is stored, so a failure at that point can leave a document record with no file behind it — check with [Retrieves all documents associated with a member](retrieves-all-documents-associated-with-a-member.md) before retrying. |