# User Management
Endpoints to create and manage user accounts
## Verify API key authentication
> Verifies that the provided API key is valid and authentication is working correctly.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"ErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["error_key"],"properties":{"error_key":{"type":"string","description":"Standardized error key for client error handling"}}}}}}},"paths":{"/api/v1/partner/verify-auth":{"get":{"tags":["User Management"],"summary":"Verify API key authentication","description":"Verifies that the provided API key is valid and authentication is working correctly.\n","operationId":"verifyAuth","responses":{"200":{"description":"Authentication successful","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"authenticated":{"type":"boolean"}}}}}]}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Create or get partner user
> Creates a new user relation or returns existing if already created. Returns user\_ref (same as input) for subsequent API calls. Partners can only access their own users.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"CreateUserResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the user. Use this value in all subsequent API calls."},"email":{"type":"string","format":"email"},"kyc_status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","VERIFIED","VERIFICATION_REJECTED"]},"created_at":{"type":"string","format":"date-time"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}},"paths":{"/api/v1/partner/users":{"post":{"tags":["User Management"],"summary":"Create or get partner user","description":"Creates a new user relation or returns existing if already created. Returns user_ref (same as input) for subsequent API calls. Partners can only access their own users.","operationId":"createPartnerUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_ref","email"],"properties":{"user_ref":{"type":"string","description":"Partner's unique user ID (usually primary key or UUID)"},"email":{"type":"string","format":"email","description":"User's email address"}}}}}},"responses":{"200":{"description":"User already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserResponse"}}}},"201":{"description":"Successfully created user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized (missing or invalid X-API-Key)"},"500":{"description":"Internal Server Error"}}}}}}
```
## Partner user by ID
> Get user details including KYC status and payment profiles using the user\_uuid returned during user creation. Partners can only access their own users.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"GetUserResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the user. Use this value in all subsequent API calls."},"email":{"type":"string","format":"email"},"created_at":{"type":"string","format":"date-time"},"kyc":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","VERIFIED","VERIFICATION_REJECTED"]},"kyc_method":{"type":"string","enum":["direct_data","external_token","handoff"],"description":"KYC submission method used"},"first_name":{"type":"string","description":"User's first name from KYC data"},"last_name":{"type":"string","description":"User's last name from KYC data"},"country_code":{"type":"string","description":"User's country code (ISO 2-letter) from KYC data"},"rejection_reason":{"type":"string","nullable":true,"description":"Reason for KYC rejection (if status is VERIFICATION_REJECTED)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp for KYC status"}}},"payment_profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rail":{"type":"string"},"currency":{"type":"string"},"institution_name":{"type":"string","nullable":true},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","additionalProperties":true}}}}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}},"paths":{"/api/v1/partner/users/{user_uuid}":{"get":{"tags":["User Management"],"summary":"Partner user by ID","description":"Get user details including KYC status and payment profiles using the user_uuid returned during user creation. Partners can only access their own users.","operationId":"getPartnerUser","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"}}}}}}
```
## Submit KYC data for a partner user
> Submit KYC (Know Your Customer) data for a partner user. Supports three methods:\
> \- direct\_data: Partner submits PII data directly, user is verified\
> \- external\_token: Partner provides external KYC provider credentials (SumSub token or Persona inquiry\_id)\
> \- handoff: Unigox handles KYC verification and generates verification URL\
> \
> \*\*Important for EUR/AUD/GBP off-ramp:\*\* EUR, AUD, and GBP payouts require the user's\
> physical address. Include \`address\`, \`city\`, and \`postal\_code\` in the PII data\
> when submitting KYC. If not provided at submission time, you can add them later with\
> \`PATCH /partner/users/{user\_uuid}/kyc\`. Without address, EUR/AUD/GBP orders will be created\
> with status \`pending\_address\` until the address is provided.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"KYCSubmitDirectData":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["direct_data"]},"data":{"type":"object","required":["pii"],"properties":{"pii":{"type":"object","required":["first_name","last_name","country_code"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"country_code":{"type":"string"},"dob":{"type":"string","format":"date"},"middle_name":{"type":"string"},"phone_number":{"type":"string","description":"E.164 format"},"id_number":{"type":"string"},"id_type":{"type":"string","enum":["NATIONAL_ID","DRIVER_LICENSE","PASSPORT"]},"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City. Required for EUR/AUD/GBP offramp (auto-populates into payment details)."},"postal_code":{"type":"string"}}}}}}},"KYCSubmitExternalToken":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["external_token"]},"data":{"type":"object","required":["provider"],"description":"Provider-specific fields:\n- SumSub: requires `token` (SumSub share token)\n- Persona: requires `inquiry_id` (Persona inquiry ID, e.g. inq_xxx)\n","properties":{"provider":{"type":"string","enum":["sumsub","persona"],"description":"KYC provider name"},"token":{"type":"string","description":"SumSub share token (required when provider=sumsub)"},"inquiry_id":{"type":"string","description":"Persona inquiry ID (required when provider=persona). This is the inq_xxx identifier returned by Persona when the inquiry was created."}}}}},"KYCSubmitHandoff":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["handoff"]},"data":{"type":"object","properties":{"pii":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"country_code":{"type":"string"}}}}}}},"KYCSubmitResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"kyc_status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","VERIFIED","VERIFICATION_REJECTED"]},"message":{"type":"string"},"verification_url":{"type":"string","format":"uri","nullable":true,"description":"Verification URL (only returned for handoff method)"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/kyc-submissions":{"post":{"tags":["User Management"],"summary":"Submit KYC data for a partner user","description":"Submit KYC (Know Your Customer) data for a partner user. Supports three methods:\n- direct_data: Partner submits PII data directly, user is verified\n- external_token: Partner provides external KYC provider credentials (SumSub token or Persona inquiry_id)\n- handoff: Unigox handles KYC verification and generates verification URL\n\n**Important for EUR/AUD/GBP off-ramp:** EUR, AUD, and GBP payouts require the user's\nphysical address. Include `address`, `city`, and `postal_code` in the PII data\nwhen submitting KYC. If not provided at submission time, you can add them later with\n`PATCH /partner/users/{user_uuid}/kyc`. Without address, EUR/AUD/GBP orders will be created\nwith status `pending_address` until the address is provided.\n","operationId":"submitKYC","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/KYCSubmitDirectData"},{"$ref":"#/components/schemas/KYCSubmitExternalToken"},{"$ref":"#/components/schemas/KYCSubmitHandoff"}]}}}},"responses":{"200":{"description":"KYC submitted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KYCSubmitResponse"}}}},"400":{"description":"Bad Request - invalid method or missing required data"},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}}}
```
## Upload KYC document for a partner user
> Upload a KYC document for a partner user. Choose one of two upload methods:\
> \
> \---\
> \
> \### Method 1: File Upload\
> Send the document as a file attachment.\
> \`\`\`\
> POST /api/v1/partner/users/{user\_uuid}/kyc/documents\
> Content-Type: multipart/form-data\
> \
> document: \\
> document\_type: identity\_front\
> \`\`\`\
> \
> \### Method 2: Single URL Upload\
> Send a URL pointing to one document image.\
> \`\`\`json\
> {\
> "upload\_method": "url\_link",\
> "document\_type": "identity\_front",\
> "url": "
> }\
> \`\`\`\
> \
> \### Method 3: Batch URL Upload\
> Upload multiple documents in one call (up to 10).\
> \`\`\`json\
> {\
> "upload\_method": "url\_link",\
> "documents": \[\
> { "document\_type": "identity\_front", "url": "" },\
> { "document\_type": "selfie", "url": "" }\
> ]\
> }\
> \`\`\`\
> \
> \*\*URL requirements:\*\* HTTPS only, 10MB per file, JPEG/PNG/GIF/PDF.\
> \
> \---\
> \
> \*\*Supported document types:\*\* \`identity\_front\` (required), \`selfie\` (required), \`identity\_back\`, \`passport\`, \`national\_id\`, \`driver\_license\`, and more.\
> \
> \*\*Automatic Verification:\*\* After uploading all required documents (selfie + identity\_front), verification starts automatically.
````json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}}},"paths":{"/api/v1/partner/users/{user_uuid}/kyc/documents":{"post":{"tags":["User Management"],"summary":"Upload KYC document for a partner user","description":"Upload a KYC document for a partner user. Choose one of two upload methods:\n\n---\n\n### Method 1: File Upload\nSend the document as a file attachment.\n```\nPOST /api/v1/partner/users/{user_uuid}/kyc/documents\nContent-Type: multipart/form-data\n\ndocument: \ndocument_type: identity_front\n```\n\n### Method 2: Single URL Upload\nSend a URL pointing to one document image.\n```json\n{\n \"upload_method\": \"url_link\",\n \"document_type\": \"identity_front\",\n \"url\": \"https://example.com/id-front.jpg\"\n}\n```\n\n### Method 3: Batch URL Upload\nUpload multiple documents in one call (up to 10).\n```json\n{\n \"upload_method\": \"url_link\",\n \"documents\": [\n { \"document_type\": \"identity_front\", \"url\": \"https://example.com/id-front.jpg\" },\n { \"document_type\": \"selfie\", \"url\": \"https://example.com/selfie.jpg\" }\n ]\n}\n```\n\n**URL requirements:** HTTPS only, 10MB per file, JPEG/PNG/GIF/PDF.\n\n---\n\n**Supported document types:** `identity_front` (required), `selfie` (required), `identity_back`, `passport`, `national_id`, `driver_license`, and more.\n\n**Automatic Verification:** After uploading all required documents (selfie + identity_front), verification starts automatically.\n","operationId":"uploadPartnerKYCDocument","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"Public UUID of the user","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"File Upload (multipart)","description":"Upload document as a file attachment. Use Content-Type multipart/form-data.","type":"object","required":["document","document_type"],"properties":{"document":{"type":"string","format":"binary","description":"Document file (JPEG, PNG, GIF, or PDF, max 10MB)"},"document_type":{"type":"string","description":"Type of document being uploaded","enum":["identity_front","identity_back","selfie","passport","national_id","driver_license","voter_id","resident_card","id_card"]}}},{"title":"Single URL Upload","description":"Upload one document by providing an HTTPS URL.","type":"object","required":["upload_method","document_type","url"],"properties":{"upload_method":{"type":"string","enum":["url_link"]},"document_type":{"type":"string","enum":["identity_front","identity_back","selfie","passport","national_id","driver_license","voter_id","resident_card","id_card"]},"url":{"type":"string","format":"uri","description":"HTTPS URL of the image. 10MB max."}}},{"title":"Batch URL Upload","description":"Upload multiple documents in one call (up to 10).","type":"object","required":["upload_method","documents"],"properties":{"upload_method":{"type":"string","enum":["url_link"]},"documents":{"type":"array","maxItems":10,"items":{"type":"object","required":["document_type","url"],"properties":{"document_type":{"type":"string","enum":["identity_front","identity_back","selfie","passport","national_id","driver_license"]},"url":{"type":"string","format":"uri"}}}}}}],"discriminator":{"propertyName":"upload_method"}}}}},"responses":{"200":{"description":"Document uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"document_id":{"type":"string","description":"AiPrise document UUID"},"document_type":{"type":"string"},"file_name":{"type":"string"},"message":{"type":"string","description":"Success message. If all required documents are uploaded, message indicates\nthat verification started automatically.\n"},"verification_session_id":{"type":"string","description":"Verification session ID (only present if verification started automatically\nafter uploading the last required document: selfie + identity_front)\n"},"verification_status":{"type":"string","enum":["PENDING","IN_PROGRESS","COMPLETED","FAILED"],"description":"Verification status (only present if verification started automatically\nafter uploading the last required document: selfie + identity_front)\n"}}}}}}}},"400":{"description":"Bad Request - invalid file type, missing document, or user not ready for uploads"},"401":{"description":"Unauthorized"},"404":{"description":"User not found or no active KYC session"},"500":{"description":"Internal Server Error"}}}}}}
````
## Update KYC data for a partner user
> Update optional PII fields on existing KYC data. The user stays verified.\
> Only optional fields can be updated.\
> Required fields (first\_name, last\_name, country\_code) cannot be changed.\
> \
> For EUR/AUD/GBP offramp, provide address, city, and postal\_code here.\
> These will auto-populate into payment details for EUR/AUD/GBP payouts.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}}},"paths":{"/api/v1/partner/users/{user_uuid}/kyc":{"patch":{"tags":["User Management"],"summary":"Update KYC data for a partner user","description":"Update optional PII fields on existing KYC data. The user stays verified.\nOnly optional fields can be updated.\nRequired fields (first_name, last_name, country_code) cannot be changed.\n\nFor EUR/AUD/GBP offramp, provide address, city, and postal_code here.\nThese will auto-populate into payment details for EUR/AUD/GBP payouts.\n","operationId":"updateKYC","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City"},"postal_code":{"type":"string"},"dob":{"type":"string","format":"date"},"phone_number":{"type":"string","description":"E.164 format"},"middle_name":{"type":"string"},"id_number":{"type":"string"},"id_type":{"type":"string","enum":["NATIONAL_ID","DRIVER_LICENSE","PASSPORT"]}}}}}},"responses":{"200":{"description":"KYC data updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"updated_fields":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}}}},"400":{"description":"Bad request (no valid fields, or trying to change required fields)"},"401":{"description":"Unauthorized"},"404":{"description":"User not found"}}}}}}
```
## Verification status for a partner user
> Get the current verification status for a partner user. This endpoint checks the verification status\
> with the KYC provider (e.g., AiPrise) and returns the current status, verification URL (if available),\
> and other relevant information. Optionally, you can provide a verification\_id to check a specific\
> verification session.\
> \
> Interpretation of terminal states:\
> \- \`VERIFIED\` — verification passed and the user is approved\
> \- \`VERIFICATION\_REJECTED\` — verification completed with a rejection outcome\
> \- \`FAILED\` — verification could not be completed due to an error\
> \- \`COMPLETED\` — provider workflow finished processing, but partners should still treat \`VERIFIED\`\
> as the success state and \`VERIFICATION\_REJECTED\` / \`FAILED\` as terminal non-success states
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"VerificationStatusResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_STARTED","PENDING","IN_PROGRESS","COMPLETED","VERIFIED","FAILED","VERIFICATION_REJECTED"],"description":"Current verification status.\n\nRecommended partner interpretation:\n- `NOT_STARTED`, `PENDING`, `IN_PROGRESS` — still processing\n- `VERIFIED` — approved / successful verification\n- `VERIFICATION_REJECTED` — completed with rejection\n- `FAILED` — terminal error\n- `COMPLETED` — provider workflow completed, but partners should not treat this alone as approval; wait for `VERIFIED` to consider the user approved\n"},"verification_url":{"type":"string","format":"uri","nullable":true,"description":"Verification URL (for handoff method)"},"verification_seconds_left":{"type":"integer","nullable":true,"description":"Seconds remaining for verification session (if applicable)"},"provider_messages":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Provider-specific messages or rejection reasons"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/verification-status":{"get":{"tags":["User Management"],"summary":"Verification status for a partner user","description":"Get the current verification status for a partner user. This endpoint checks the verification status\nwith the KYC provider (e.g., AiPrise) and returns the current status, verification URL (if available),\nand other relevant information. Optionally, you can provide a verification_id to check a specific\nverification session.\n\nInterpretation of terminal states:\n- `VERIFIED` — verification passed and the user is approved\n- `VERIFICATION_REJECTED` — verification completed with a rejection outcome\n- `FAILED` — verification could not be completed due to an error\n- `COMPLETED` — provider workflow finished processing, but partners should still treat `VERIFIED`\n as the success state and `VERIFICATION_REJECTED` / `FAILED` as terminal non-success states\n","operationId":"getVerificationStatus","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}},{"name":"verification_id","in":"query","required":false,"description":"Optional verification session ID. If not provided, the latest verification session for the user will be checked.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved verification status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationStatusResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}}}
```
## Payment details for a partner user
> Retrieve all payment details (payment profiles) for a partner user. Returns all saved beneficiary details that can be used for offramp operations. Partners can only access their own users.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"GetPaymentDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentProfile"},"description":"List of all payment profiles for the user"}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PaymentProfile":{"type":"object","properties":{"payment_details_id":{"type":"string","description":"Payment details ID. Use this value in offramp/onramp quote requests."},"rail":{"type":"string","description":"Payment rail identifier"},"currency":{"type":"string","description":"Fiat currency code"},"institution_name":{"type":"string","nullable":true,"description":"Institution (bank) name if applicable"},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","description":"Payment details (account number, VPA, IBAN, etc.)","additionalProperties":true}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/payment-details":{"get":{"tags":["User Management"],"summary":"Payment details for a partner user","description":"Retrieve all payment details (payment profiles) for a partner user. Returns all saved beneficiary details that can be used for offramp operations. Partners can only access their own users.","operationId":"getPaymentDetails","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully retrieved payment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPaymentDetailsResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}}}
```
## Create payment details for a partner user
> Create payment details (beneficiary details) for a partner user. Used for offramp operations where crypto is converted to fiat and sent to the user's payment account. Partners can only access their own users.\
> \
> Institution handling:\
> \- for most rails, \`institution\_id\` must be provided from \`/api/v1/supported/institutions\`\
> \- partners may omit \`institution\_id\` only for the explicitly supported rails below; the backend will assign the generic \`other-bank\` payment method automatically\
> \
> Currently supported omission rails:\
> \- \`iban-sepa\`\
> \- \`nip-nigeria\`
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"CreatePaymentDetailsRequest":{"description":"Conditional request schema for partner payment details. `institution_id` may be omitted only for `iban-sepa` and `nip-nigeria`.","oneOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestInstitutionOptional"},{"$ref":"#/components/schemas/CreatePaymentDetailsRequestInstitutionRequired"}]},"CreatePaymentDetailsRequestInstitutionOptional":{"allOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestBase"},{"type":"object","properties":{"rail":{"type":"string","enum":["iban-sepa","nip-nigeria"],"description":"Payment rail identifier for rails that support omission of `institution_id`"},"institution_id":{"type":"string","description":"Optional for `iban-sepa` and `nip-nigeria`.\nIf omitted, the backend assigns the generic `other-bank` payment method automatically.\n"}}}]},"CreatePaymentDetailsRequestBase":{"type":"object","required":["currency","rail","details"],"properties":{"currency":{"type":"string","description":"ISO 3-letter fiat currency code (e.g., INR, EUR, USD)"},"rail":{"type":"string","description":"Payment rail identifier (e.g., \"upi-india\", \"iban-sepa\", \"imps-india\")"},"details":{"type":"object","description":"Payment details object with fields specific to the payment network (e.g., account_number, vpa, iban, full_name)","additionalProperties":true},"country_code":{"type":"string","description":"Optional ISO 2-letter country code"}}},"CreatePaymentDetailsRequestInstitutionRequired":{"allOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestBase"},{"type":"object","required":["institution_id"],"properties":{"rail":{"type":"string","description":"Payment rail identifier for rails that require institution selection","not":{"enum":["iban-sepa","nip-nigeria"]}},"institution_id":{"type":"string","description":"Institution (payment method) identifier - our internal slug (e.g., \"wise\", \"hdfc-bank\", \"revolut\", \"uala\", \"banco-santander-argentina\").\nRequired for all rails except `iban-sepa` and `nip-nigeria`.\nIf omitted for any other rail, the API returns a validation error.\nFor rails with multiple formats (e.g., CVU/CBU), the format is automatically determined based on the payment method type of this institution.\n"}}}]},"CreatePaymentDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentProfile"}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PaymentProfile":{"type":"object","properties":{"payment_details_id":{"type":"string","description":"Payment details ID. Use this value in offramp/onramp quote requests."},"rail":{"type":"string","description":"Payment rail identifier"},"currency":{"type":"string","description":"Fiat currency code"},"institution_name":{"type":"string","nullable":true,"description":"Institution (bank) name if applicable"},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","description":"Payment details (account number, VPA, IBAN, etc.)","additionalProperties":true}}},"ErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["error_key"],"properties":{"error_key":{"type":"string","description":"Standardized error key for client error handling"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/payment-details":{"post":{"tags":["User Management"],"summary":"Create payment details for a partner user","description":"Create payment details (beneficiary details) for a partner user. Used for offramp operations where crypto is converted to fiat and sent to the user's payment account. Partners can only access their own users.\n\nInstitution handling:\n- for most rails, `institution_id` must be provided from `/api/v1/supported/institutions`\n- partners may omit `institution_id` only for the explicitly supported rails below; the backend will assign the generic `other-bank` payment method automatically\n\nCurrently supported omission rails:\n- `iban-sepa`\n- `nip-nigeria`\n","operationId":"createPaymentDetails","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentDetailsRequest"}}}},"responses":{"201":{"description":"Payment details created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentDetailsResponse"}}}},"400":{"description":"Bad Request - invalid payment details or unsupported combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}}}
```
## Delete payment details for a partner user
> Delete a specific payment details (payment profile) for a partner user by its ID. Partners can only access their own users.
```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Endpoints to create and manage user accounts"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}}},"paths":{"/api/v1/partner/users/{user_uuid}/payment-details/{payment_details_id}":{"delete":{"tags":["User Management"],"summary":"Delete payment details for a partner user","description":"Delete a specific payment details (payment profile) for a partner user by its ID. Partners can only access their own users.","operationId":"deletePaymentDetails","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}},{"name":"payment_details_id","in":"path","required":true,"description":"The payment_details_id returned when creating payment details.","schema":{"type":"string"}}],"responses":{"200":{"description":"Payment details deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found or payment details not found"},"409":{"description":"Conflict - payment details linked to active offers"},"500":{"description":"Internal Server Error"}}}}}}
```
---
# 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://developers.unigox.com/api-reference/user-management.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.