Mapping

    Create, manage, and run IVR mapping jobs. Map phone system menus by calling numbers, navigating DTMF and voice paths, and building a complete IVR tree.

    16 endpoints

    GET/mapping

    List mapping jobs in the workspace. Filter by phone number, name, profile, tag, or latest-run status, and page with an opaque cursor. Each item is a slim summary whose status reflects the latest run.

    Query Parameters

    NameTypeRequiredDescription
    phoneNumberstringoptionalFilter by exact phone number in E.164 format
    namestringoptionalFilter by case-insensitive substring of the job name
    profileIdstringoptionalFilter by profile id (UUID)
    tagstringoptionalFilter by a single lowercase tag (exact match)
    statusstringoptionalFilter by latest-run status: idle, running, completed, failed, or limited
    createdAfterstringoptionalOnly return jobs created at or after this ISO8601 datetime
    createdBeforestringoptionalOnly return jobs created at or before this ISO8601 datetime
    sortstringoptionalSort field. Only createdAt is supported (default)
    sortDirstringoptionalSort direction: asc or desc (default desc)
    limitnumberoptionalMaximum items to return, 1-100 (default 50)
    cursorstringoptionalOpaque pagination cursor from the previous response

    Request

    bash
    curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.nopaque.co.uk/mapping?status=completed&tag=production&limit=10"

    Response

    json
    {
  "items": [
    {
      "id": "map_abc123",
      "name": "Main IVR",
      "phoneNumber": "+441234567890",
      "status": "completed",
      "tags": [
        "production"
      ],
      "runNumber": 3,
      "profileId": "prof_xyz789",
      "createdAt": "2026-04-10T12: 00: 00Z",
      "updatedAt": "2026-04-10T12: 20: 00Z"
    }
  ],
  "nextCursor": null,
  "nextToken": null
}
    GET/mapping/{id}

    Get a specific mapping job by ID. When a run has started, the response includes runNumber and a nested currentRun with live status and stats. currentRun is omitted (never null) when the job has no runs.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Request

    bash
    curl -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123

    Response

    json
    {
  "id": "map_abc123",
  "name": "Main IVR",
  "phoneNumber": "+441234567890",
  "status": "completed",
  "mappingMode": "dtmf",
  "tags": [
    "production"
  ],
  "runNumber": 3,
  "currentRun": {
    "id": "run_def456",
    "status": "completed",
    "runNumber": 3,
    "stats": {
      "stepsTotal": 12,
      "stepsCompleted": 12
    },
    "inFlightCount": 0,
    "startedAt": "2026-04-10T12: 15: 00Z",
    "completedAt": "2026-04-10T12: 20: 00Z"
  },
  "createdAt": "2026-04-10T12: 00: 00Z",
  "updatedAt": "2026-04-10T12: 05: 00Z"
}
    POST/mapping

    Create a new mapping job.

    Body Parameters

    NameTypeRequiredDescription
    namestringrequiredDisplay name for the mapping job
    phoneNumberstringrequiredPhone number to map in E.164 format (e.g., +441234567890)
    mappingModestringrequiredMapping mode: dtmf, dtmf-audio, or full-audio
    profileIdstringoptionalProfile ID for voice-capable modes
    tagsstring[]optionalUp to 10 lowercase kebab-case tags (1-32 chars, pattern ^[a-z0-9][a-z0-9-]*$) for filtering and organisation

    Request

    bash
    curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Main IVR","phoneNumber":"+441234567890","mappingMode":"dtmf"}' \
  https://api.nopaque.co.uk/mapping

    Response

    json
    {
  "id": "map_abc123",
  "name": "Main IVR",
  "phoneNumber": "+441234567890",
  "mappingMode": "dtmf",
  "status": "created",
  "createdAt": "2026-04-10T12: 00: 00Z"
}
    PATCH/mapping/{id}

    Update a mapping job configuration.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Body Parameters

    NameTypeRequiredDescription
    namestringoptionalUpdated display name
    phoneNumberstringoptionalUpdated phone number in E.164 format
    mappingModestringoptionalUpdated mapping mode
    tagsstring[]optionalReplace the tag list. Up to 10 lowercase kebab-case tags (1-32 chars, pattern ^[a-z0-9][a-z0-9-]*$)

    Request

    bash
    curl -X PATCH -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated IVR Name"}' \
  https://api.nopaque.co.uk/mapping/map_abc123

    Response

    json
    {
  "id": "map_abc123",
  "name": "Updated IVR Name",
  "status": "created",
  "updatedAt": "2026-04-10T12: 10: 00Z"
}
    DELETE/mapping/{id}

    Delete a mapping job and all associated data.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Request

    bash
    curl -X DELETE -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123

    Response

    json
    {
  "message": "Mapping job deleted successfully"
}
    POST/mapping/{id}/start

    Start a mapping run for an existing job. Initiates phone calls to map the IVR tree.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Request

    bash
    curl -X POST -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/start

    Response

    json
    {
  "id": "map_abc123",
  "runId": "run_def456",
  "status": "running",
  "startedAt": "2026-04-10T12: 15: 00Z"
}
    POST/mapping/{id}/cancel

    Cancel a running mapping job.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Request

    bash
    curl -X POST -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/cancel

    Response

    json
    {
  "id": "map_abc123",
  "status": "cancelled",
  "cancelledAt": "2026-04-10T12: 20: 00Z"
}
    POST/mapping/attest

    Submit a security probe attestation for probe-enabled mapping jobs.

    Body Parameters

    NameTypeRequiredDescription
    jobIdstringrequiredMapping job ID

    Request

    bash
    curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobId":"map_abc123"}' \
  https://api.nopaque.co.uk/mapping/attest

    Response

    json
    {
  "attested": true
}
    GET/mapping/{id}/steps

    Get all orchestration steps for a mapping job.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Request

    bash
    curl -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/steps

    Response

    json
    {
  "items": [
    {
      "stepId": "step_001",
      "path": "/",
      "status": "completed",
      "dtmfOption": "1",
      "transcript": "Press 1 for sales..."
    }
  ]
}
    POST/mapping/{id}/remap/{path}

    Re-map a specific path within an existing mapping job.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID
    pathstringrequiredURL-encoded IVR tree path to remap (e.g., /1/3)

    Request

    bash
    curl -X POST -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/remap/%2F1%2F3

    Response

    json
    {
  "id": "map_abc123",
  "remapPath": "/1/3",
  "status": "running"
}
    GET/mapping/{id}/tree

    Get the IVR tree structure for a mapping job. Nodes carry enrichment fields (stepType, voicePrompt, menuLabel, spokenResponse, probe classification, audioUrl, duration, inputRequired) where available. When the job has no mapped tree yet, the endpoint returns 200 with an empty-state envelope { jobId, runId?, runNumber?, status, stats?, tree: null, reason, message } where reason is no_runs, no_steps, or in_progress. Branch on tree === null before reading root.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Request

    bash
    curl -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/tree

    Response

    json
    {
  "jobId": "map_abc123",
  "runNumber": 3,
  "root": {
    "path": "/",
    "stepType": "dtmf",
    "transcript": "Welcome to Acme Corp. Press 1 for sales, 2 for support.",
    "menuLabel": "Main menu",
    "audioUrl": "https://audio.nopaque.co.uk/map_abc123/root.mp3",
    "duration": 6.2,
    "children": [
      {
        "path": "/1",
        "dtmfOption": "1",
        "stepType": "dtmf",
        "menuLabel": "Sales",
        "transcript": "Sales department..."
      },
      {
        "path": "/2",
        "dtmfOption": "2",
        "stepType": "voice",
        "voicePrompt": "Please describe your issue.",
        "spokenResponse": "I need to reset my password.",
        "probeCategory": "authentication",
        "probeClassification": "weak",
        "probeRationale": "Resets identity with only a postcode.",
        "inputRequired": {
          "type": "voice",
          "description": "Spoken issue description"
        },
        "transcript": "Support department..."
      }
    ]
  }
}
    GET/mapping/{id}/runs

    List all runs for a mapping job. Runs may carry an optional callTelemetry object (schemaVersion 1) with nested telephony, quality, audio, cost, timing, mode, and per-turn detail. All telemetry fields are optional and may be absent.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Request

    bash
    curl -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/runs

    Response

    json
    {
  "jobId": "map_abc123",
  "runs": [
    {
      "id": "run_def456",
      "status": "completed",
      "startedAt": "2026-04-10T12: 15: 00Z",
      "completedAt": "2026-04-10T12: 20: 00Z"
    }
  ],
  "totalRuns": 1
}
    GET/mapping/{id}/paths

    List all discovered paths in a mapping job with path rule overrides.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID

    Request

    bash
    curl -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/paths

    Response

    json
    {
  "jobId": "map_abc123",
  "rules": [
    {
      "path": "/1",
      "status": "completed",
      "repeatBehavior": "skip"
    },
    {
      "path": "/2",
      "status": "completed",
      "repeatBehavior": "explore-once"
    }
  ],
  "totalRules": 2
}
    PATCH/mapping/{id}/paths/{path}

    Update a path rule override for a specific path in a mapping job.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID
    pathstringrequiredURL-encoded IVR tree path

    Body Parameters

    NameTypeRequiredDescription
    repeatBehaviorstringoptionalRepeat behavior: skip, explore-once, or explore-N

    Request

    bash
    curl -X PATCH -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repeatBehavior":"explore-once"}' \
  https://api.nopaque.co.uk/mapping/map_abc123/paths/%2F1

    Response

    json
    {
  "path": "/1",
  "repeatBehavior": "explore-once",
  "updatedAt": "2026-04-10T12: 25: 00Z"
}
    DELETE/mapping/{id}/paths/{path}

    Delete a path rule override, reverting to default behavior.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID
    pathstringrequiredURL-encoded IVR tree path

    Request

    bash
    curl -X DELETE -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/paths/%2F1

    Response

    json
    {
  "message": "Path rule deleted successfully"
}
    POST/mapping/{id}/runs/{runId}/probe

    Trigger on-demand security probe analysis on a completed mapping run. Queues probe steps and returns how many were enqueued.

    Path Parameters

    NameTypeRequiredDescription
    idstringrequiredMapping job ID
    runIdstringrequiredRun ID for the completed mapping run

    Request

    bash
    curl -X POST -H "x-api-key: YOUR_API_KEY" \
  https://api.nopaque.co.uk/mapping/map_abc123/runs/run_def456/probe

    Response

    json
    {
  "message": "Queued 3 security probe steps",
  "probeCount": 3
}