{"openapi":"3.1.0","info":{"title":"sendwich Merchant API","version":"v1","description":"User-sent SMS phone possession verification. Server-side API keys only. Customer API extracted from backend models; see https://sendwich.kr/docs/ for webhooks and examples."},"servers":[{"url":"https://api.sendwich.kr"}],"paths":{"/v1/verifications":{"post":{"tags":["Merchant"],"summary":"Merchant Create","operationId":"merchant_create_v1_verifications_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","title":"Idempotency-Key","pattern":"^[A-Za-z0-9_.:-]{8,128}$","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationCreate"}}}},"responses":{"200":{"description":"Retained idempotent replay: original creation snapshot, not current status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedVerification"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}},"Idempotent-Replayed":{"schema":{"type":"string","enum":["true","false"]}}}},"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedVerification"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}},"Idempotent-Replayed":{"schema":{"type":"string","enum":["true","false"]}}}},"400":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"401":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"403":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"404":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"409":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"422":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"429":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"503":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}}},"description":"Create a phone possession verification. Both plans support API-only use; parent_origin and return_url are optional. Project settings control code format and expiry."}},"/v1/verifications/{verification_id}":{"get":{"tags":["Merchant"],"summary":"Merchant Get","operationId":"merchant_get_v1_verifications__verification_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResult"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"400":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"401":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"403":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"404":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"409":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"422":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"429":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"503":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}}}}},"/v1/verifications/{verification_id}/cancel":{"post":{"tags":["Merchant"],"summary":"Merchant Cancel","operationId":"merchant_cancel_v1_verifications__verification_id__cancel_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","title":"Verification Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResult"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"400":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"401":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"403":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"404":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"409":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"422":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"429":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}},"503":{"description":"API error. Read error.code; 422 may include fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"X-Request-ID":{"schema":{"type":"string"}},"X-Usage-Calls":{"description":"Present when usage was recorded.","schema":{"type":"string"}},"X-Usage-Limit":{"description":"Configured limit or unlimited, when usage was recorded.","schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}},"CreatedVerification":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","enum":["pending","verified","expired","cancelled"],"title":"Status"},"environment":{"type":"string","enum":["test","live"],"title":"Environment"},"mode":{"type":"string","enum":["discover","match"],"title":"Mode"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"carrier":{"anyOf":[{"type":"string","enum":["SKT","KT","LGU+"]},{"type":"null"}],"title":"Carrier","description":"Network reported by the matching SMS; null when unavailable or unrecognized."},"client_reference":{"type":"string","title":"Client Reference"},"state":{"type":"string","title":"State"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"type":"string","title":"Expires At"},"verified_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verified At"},"server_time":{"type":"string","title":"Server Time"},"verification_url":{"type":"string","title":"Verification Url"},"destination":{"type":"string","title":"Destination"},"sms_text":{"type":"string","title":"Sms Text"}},"type":"object","required":["id","status","environment","mode","phone","client_reference","state","created_at","expires_at","verified_at","server_time","verification_url","destination","sms_text"],"title":"CreatedVerification"},"VerificationCreate":{"properties":{"mode":{"type":"string","enum":["discover","match"],"title":"Mode","default":"discover"},"expected_phone":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Expected Phone"},"client_reference":{"type":"string","maxLength":160,"title":"Client Reference","default":""},"state":{"type":"string","maxLength":256,"title":"State","default":""},"parent_origin":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Parent Origin"},"return_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Return Url"}},"additionalProperties":false,"type":"object","title":"VerificationCreate"},"VerificationResult":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","enum":["pending","verified","expired","cancelled"],"title":"Status"},"environment":{"type":"string","enum":["test","live"],"title":"Environment"},"mode":{"type":"string","enum":["discover","match"],"title":"Mode"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"carrier":{"anyOf":[{"type":"string","enum":["SKT","KT","LGU+"]},{"type":"null"}],"title":"Carrier","description":"Network reported by the matching SMS; null when unavailable or unrecognized."},"client_reference":{"type":"string","title":"Client Reference"},"state":{"type":"string","title":"State"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"type":"string","title":"Expires At"},"verified_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verified At"},"server_time":{"type":"string","title":"Server Time"}},"type":"object","required":["id","status","environment","mode","phone","client_reference","state","created_at","expires_at","verified_at","server_time"],"title":"VerificationResult"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}