# Registry documents

> Upload and track the documents some extensions, Turkish third-level domains in particular, require before approving a registration or ownership change.

Some extensions — Turkish third-level domains in particular — require supporting documents before the registry approves a registration or an ownership change. These endpoints submit and track them.

:::caution[You can only upload while the domain is expecting documents]
Call `GET /api/v1/domains/info` and check `status` and `statusReason` first:

| status | statusReason | Upload accepted? |
| --- | --- | --- |
| WaitingForDocument | DocumentPendingForRegistration | Yes — for the registration |
| WaitingForDocument | anything else | Yes — for an ownership change |
| WaitingForRegistration | DocumentPendingForRegistration, DocumentUnderReview or DocumentInvalid | Yes — for the registration |
| ModificationPending | — | Yes — for an ownership change |
| anything else | — | **No** — `Dna.DomainService:Domain:10055` |
:::

## POST /api/v1/domains/documents

Uploads one or more documents as Base64 and forwards each to the registry.

**Request**

| Field | Required | Notes |
| --- | --- | --- |
| `domainName` | required |   |
| `documents` | required | Array, at least one entry. |
| `documents[].documentType` | required | Number or name from the table below. |
| `documents[].fileName` | required | **Must include the extension.** The extension is how we determine the expected content type. |
| `documents[].fileContent` | required | Raw Base64. **No `data:` prefix.** |

```json
{
  "domainName": "apiname.com.tr",
  "documents": [
    {
      "documentType": 1,
      "fileName": "identity-card.jpg",
      "fileContent": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    {
      "documentType": 3,
      "fileName": "tax-certificate.pdf",
      "fileContent": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8..."
    }
  ]
}
```

**Limits**

| Limit | Value |
| --- | --- |
| Allowed formats | PDF, DOC, DOCX, ODT, JPG, JPEG, PNG |
| Maximum per file | **10 MB** |
| Maximum per request, all files | **50 MB** |
| Maximum documents under review per domain | **10** (pending plus new, combined) |

:::caution[The file extension must match the actual file]
We decode each file and inspect its real format, then require that it matches the extension you gave. Renaming a `.docx` to `.pdf` is rejected with `Dna.DomainService:Domain:10068`, and `details` tells you what the file really is. This catches the common case of a customer uploading a Word file named `.pdf`.
:::

**Response — 200**

```json
{
  "uploaded": [
    {
      "name": "identity-card.jpg",
      "size": 284119,
      "mimeType": "image/jpeg",
      "type": 1,
      "uploadedDate": "2026-10-30T15:41:09"
    }
  ],
  "duplicates": [],
  "failed": ["tax-certificate.pdf"],
  "totalDocumentCount": 1,
  "totalDocumentSize": 1093847
}
```

:::danger[This endpoint is partially successful by design]
Documents are processed one at a time. One failure does not abort the rest, and **HTTP 200 does not mean everything was accepted**. You must read all three arrays:

| Array | Meaning |
| --- | --- |
| `uploaded` | Stored **and** accepted by the registry. These are done. |
| `duplicates` | Skipped — a document with the same file name is already under review, or the name repeated within your request. Rename and resend if it was a different file. |
| `failed` | Skipped — storage failed, or **the registry rejected this particular file**. Retry these. |

A 200 with `uploaded: []` and entries in `failed` means nothing was accepted. Note that `totalDocumentSize` counts *everything you submitted*, including failures, while `totalDocumentCount` counts only successes.
:::

:::tip[What happens next]
Once at least one document is accepted, the domain moves to `statusReason: DocumentUnderReview`. The registry reviews it — this takes hours to days depending on the extension. Poll `GET /api/v1/domains/documents` to watch each document's status, and `GET /api/v1/domains/info` for the domain's overall state.

If a document is rejected (`status: Rejected`), upload a corrected one. The domain stays in the waiting state until the registry is satisfied.
:::

**Document types**

