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

List mapping jobs

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

Name	Type	Required	Description
phoneNumber	string	optional	Filter by exact phone number in E.164 format
name	string	optional	Filter by case-insensitive substring of the job name
profileId	string	optional	Filter by profile id (UUID)
tag	string	optional	Filter by a single lowercase tag (exact match)
status	string	optional	Filter by latest-run status: idle, running, completed, failed, or limited
createdAfter	string	optional	Only return jobs created at or after this ISO8601 datetime
createdBefore	string	optional	Only return jobs created at or before this ISO8601 datetime
sort	string	optional	Sort field. Only createdAt is supported (default)
sortDir	string	optional	Sort direction: asc or desc (default desc)
limit	number	optional	Maximum items to return, 1-100 (default 50)
cursor	string	optional	Opaque 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 a mapping job

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

Name	Type	Required	Description
id	string	required	Mapping 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"
}

Create a mapping job

POST/mapping

Create a mapping job. Creating does NOT start it — the job is created at status idle and you start it separately with POST /mapping/{id}/start. Every mode-related setting lives inside config, not at the top of the body.

Body Parameters

Name	Type	Required	Description
name	string	required	Display name for the mapping job
phoneNumber	string	required	Phone number to map in E.164 format (e.g., +441234567890)
profileId	string	optional	Data profile supplying scripted input values (account numbers, PINs) during the run
tags	string[]	optional	Up to 10 lowercase kebab-case tags (1-32 chars, pattern ^[a-z0-9][a-z0-9-]*$) for filtering and organisation
config	MappingJobConfig	required	Job configuration. Required, because config.mappingMode is required. A top-level mappingMode is ignored.
└ mappingMode	string	required	dtmf (keypad only), dtmf-audio (keypad + voice), or full-audio (voice first)
└ vertical	string	optional	FSI, Healthcare, EnergyUtilities, Telecoms, or General. REQUIRED whenever mappingMode is not dtmf; defaults to General for dtmf
└ probeMode	boolean	optional	Run security probes during exploration. Rejected in combination with mappingMode dtmf, and requires a prior POST /mapping/attest for the number
└ maxDepth	number	optional	Maximum tree depth to explore, 0-10 (0 = root only). Default 3
└ maxCalls	number	optional	Maximum total calls per run, 1-100. Default 50
└ maxDurationMinutes	number	optional	Maximum run duration in minutes, 1-60. Default 30
└ maxConcurrency	number	optional	Maximum concurrent calls, 1-5. Default 1
└ language	string	optional	Transcription language code (e.g. en-GB). Defaults to en-GB
└ voiceProfileId	string	optional	Voice profile used for TTS responses in dtmf-audio and full-audio modes
└ dataProfileId	string	optional	Data profile for variable substitution in scripted inputs
└ retryConfig	object	optional	Retry behaviour for failed calls: { enabled: boolean, maxRetries: number (1-5) }
└ repeatConfig	object	optional	Revisited-menu behaviour: { behavior: skip \| explore_once \| explore_n, maxExplorations?: number (1-10) }
└ enrichmentConfig	object	optional	Post-run enrichment: { enabled: boolean, types?: string[] }. Defaults to ["quality_scoring"]

Request

bash

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

Response

json

{
  "id": "map_abc123",
  "name": "Main IVR",
  "phoneNumber": "+441234567890",
  "status": "idle",
  "config": {
    "mappingMode": "dtmf",
    "vertical": "General",
    "language": "en-GB",
    "maxDepth": 4,
    "maxCalls": 30
  },
  "createdAt": "2026-04-10T12: 00: 00Z"
}

Update a mapping job

PATCH/mapping/{id}

Update a mapping job. config is merged over the existing config rather than replacing it, so send only the keys you are changing. Returns 400 if the job is currently running or queued.

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping job ID

Body Parameters

Name	Type	Required	Description
name	string	optional	Updated display name
phoneNumber	string	optional	Updated phone number in E.164 format
profileId	string	optional	Updated data profile. Send null to clear it
config	MappingJobConfig	optional	Partial config. Merged over the existing config server-side, so send only the keys you are changing. Same fields as on create, including mappingMode — which lives here, not at the top of the body
tags	string[]	optional	Replace the tag list. Up to 10 lowercase kebab-case tags (1-32 chars, pattern ^[a-z0-9][a-z0-9-]*$). Send [] to clear all tags

Request

bash

curl -X PATCH -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated IVR Name","config":{"maxCalls":60}}' \
  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 a mapping job

DELETE/mapping/{id}

Delete a mapping job and all associated data.

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping 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"
}

Start a mapping run

POST/mapping/{id}/start

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

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping 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"
}

Cancel a running job

POST/mapping/{id}/cancel

Cancel a running mapping job.

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping 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"
}

Attest a number

POST/mapping/attest

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

Body Parameters

Name	Type	Required	Description
jobId	string	required	Mapping 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
}

List the steps in a run

GET/mapping/{id}/steps

Get all orchestration steps for a mapping job.

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping 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..."
    }
  ]
}

Re-map a single path

POST/mapping/{id}/remap/{path}

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

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping job ID
path	string	required	URL-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 the menu tree

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

Name	Type	Required	Description
id	string	required	Mapping 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..."
      }
    ]
  }
}

List runs of a job

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

Name	Type	Required	Description
id	string	required	Mapping 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
}

List discovered paths

GET/mapping/{id}/paths

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

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping 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
}

Set a path rule

PATCH/mapping/{id}/paths/{path}

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

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping job ID
path	string	required	URL-encoded IVR tree path

Body Parameters

Name	Type	Required	Description
repeatBehavior	string	optional	Repeat 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 a path rule

DELETE/mapping/{id}/paths/{path}

Delete a path rule override, reverting to default behavior.

Path Parameters

Name	Type	Required	Description
id	string	required	Mapping job ID
path	string	required	URL-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"
}

Run security probes on a run

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

Name	Type	Required	Description
id	string	required	Mapping job ID
runId	string	required	Run 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
}