Skip to main content
POST
/
api
/
v1
/
customers
/
kyc
/
id-card
Submit ID Card Document
curl --request POST \
  --url https://waas-staging.embedly.ng/api/v1/api/v1/customers/kyc/id-card \
  --header 'x-api-key: <api-key>'

​
Endpoint

POST /api/v1/customers/kyc/id-card

​
Headers

HeaderValue
Content-Typeapplication/json
x-api-key<tenant API key>

​
Request body

FieldTypeRequiredDescription
customerIdstring (GUID)yesThe customer the document belongs to. Must be on Tier 2 (NIN + BVN verified + liveness completed).
documentTypestring enumyesAllowed: NIN_CARD, DRIVERS_LICENCE, PASSPORT, VOTERS_CARD. Case-insensitive on input; normalised on output.
documentUrlstring (HTTPS URL)yesMust use https://. Plain http:// is rejected. The URL is stored verbatim; the back office presigns / fetches it during review.
submissionChannelstring enumnoSource of the request. Allowed: WAAS (default), MERCHANT_SERVICE.
{
  "customerId":   "8d3e2c4a-19b7-4f2e-9c61-2a78b0f31c45",
  "documentType": "NIN_CARD",
  "documentUrl":  "https://your-cdn.example.com/uploads/nin-card-8d3e.jpg",
  "submissionChannel": "WAAS"
}

​
Success response

{
  "code": "00",
  "success": true,
  "message": "ID card submitted successfully and is pending review",
  "data": {
    "customerId":    "8d3e2c4a-19b7-4f2e-9c61-2a78b0f31c45",
    "submissionId":  "DOC-SUB-00001",
    "documentType":  "NIN_CARD",
    "documentUrl":   "https://your-cdn.example.com/uploads/nin-card-8d3e.jpg",
    "status":        "pending_review",
    "submittedAt":   "2026-06-25T10:14:33.521Z",
    "attemptNumber": 1,
    "channel":       "WAAS"
  }
}

​
Error responses

StatusTriggerSample body
400Invalid GUID{"code":"400","success":false,"message":"customerId must be a valid GUID","data":null}
400Unknown documentType{"code":"400","success":false,"message":"documentType 'X' is not accepted. Allowed values: NIN_CARD, DRIVERS_LICENCE, PASSPORT, VOTERS_CARD","data":null}
400documentUrl not HTTPS{"code":"400","success":false,"message":"documentUrl must use HTTPS","data":null}
404Customer not found{"code":"404","success":false,"message":"The customer could not be found","data":null}
422NIN/BVN not verified{"code":"422","success":false,"message":"NIN and BVN verification must be completed before an ID card can be submitted","data":null}
422Tier below 2{"code":"422","success":false,"message":"Customer must be on Tier 2 before submitting an ID card","data":null}
409Submission pending{"code":"409","success":false,"message":"A document submission is already under review. Re-upload is only permitted after current review completes.","data":null}
409Already approved{"code":"409","success":false,"message":"This customer's ID card has already been approved. No further submission is required.","data":null}
500Unexpected{"code":"500","success":false,"message":"An unexpected error occurred while submitting the ID card","data":null}