# 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"}}}}}}}} ```