Skip to content
MidwaterDocs

Confirm or correct a check result

POST
/v1/conversations/{id}/feedback
curl --request POST \
  --url https://example.com/MIDWATER_BASE_URL/v1/conversations/example/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "check_key": "need_unresolved", "verdict": "fail", "note": "Caller hung up before the booking went through." }'

Records your team’s answer for one check on one conversation (stored as a label with source api). id is Midwater’s ID or your external_id. Today each call adds a label; idempotency keys on this endpoint are planned.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Midwater’s conversation ID or your external_id.

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
<= 255 characters

Planned for every POST. Accepted today but not yet honoured on this endpoint, so don’t retry it blindly.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
check_key
required
string
>= 1 characters
verdict
required

Your team’s answer: pass (no problem) or fail (the problem happened).

string
Allowed values: pass fail
note
string
<= 1000 characters

Example 

{
  "check_key": "need_unresolved",
  "verdict": "fail",
  "note": "Caller hung up before the booking went through."
}

Responses

Section titled “Responses”

200

Section titled “200”

The label was stored.

Media typeapplication/json
object
id
required
string
check_key
required
string
verdict
required
string
Allowed values: pass fail
source
required
string
Allowed value: api

Example 

{
  "id": "cmv0189as006no301jmgcwibw",
  "check_key": "need_unresolved",
  "verdict": "fail",
  "source": "api"
}

Headers

Section titled “Headers”
Midwater-Request-Id
string
Example 
req_8Jx2kQ4mT9

The request’s ID, also in error bodies as error.request_id. Quote it when contacting support.

400

Section titled “400”

The body isn’t valid JSON.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "invalid_json",
    "message": "Body must be valid JSON"
  }
}

401

Section titled “401”

Missing, malformed, unknown or revoked API key.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "authentication_error",
    "message": "Missing or invalid API key. Use Authorization: Bearer mw_test_… or mw_live_…"
  }
}

403

Section titled “403”

The key is valid but not allowed to do this.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "permission_denied",
    "message": "This key can't do that",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

404

Section titled “404”

No such conversation, or the conversation has no result for check_key ("No result for check <key>").

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "not_found",
    "message": "No result for check no_such_check"
  }
}

405

Section titled “405”

The path exists but doesn’t support this method. Allow lists the methods it does support.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "method_not_allowed",
    "message": "GET isn't supported here; use POST",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

Headers

Section titled “Headers”
Allow
string
Example 
POST

The methods the path supports, e.g. POST.

409

Section titled “409”

The Idempotency-Key was already used with a different body.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "idempotency_conflict",
    "message": "This Idempotency-Key was used with a different body",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

422

Section titled “422”

The body is JSON but doesn’t match the schema. fields maps each dotted path to its messages.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "validation_error",
    "message": "The conversation payload is invalid",
    "fields": {
      "channel": [
        "Invalid enum value. Expected 'voice' | 'chat', received 'fax'"
      ],
      "transcript": [
        "transcript needs at least one turn"
      ]
    }
  }
}

429

Section titled “429”

Too many requests. Wait Retry-After seconds. The limits are published when they’re set.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "rate_limited",
    "message": "Too many requests",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

RateLimit-Limit
integer

Requests allowed in the current window. The numbers are published when the limits are set.

RateLimit-Remaining
integer

Requests left in the current window.

RateLimit-Reset
integer

Seconds until the window resets.

500

Section titled “500”

Something went wrong on Midwater’s side. Safe to retry with the same Idempotency-Key.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "server_error",
    "message": "Something went wrong on our side"
  }
}

503

Section titled “503”

Midwater is briefly unavailable. Retry with backoff, honouring Retry-After when present.

Media typeapplication/json
object
error
required
object
type
required

Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401, permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413, validation_error 422, rate_limited 429, server_error 500, service_unavailable 503. Types not yet returned are planned. Treat a type you don’t know by its status class.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "service_unavailable",
    "message": "Midwater is briefly unavailable",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.