| Value | Name | Document |
| --- | --- | --- |
| 1 | `IdentityCard` | National identity card, both sides in one file |
| 2 | `Passport` | Passport, for foreign nationals |
| 3 | `TaxCertificate` | Tax registration certificate, for companies |
| 4 | `ActivityCertificate` | Certificate of activity or chamber registration |
| 5 | `SignatureCircular` | Signature circular |
| 6 | `AuthorizationLetter` | Letter of authority or proxy to act |
| 7 | `Petition` | Petition, e.g. a deletion request |
| 8 | `TradeRegistryGazette` | Trade registry gazette |
| 9 | `TrademarkCertificate` | Trademark registration certificate |
| 10 | `EducationCertificate` | Educational institution certificate |
| 11 | `OrganizationStatute` | Association or foundation statute |
| 12 | `GovernmentApproval` | Official body approval or ministry permit |
| 13 | `DomainOwnershipProof` | Proof of ownership: prior WHOIS, invoice, declaration |
| 14 | `PowerOfAttorney` | Power of attorney from a lawyer or representative |
| 15 | `BarAssociationCertificate` | Bar registration or licence |
| 16 | `MedicalDiplomaOrLicense` | Medical diploma or specialisation certificate |
| 17 | `MunicipalOfficialLetter` | Official signed request from the competent authority |
| 18 | `EducationInstitutionLicense` | Establishment or operating licence for a school |
| 19 | `ChamberOfCommerceCertificate` | Chamber of commerce registration letter |
| 20 | `TrademarkTransferAgreement` | Trademark transfer agreement |
| 21 | `KepAuthorization` | Registered-e-mail authority document |
| 99 | `Other` | Anything else, or a special case |

**Errors**

| Code | Meaning and fix |
| --- | --- |
| `Dna.DomainService:Domain:10055` | The domain is not expecting documents. Check `status` and `statusReason`. |
| `Dna.DomainService:Domain:10061` | `documents` empty or missing. |
| `Dna.DomainService:Domain:10066` | An entry lacks `fileName` or `fileContent`. |
| `Dna.DomainService:Domain:10065` | `documentType` is not a valid value. |
| `Dna.DomainService:Domain:10062` | Format not allowed, or the content is unrecognisable. |
| `Dna.DomainService:Domain:10067` | Not valid Base64. The usual cause is leaving the `data:image/jpeg;base64,` prefix in. |
| `Dna.DomainService:Domain:10068` | Extension does not match the file content. |
| `Dna.DomainService:Domain:10069` | A single file exceeds 10 MB. |
| `Dna.DomainService:Domain:10064` | The request total exceeds 50 MB. Split it. |
| `Dna.DomainService:Domain:10063` | More than 10 documents would be under review. `details` gives the pending and new counts. |
| `Dna.DomainService:Epp:10001` | Every document was refused by the registry. Read `details`. |

## GET /api/v1/domains/documents

Lists the documents uploaded for a domain and their review status. Metadata only — file contents are not returned.

**Request — query string**

| Parameter | Default | Notes |
| --- | --- | --- |
| `domainName` | — | **Required.** |
| `documentTypes` | — | Comma-separated filter of names or numbers: `IdentityCard,TaxCertificate` or `1,3`. |
| `skipCount` | 0 |   |
| `maxResultCount` | 10 |   |

```http
GET /api/v1/domains/documents?domainName=apiname.com.tr
```

**Response — 200**

```json
{
  "totalCount": 2,
  "items": [
    {
      "name": "identity-card.jpg",
      "type": 1,
      "status": 3,
      "operationType": 1,
      "uploadedDate": "2026-10-30T15:41:09"
    },
    {
      "name": "tax-certificate.pdf",
      "type": 3,
      "status": 2,
      "operationType": 1,
      "uploadedDate": "2026-10-30T15:52:33"
    }
  ]
}
```

**Document status**

| Value | Name | What it means for you |
| --- | --- | --- |
| 1 | `Waiting` | A document is expected but none has been sent. Upload one. |
| 2 | `Pending` | Sent, awaiting registry review. Wait. |
| 3 | `Approved` | Accepted. Nothing more to do for this document. |
| 4 | `Rejected` | **Upload a corrected document.** The domain stays blocked until the registry is satisfied. |
| 5 | `Expired` | The document's validity window passed. Upload a current one. |
| 6 | `Cancelled` | The surrounding application or ownership change was cancelled. |

`operationType`: `1` registration · `2` ownership change · `3` deletion.

**Errors**

| Code | Meaning and fix |
| --- | --- |
| `Dna.DomainService:Domain:10007` | Domain not found or not yours. |
| `Dna.DomainService:Domain:10065` | An entry in `documentTypes` is not a recognised type. |