# Upload KYC documents
The following API allows a merchant to upload customer's documents for KYC within a host-to-host SEPA Secure flow. In order for a customer to pass a KYC, at least 3 documents must be provided by a merchant:
* **Photo:** SELFIE
* **Document ID (one of the following):** PASSPORT, ID\_CARD, DRIVERS, RESIDENCE\_PERMIT
* **Proof of address:** UTILITY\_BILL (can also be other documents than bill, see [list](https://riddec.atlassian.net/wiki/spaces/XGAT/pages/1619329028#1131f621-8810-4721-93c3-85aa806a9675))
Documents must follow the following rules:
* DRIVERS, ID\_CARD - it is required to upload **two sides**
* Use documentSubType parameter with FRONT\_SIDE / BACK\_SIDE values
* SELFIE, PASSPORT, UTILITY\_BILL - it is required to upload one side
* RESIDENCE\_PERMIT - can be one or two sides
{% hint style="warning" %}
The documents are not registered in SumSub after the upload is done. It is required to trigger the verification endpoint to start identity verification
{% endhint %}
### Document quality
Submitted documents should meet the following criteria:
* **Official and unexpired** (passports, national IDs, etc.) **and** **valid for at least 1 more month**
* **Fully visible** — no cut-off edges, glare, or blur
* **Not screenshots** — original files or clear photos only
* No edited, cropped, or screenshot versions
* **Correct file format**: JPG, PNG, or PDF, under 50MB
* **Proof of address** must be **issued within the last 3 months** and clearly show the client’s name and address.
### Acceptable Proof of Address Documents
* Recent utility bill (electricity, gas, internet)
* Bank or credit card statement
* Local or national tax letter (issued within the past 12 months)
* Mortgage or rental agreement
* Official correspondence from a government authority
* Voter registration certificate
### API specification
## Uploads a KYC document for a customer.
> Uploads a KYC (Know Your Customer) document for a specified customer.\
> \
> Access to this endpoint requires a valid API key. The API key is sent in the \`x-api-key\` header.\
> \
> Preconditions:\
> \- The customer must have a user profile (see POST /customer/{id}/bank-transfer/user).\
> \- The customer must have a KYC applicant (see POST /customer/{id}/bank-transfer/kyc/applicant).\
> \
> Supported Document Types:\
> One-sided documents (require \`documentType\`, \`content\`, \`country\`):\
> \- PASSPORT\
> \- RESIDENCE\_PERMIT.\
> \- UTILITY\_BILL\
> \- SELFIE.\
> \
> Two-sided documents (require \`documentType\`, \`documentSubType\`, \`content\`, \`country\`):\
> \- DRIVERS\
> \- ID\_CARD\
> \- RESIDENCE\_PERMIT.\
> \
> Parameters:\
> \- \`documentType\`: Type of document being uploaded.\
> \- \`documentSubType\`: "FRONT\_SIDE" or "BACK\_SIDE" for two-sided documents.\
> \- \`content\`: Base64-encoded document image. Must not exceed 500KB.\
> \- \`country\`: Two-letter ISO 3166-1 alpha-2 country code.
```json
{"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_null_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"type":"number","enum":[null],"nullable":true}},"required":["success","data"],"type":"object","additionalProperties":false},"AppValidationErrorResponse":{"description":"The AppValidationErrorResponse object contains general information about the validation error.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"UploadKycDocumentInput":{"anyOf":[{"properties":{"country":{"type":"string"},"content":{"type":"string"},"documentSubType":{"$ref":"#/components/schemas/UnblockKYCDocSubtype"},"documentType":{"anyOf":[{"$ref":"#/components/schemas/UnblockKYCDocType.Drivers"},{"$ref":"#/components/schemas/UnblockKYCDocType.IdCard"}]}},"required":["country","content","documentSubType","documentType"],"type":"object"},{"properties":{"country":{"type":"string"},"content":{"type":"string"},"documentType":{"anyOf":[{"$ref":"#/components/schemas/UnblockKYCDocType.Passport"},{"$ref":"#/components/schemas/UnblockKYCDocType.Selfie"},{"$ref":"#/components/schemas/UnblockKYCDocType.UtilityBill"}]}},"required":["country","content","documentType"],"type":"object"},{"properties":{"country":{"type":"string"},"content":{"type":"string"},"documentSubType":{"$ref":"#/components/schemas/UnblockKYCDocSubtype"},"documentType":{"$ref":"#/components/schemas/UnblockKYCDocType.ResidencePermit"}},"required":["country","content","documentType"],"type":"object"}]},"UnblockKYCDocSubtype":{"enum":["FRONT_SIDE","BACK_SIDE"],"type":"string"},"UnblockKYCDocType.Drivers":{"enum":["DRIVERS"],"type":"string"},"UnblockKYCDocType.IdCard":{"enum":["ID_CARD"],"type":"string"},"UnblockKYCDocType.Passport":{"enum":["PASSPORT"],"type":"string"},"UnblockKYCDocType.Selfie":{"enum":["SELFIE"],"type":"string"},"UnblockKYCDocType.UtilityBill":{"enum":["UTILITY_BILL"],"type":"string"},"UnblockKYCDocType.ResidencePermit":{"enum":["RESIDENCE_PERMIT"],"type":"string"}}},"paths":{"/customer/{id}/bank-transfer/kyc/document":{"put":{"operationId":"UploadKycDocument","responses":{"204":{"description":"No Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_null_"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppValidationErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}},"422":{"description":"Unprocessable content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppValidationErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}}},"description":"Uploads a KYC (Know Your Customer) document for a specified customer.\n\nAccess to this endpoint requires a valid API key. The API key is sent in the `x-api-key` header.\n\nPreconditions:\n- The customer must have a user profile (see POST /customer/{id}/bank-transfer/user).\n- The customer must have a KYC applicant (see POST /customer/{id}/bank-transfer/kyc/applicant).\n\nSupported Document Types:\nOne-sided documents (require `documentType`, `content`, `country`):\n- PASSPORT\n- RESIDENCE_PERMIT.\n- UTILITY_BILL\n- SELFIE.\n\nTwo-sided documents (require `documentType`, `documentSubType`, `content`, `country`):\n- DRIVERS\n- ID_CARD\n- RESIDENCE_PERMIT.\n\nParameters:\n- `documentType`: Type of document being uploaded.\n- `documentSubType`: \"FRONT_SIDE\" or \"BACK_SIDE\" for two-sided documents.\n- `content`: Base64-encoded document image. Must not exceed 500KB.\n- `country`: Two-letter ISO 3166-1 alpha-2 country code.","summary":"Uploads a KYC document for a customer.","tags":["Customer"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadKycDocumentInput"}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.xgateway.tech/miscellaneous/sepa-secure-service-api/upload-kyc-documents.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.