# sender/id-upload

## Purpose
Upload sender identification document images (front and optionally back) for KYC processing.
## When to Use
Use this endpoint when you need to:
- Upload the sender's ID document image after creating a transaction
- Submit both front and back images of the identification document
- Fulfill KYC requirements for sender verification

## Authentication
Requires `x-client-id` and `x-secret-key` headers for partner authentication.
## How It Works
1. The `uuid` field identifies the sender (idSenderGlobal) — the same UUID returned when creating the sender
2. The sender is validated against the Customer DynamoDB table
3. `documentType` + `documentCountry` are validated against the KYC identifications catalog to confirm the document is accepted and to determine whether the back image is required
4. Images are forwarded to the Viacheck processing Lambda for storage and verification
5. On success, returns a confirmation message

## Notes
- `documentType` must be a code accepted for `documentCountry` (e.g., DL, PA, CL)
- `documentCountry` is the document's issuing country in ISO 3166-1 alpha-3 format (e.g., USA, MEX)
- `frontImage` is always required; `backImage` is required only when the document type/country requires the back side (per the identifications catalog)
- Images can be sent as raw base64 or data URI format (data:image/png;base64,...)

## Common Errors
- **400000** - Invalid JSON format or image upload failed
- **400001** - Missing required field (uuid, documentType, documentCountry, documentNumber, frontImage, or backImage when required)
- **400010** - documentType is not accepted for the given documentCountry
- **401000** - Invalid credentials
- **403001** - Partner not authorized for this endpoint
- **404002** - Sender not found for the given UUID
- **500000** - Internal server error

Endpoint: POST /sender/id-upload
Version: 1.0.0

## Header parameters:

  - `x-client-id` (string, required)
    Unique identifier assigned to the integrating client.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

  - `x-secret-key` (string, required)
    Secret authentication key associated with the client.

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

## Request fields (application/json):

  - `uuid` (string, required)
    Sender's unique identifier (idSenderGlobal). This is the same UUID returned when the sender was created via transaction/create. The sender is validated against the Customer table before processing.
Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

  - `documentType` (string, required)
    Identification document type code (e.g., DL, PA, CL). Must be a document type accepted for the given documentCountry according to the KYC identifications catalog. Determines whether the back image is required.
Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, pattern=400009

  - `documentCountry` (string, required)
    Document country in ISO 3166-1 alpha-3 format (e.g., USA, MEX, COL). Used together with documentType to validate the document and resolve image requirements.
Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, pattern=400009

  - `documentNumber` (string, required)
    Sender's identification document number (e.g., driver's license, passport, national ID). Must match the documentNumber used in transaction/create.
Error codes: required=400001, type=400002, minLength=400003, maxLength=400004, pattern=400009

  - `frontImage` (string, required)
    Front image of the identification document encoded in base64. Accepts raw base64 or data URI (data:image/png;base64,...).
Error codes: required=400001, type=400002, minLength=400003, pattern=400009

  - `backImage` (string)
    Back image of the identification document encoded in base64. Optional — required only for document types that need back side capture (e.g., driver's license). Accepts raw base64 or data URI (data:image/png;base64,...).
Error codes: type=400002, minLength=400003, pattern=400009

## Response 200 fields (application/json):

  - `status` (string)
    Request status (success)

  - `message` (string)
    Descriptive message about the operation result

## Response 400 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 400 (click to expand)CodeDescription400000Invalid JSON format or image upload failed.400001Required field is missing (uuid, documentType, documentCountry, documentNumber, frontImage, or backImage when required by the document type/country).400010documentType is not accepted for the given documentCountry.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)

## Response 401 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 401 (click to expand)CodeDescription401000Invalid credentials.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

## Response 403 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 403 (click to expand)CodeDescription403001Access to this resource is forbidden for this client.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)

## Response 404 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 404 (click to expand)CodeDescription404002Sender not found for the given UUID.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)

## Response 422 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 422 (click to expand)CodeDescription422007Sender does not have required associated data.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

## Response 500 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 500 (click to expand)CodeDescription500000Internal server error.500001Error retrieving sender data from DynamoDB.500002Error invoking document processing Lambda.500003Error retrieving the KYC identifications catalog.

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)