> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Lookup by phone number > Find the matching simulation using the number used by the Roark simulation agent. ## OpenAPI ````yaml /api-reference/openapi.documented.json get /v1/simulation/job/lookup openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Config - name: CLI Auth - name: Call Analysis - name: Health paths: /v1/simulation/job/lookup: get: tags: - Simulation Job summary: Lookup by phone number description: >- Find the matching simulation using the number used by the Roark simulation agent. operationId: getV1SimulationJobLookup parameters: - in: query name: roarkPhoneNumber schema: type: string required: true example: '+15551234567' description: >- Phone number provisioned by Roark for the simulation job in E.164 format. In the case of an inbound simulation, this is the number that calls your agent; in the case of an outbound simulation, this is the number you call from your agent. - in: query name: callReceivedAt schema: type: string format: date-time required: false example: '2024-01-15T10:30:00Z' description: >- ISO 8601 timestamp of when the call was received. Alternatively, any time between the start and end of the call is valid. Defaults to the current time, which fetches any jobs that are currently ongoing. responses: '200': description: Successfully found simulation job content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SimulationJobResponse' required: - data '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: No active lease or associated job found '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: >- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.simulationJob.lookup({ roarkPhoneNumber: 'roarkPhoneNumber' }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.simulation_job.lookup( roark_phone_number="roarkPhoneNumber", ) print(response.data) components: schemas: SimulationJobResponse: type: object properties: simulationJobId: type: string format: uuid description: Simulation job ID status: type: string description: Job status processingStatus: type: string description: Processing status callId: type: - string - 'null' format: uuid description: >- ID of the call created for this simulation job. Null if the call has not been created yet. roarkPhoneNumber: type: - string - 'null' description: >- Phone number provisioned by Roark for this simulation job in E.164 format. Null if the simulation job is queued and has not been assigned a phone number yet. runPlan: $ref: '#/components/schemas/SimulationRunPlanRef' enrichment: $ref: '#/components/schemas/SimulationJobEnrichment' invalidation: oneOf: - $ref: '#/components/schemas/SimulationJobInvalidation' - type: 'null' description: Null while the result counts. See SimulationJobInvalidation. persona: type: object properties: id: type: string format: uuid description: Unique identifier of the persona name: type: string description: The name the agent will identify as during conversations displayName: type: - string - 'null' description: >- Label shown in place of the name across the dashboard (e.g. a short descriptor like "Irate Escalator"). The persona still identifies as `name` on calls. Omit or set null to display the name itself. description: type: - string - 'null' description: Human-readable description of the persona language: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE description: Primary language ISO 639-1 code for the persona secondaryLanguage: type: - string - 'null' enum: - EN description: >- Secondary language ISO 639-1 code for code-switching (e.g., Hinglish, Spanglish) understoodLanguages: type: array items: type: string enum: - EN - ES - DE - HI - FR - NL - AR - EL - IT - ID - TH - JA - TL - MS - ZH - TR - PT - HE minItems: 1 description: >- Languages the persona can understand. Multilingual combinations are limited by multilingual speech recognition support. accent: type: string enum: - US - US_X_SOUTH - GB - ES - DE - IN - FR - NL - SA - GR - AU - IT - ID - TH - JP - NZ - PH - SG - MY - HK - TR - PT - IL description: >- Accent of the persona, defined using ISO 3166-1 alpha-2 country codes with optional variants age: type: string enum: - CHILD - TEENAGER - ADULT - ELDERLY default: ADULT description: >- How old the caller sounds and behaves. Only ages the persona's accent has a voice for are accepted; defaults to ADULT, which every accent supports. gender: type: string enum: - MALE - FEMALE description: Gender of the persona backgroundNoise: type: string enum: - NONE - AIRPORT - CHILDREN_PLAYING - CITY - COFFEE_SHOP - DRIVING - OFFICE - THUNDERSTORM default: NONE description: Background noise setting speechPace: type: string enum: - SUPER_SLOW - SLOW - NORMAL - FAST - SUPER_FAST default: NORMAL description: Speech pace of the persona speechClarity: type: string enum: - CLEAR - VAGUE - RAMBLING default: CLEAR description: Speech clarity of the persona hasDisfluencies: type: boolean default: false description: Whether the persona uses filler words like "um" and "uh" baseEmotion: type: string enum: - NEUTRAL - CHEERFUL - CONFUSED - FRUSTRATED - SKEPTICAL - RUSHED - DISTRACTED default: NEUTRAL description: Base emotional state of the persona intentClarity: type: string enum: - CLEAR - INDIRECT - VAGUE default: CLEAR description: How clearly the persona expresses their intentions confirmationStyle: type: string enum: - EXPLICIT - VAGUE default: EXPLICIT description: How the persona confirms information memoryReliability: type: string enum: - HIGH - LOW default: HIGH description: How reliable the persona's memory is responseTiming: type: string enum: - RELAXED - NORMAL - QUICK default: NORMAL description: >- Controls how quickly the persona responds to pauses in conversation (QUICK, NORMAL, RELAXED) backstoryPrompt: type: - string - 'null' description: Background story and behavioral patterns for the persona example: A busy professional calling during lunch break idleMessages: type: - array - 'null' items: type: string description: >- Messages the persona will say when the agent goes silent during a call. null = "Automatic": language-appropriate defaults are used at call time. idleTimeoutSeconds: type: integer minimum: 5 maximum: 60 default: 10 description: Seconds of silence before the persona sends an idle message idleMessageMaxSpokenCount: type: integer minimum: 1 maximum: 10 default: 3 description: >- Maximum number of idle messages the persona will send before giving up idleMessageResetCountOnUserSpeechEnabled: type: boolean default: true description: Whether the idle message counter resets when the agent speaks properties: type: object additionalProperties: {} default: {} description: Additional custom properties about the persona example: age: 35 zipCode: '94105' occupation: Software Engineer createdAt: type: string description: Creation timestamp updatedAt: type: string description: Last update timestamp required: - id - name - language - understoodLanguages - accent - age - gender - backgroundNoise - speechPace - speechClarity - hasDisfluencies - baseEmotion - intentClarity - confirmationStyle - memoryReliability - responseTiming - idleMessages - idleTimeoutSeconds - idleMessageMaxSpokenCount - idleMessageResetCountOnUserSpeechEnabled - properties - createdAt - updatedAt scenario: $ref: '#/components/schemas/ScenarioResponse' agentEndpoint: $ref: '#/components/schemas/AgentEndpointResponse' createdAt: type: string description: When the job was created startedAt: type: - string - 'null' description: When the job started completedAt: type: - string - 'null' description: When the job completed required: - simulationJobId - status - processingStatus - runPlan - enrichment - invalidation - persona - scenario - agentEndpoint - createdAt description: Simulation job with related entities example: simulationJobId: 7f3e4d2c-8a91-4b5c-9e6f-1a2b3c4d5e6f status: COMPLETED processingStatus: PROCESSED callId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 roarkPhoneNumber: '+15551234567' runPlan: id: b2c3d4e5-f6a7-8901-bcde-f12345678901 name: Billing Flow Test variables: promptToUse: v1 accountTier: premium enrichment: requested: true outcome: TIMED_OUT waitStartedAt: '2025-01-15T14:28:32.789Z' waitEndedAt: '2025-01-15T14:43:32.789Z' metricsScoredOnSimulationInstead: 4 metricsNotCollected: 1 invalidation: null persona: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: Sarah Johnson - Anxious Patient displayName: Anxious Patient language: EN secondaryLanguage: null understoodLanguages: - EN accent: US age: ADULT gender: FEMALE backgroundNoise: OFFICE speechPace: NORMAL speechClarity: CLEAR hasDisfluencies: false baseEmotion: FRUSTRATED intentClarity: CLEAR confirmationStyle: EXPLICIT memoryReliability: HIGH responseTiming: NORMAL backstoryPrompt: A busy professional calling during lunch break idleMessages: null idleTimeoutSeconds: 10 idleMessageMaxSpokenCount: 3 idleMessageResetCountOnUserSpeechEnabled: true properties: age: '35' zipCode: '94105' createdAt: '2025-01-10T12:00:00.000Z' updatedAt: '2025-01-10T12:00:00.000Z' scenario: id: f8e7d6c5-b4a3-9281-7069-5f4e3d2c1b0a description: >- Patient calling to schedule an urgent dental appointment due to severe tooth pain agentEndpoint: id: 3c2b1a09-8f7e-6d5c-4b3a-291807060504 name: PHONE phoneNumber: '+15555551234' type: PHONE createdAt: '2025-01-15T14:23:45.123Z' startedAt: '2025-01-15T14:24:15.456Z' completedAt: '2025-01-15T14:28:32.789Z' ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message SimulationRunPlanRef: type: object properties: id: type: string format: uuid description: Run plan ID name: type: string description: Run plan name variables: type: object additionalProperties: type: string description: >- Run-plan-level variables resolved for this job, keyed by variable name. Values are stringified by their declared type. required: - id - name - variables SimulationJobEnrichment: type: object properties: requested: type: boolean description: >- Whether the run plan asked for the customer's live conversation to be merged into this run. outcome: type: string enum: - NOT_REQUESTED - WAITING - MERGED - TIMED_OUT - SKIPPED - UNKNOWN description: >- How the wait for the live conversation resolved. `WAITING` means the run is holding open for it right now. `MERGED` means it arrived and live-sourced metrics were scored against it. `TIMED_OUT` and `SKIPPED` both mean it never arrived, so scoring fell back to the simulated side: read `metricsScoredOnSimulationInstead` and `metricsNotCollected` for what that cost. `UNKNOWN` is a run that finished before Roark started recording this. waitStartedAt: type: - string - 'null' description: >- When the run began holding open for the live conversation. Null if it never waited. waitEndedAt: type: - string - 'null' description: >- When the wait ended, however it ended. Null if it never waited or is still waiting. metricsScoredOnSimulationInstead: type: - integer - 'null' description: >- Metrics that asked for the live side and were scored against the simulated side because no live conversation arrived. Null on runs that predate this recording. metricsNotCollected: type: - integer - 'null' description: >- Metrics that only support the live side and so were not scored at all. Null on runs that predate this recording. required: - requested - outcome description: >- What happened to this run's live-conversation enrichment, and what scoring fell back to when none arrived. SimulationJobInvalidation: type: object properties: reason: type: string enum: - SCRIPT_DIVERGED description: >- Why the result does not count. `SCRIPT_DIVERGED`: a strict flow went off script at a step whose off-script policy is HANG_UP_INVALIDATE. detail: type: - string - 'null' description: >- One sentence: where the script was left and what your agent did instead. invalidatedAt: type: string description: When the run was invalidated. required: - reason - invalidatedAt description: >- Present when the run was invalidated: it keeps its transcript and recording, but nothing scored it and it is excluded from every run total. ScenarioResponse: type: object properties: id: type: string format: uuid description: Scenario ID description: type: - string - 'null' description: Scenario description required: - id description: Scenario used in a simulation AgentEndpointResponse: type: object properties: id: type: string format: uuid description: Agent endpoint ID name: type: string description: Agent endpoint name phoneNumber: type: - string - 'null' description: Agent endpoint phone number type: type: string enum: - PHONE - WEBSOCKET - LIVEKIT - SMALL_WEBRTC - ELEVENLABS_WS - KORE - GOOGLE_CES - DAILY description: Agent endpoint type required: - id - name - phoneNumber - type description: Agent endpoint used in a simulation securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````